Partager via


sp_addextendedproperty (Transact-SQL)

Ajoute une nouvelle propriété étendue à un objet de base de données.

Icône Lien de rubriqueConventions de syntaxe Transact-SQL

Syntaxe

        sp_addextendedproperty
    [ @name= ] { 'property_name' }
    [ , [ @value= ] { 'value' } 
        [ , [ @level0type= ] { 'level0_object_type' } 
          , [ @level0name= ] { 'level0_object_name' } 
                [ , [ @level1type= ] { 'level1_object_type' } 
                  , [ @level1name= ] { 'level1_object_name' } 
                        [ , [ @level2type= ] { 'level2_object_type' } 
                          , [ @level2name= ] { 'level2_object_name' } 
                        ] 
                ]
        ] 
    ] 
[;]

Arguments

  • [ @name ] = { 'property_name' }
    Nom de la propriété à ajouter. L'argument property_name est de type sysname et ne peut pas être NULL. Les noms peuvent également comporter des chaînes de caractères vides ou non alphanumériques, ainsi que des valeurs binaires.

  • [ @value= ] { 'value'}
    Valeur à associer à la propriété. L'argument value est de type sql_variant, avec NULL comme valeur par défaut. La taille de l'argument value ne peut pas dépasser les 7 500 octets.

  • [ @level0type= ] { 'level0_object_type' }
    Type de l'objet de niveau 0. L'argument level0_object_type est de type varchar(128), avec NULL comme valeur par défaut.

    Les entrées valides sont ASSEMBLY, CONTRACT, EVENT NOTIFICATION, FILEGROUP, MESSAGE TYPE, PARTITION FUNCTION, PARTITION SCHEME, REMOTE SERVICE BINDING, ROUTE, SCHEMA, SERVICE, USER, TRIGGER, TYPE et NULL.

    Important

    La possibilité de spécifier USER en tant que type de niveau 0 dans une propriété étendue d'un objet de type de niveau 1 sera supprimée dans la future version de SQL Server. Utilisez à la place SCHEMA en tant que type de niveau 0. Par exemple, lorsque vous définissez une propriété étendue d'une table, spécifiez le schéma de la table, au lieu d'un nom d'utilisateur. La possibilité de spécifier TYPE en tant que type de niveau 0 sera supprimée dans la future version de SQL Server. Pour TYPE, choisissez SCHEMA comme type de niveau 0, et TYPE comme type de niveau 1.

  • [ @level0name= ] { 'level0_object_name' }
    Nom du type d'objet de niveau 0 spécifié. L'argument level0_object_name est de type sysname, avec NULL comme valeur par défaut.

  • [ @level1type= ] { 'level1_object_type' }
    Type de l'objet de niveau 1. L'argument level1_object_type est de type varchar(128), avec NULL comme valeur par défaut. Les entrées valides sont AGGREGATE, DEFAULT, FUNCTION, LOGICAL FILE NAME, PROCEDURE, QUEUE, RULE, SYNONYM, TABLE_TYPE, TYPE, VIEW, XML SCHEMA COLLECTION et NULL.

  • [ @level1name= ] { 'level1_object_name' }
    Nom du type d'objet de niveau 1 spécifié. L'argument level1_object_name est de type sysname, avec NULL comme valeur par défaut.

  • [ @level2type= ] { 'level2_object_type' }
    Type de l'objet de niveau 2. L'argument level2_object_type est de type varchar(128), avec NULL comme valeur par défaut. Les entrées valides sont COLUMN, CONSTRAINT, EVENT NOTIFICATION, INDEX, PARAMETER, TRIGGER et NULL.

  • [ @level2name= ] { 'level2_object_name' }
    Nom du type d'objet de niveau 2 spécifié. L'argument level2_object_name est de type sysname, avec NULL comme valeur par défaut.

Valeurs des codes de retour

0 (réussite) ou 1 (échec)

Notes

Les objets d'une base de données SQL Server sont répartis sur trois niveaux (0, 1 et 2) pour la définition des propriétés étendues. Le niveau 0 est le plus élevé et est défini en tant qu'objets contenus dans l'étendue de la base de données. Les objets de niveau 1 sont contenus dans une étendue de schéma ou d'utilisateur, tandis que les objets de niveau 2 sont contenus dans des objets de niveau 1. Vous pouvez définir des propriétés étendues pour les objets de tous ces niveaux.

Les références à un objet d'un niveau donné doivent être qualifiées par les noms des objets de niveau supérieur possédant ou contenant l'objet en question. Par exemple, lorsque vous ajoutez une propriété étendue à une colonne de table (niveau 2), vous devez également indiquer le nom de la table (niveau 1) qui contient la colonne et le schéma (niveau 0) qui contient la table.

Pour une liste complète des objets et leurs types valides de niveau 0, 1 et 2, consultez Utilisation de propriétés étendues sur les objets de base de données.

Si tous les types et noms d'objet sont NULL, la propriété appartient à la base de données active.

Les propriétés étendues ne sont pas autorisées sur les objets système, les objets se trouvant en dehors de l'étendue d'une base de données définie par l'utilisateur ou les objets non répertoriés dans les arguments comme des entrées valides.

Réplication des propriétés étendues

Les propriétés étendues sont répliquées uniquement lors de la synchronisation initiale entre le serveur de publication et l'Abonné. Si vous ajoutez ou modifiez une propriété étendue après la synchronisation initiale, la modification n'est pas répliquée. Pour plus d'informations sur la réplication des objets de base de données, consultez Publication de données et d'objets de base de données.

