sp_addextendedproperty (Transact-SQL)

Article
12/15/2008

Mis à jour : 5 décembre 2005

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

Icône Lien de rubrique Conventions de la syntaxe de 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 :
Les types de niveau 0 USER et TYPE seront éliminés dans une version ultérieure de SQL Server. Évitez d'utiliser ces fonctions dans un nouveau travail de développement et prévoyez la modification des applications qui les utilisent actuellement. Utilisez SCHEMA comme type de niveau 0 à la place de USER. Pour TYPE, utilisez 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, 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.

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 des objets de n'importe quel niveau.

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

Dans les versions antérieures de SQL Server, les utilisateurs détenaient des objets de base de données, tels que des tables, des vues et des déclencheurs. Il était dès lors possible d'ajouter une propriété étendue à ces objets et de spécifier un nom d'utilisateur en tant que type de niveau 0. Cependant, dans SQL Server 2005, les objets de base de données sont contenus dans des schémas, et sont indépendants des utilisateurs propriétaires de ces schémas.

Dans SQL Server 2005, 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 ambiguité de résolution de noms. Par exemple, supposez que l'utilisateur Marie détient deux schémas (Marie et MySchema) et que ceux-ci contiennent tous deux une table intitulée MyTable. Si Marie ajoute une propriété étendue à la table MyTable et spécifie @level0type = N'USER',@level0name = Marie, il n'apparaît pas clairement à quelle table la propriété étendue est appliquée. Afin de garantir une compatibilité descendante, SQL Server appliquera la propriété à la table contenue dans le schéma intitulé Marie. 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 la restriction suivante : le rôle db_ddladmin ne peut pas ajouter de propriétés à la base de données elle-même, aux utilisateurs ou aux 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.

Valeurs des codes renvoyés

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

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 'AdventureWorks Sample OLTP Database' pour valeur à la base de données exemple AdventureWorks.

USE AdventureWorks;
GO
--Add a caption to the AdventureWorks Database object itself.
EXEC sp_addextendedproperty 
@name = N'Caption', @value = 'AdventureWorks 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 AdventureWorks;
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 AdventureWorks;
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 AdventureWorks;
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample', 
@value = N'Primary filegroup for the AdventureWorks sample database.', 
@level0type = N'FILEGROUP', @level0name = [PRIMARY];
GO

Voir aussi

Historique des modifications

Version	Historique
5 décembre 2005	Nouveau contenu : La section Réplication des propriétés étendues a été ajoutée.