Schéma ou Utilisateur

Nous ne vous recommandons pas de spécifier l'argument USER comme type de niveau 0 lorsque vous appliquez une propriété étendue à un objet de base de données, car vous pourriez engendrer une ambiguïté de résolution de noms. Par exemple, supposons que l'utilisateur Mary détienne deux schémas (Mary et MySchema) et que ceux-ci contiennent tous les deux une table nommée MyTable. Si Mary ajoute une propriété étendue à la table MyTable et spécifie @level0type = N'USER', @level0name = Mary, il n'apparaît pas clairement à quelle table la propriété étendue est appliquée. Pour assurer la compatibilité descendante, SQL Server applique la propriété étendue à la table contenue dans le schéma nommé Mary. Pour plus d'informations sur les utilisateurs et les schémas, consultez Séparation du schéma et de l'utilisateur.

Autorisations

Les membres des rôles de base de données fixes db_owner et db_ddladmin peuvent ajouter des propriétés étendues à n'importe quel objet, avec toutefois l'exception suivante : db_ddladmin ne peut pas ajouter de propriétés à la base de données elle-même, ni aux utilisateurs ou rôles.

Les utilisateurs peuvent ajouter des propriétés étendues à des objets qu'ils possèdent ou pour lesquels ils bénéficient d'autorisations ALTER ou CONTROL. Pour obtenir une liste complète des autorisations requises, consultez Utilisation de propriétés étendues sur les objets de base de données.

Exemples

A. Ajout d'une propriété étendue à une base de données

L'exemple suivant ajoute la propriété intitulée 'Caption' et ayant 'AdventureWorks2008R2 Sample OLTP Database' pour valeur à la base de données exemple AdventureWorks2008R2.

USE AdventureWorks2008R2;
GO
--Add a caption to the AdventureWorks2008R2 Database object itself.
EXEC sp_addextendedproperty 
@name = N'Caption', 
@value = 'AdventureWorks2008R2 Sample OLTP Database';

B. Ajout d'une propriété étendue à une colonne dans une table

L'exemple suivant ajoute une propriété de légende à la colonne PostalCode dans la table Address.

USE AdventureWorks2008R2;
GO
EXEC sp_addextendedproperty 
@name = N'Caption', 
@value = 'Postal code is a required column.',
@level0type = N'Schema', @level0name = 'Person',
@level1type = N'Table',  @level1name = 'Address',
@level2type = N'Column', @level2name = 'PostalCode';
GO

C. Ajout d'une propriété de masque de saisie à une colonne

L'exemple suivant ajoute la propriété de masque de saisie 99999 or 99999-9999 or #### ### à la colonne PostalCode dans la table Address.

USE AdventureWorks2008R2;
GO
EXEC sp_addextendedproperty 
@name = N'Input Mask ', @value = '99999 or 99999-9999 or #### ###',
@level0type = N'Schema', @level0name = 'Person',
@level1type = N'Table', @level1name = 'Address', 
@level2type = N'Column',@level2name = 'PostalCode';
GO

D. Ajout d'une propriété étendue à un groupe de fichiers

Dans l'exemple suivant, une propriété étendue est ajoutée au groupe de fichiers PRIMARY.

USE AdventureWorks2008R2;
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample', 
@value = N'Primary filegroup for the AdventureWorks2008R2 sample database.', 
@level0type = N'FILEGROUP', @level0name = 'PRIMARY';
GO

E. Ajout d'une propriété étendue à un schéma

Dans l'exemple suivant, une propriété étendue est ajoutée au schéma HumanResources.

USE AdventureWorks2008R2;
GO
EXECUTE sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample',
@value = N'Contains objects related to employees and departments.',
@level0type = N'SCHEMA', 
@level0name = 'HumanResources';

F. Ajout d'une propriété étendue à une table

Dans l'exemple ci-dessous, une propriété étendue est ajoutée à la table Address dans le schéma Person.

USE AdventureWorks2008R2;
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample', 
@value = N'Street address information for customers, employees, and vendors.', 
@level0type = N'SCHEMA', @level0name = 'Person',
@level1type = N'TABLE',  @level1name = 'Address';
GO

G. Ajout d'une propriété étendue à un rôle

Dans l'exemple suivant, un rôle d'application est créé et une propriété étendue y est ajoutée.

USE AdventureWorks2008R2; 
GO
CREATE APPLICATION ROLE Buyers
WITH Password = '987G^bv876sPY)Y5m23'; 
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_Description', 
@value = N'Application Role for the Purchasing Department.',
@level0type = N'USER',
@level0name = 'Buyers';

H. Ajout d'une propriété étendue à un type

Dans l'exemple suivant, une propriété étendue est ajoutée à un type.

USE AdventureWorks2008R2; 
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_Description', 
@value = N'Data type (alias) to use for any column that represents an order number. For example a sales order number or purchase order number.', 
@level0type = N'SCHEMA', 
@level0name = N'dbo', 
@level1type = N'TYPE', 
@level1name = N'OrderNumber';

I. Ajout d'une propriété étendue à un utilisateur

Dans l'exemple suivant, un utilisateur est créé et une propriété étendue y est ajoutée.

USE AdventureWorks2008R2; 
GO
CREATE USER CustomApp WITHOUT LOGIN ; 
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_Description', 
@value = N'User for an application.', 
@level0type = N'USER', 
@level0name = N'CustomApp';