Directives de développement pour les applets de commande SharePoint Foundation
Dernière modification : mercredi 24 mars 2010
S’applique à : SharePoint Foundation 2010
Lorsque vous écrivez des applets de commande Windows PowerShell pour SharePoint, c’est-à-dire des applets de commande personnalisées qui dérivent de la classe de base SPCmdlet, assurez-vous d’utiliser les instructions de conception spécifiques à SharePoint, de façon à ce que vos applets de commande soient entièrement compatibles avec les applets de commande de la bibliothèque d’applets de commande de SharePoint exposées dans SharePoint Management Shell. En outre, SharePoint Foundation recommande des modèles de conception qui assurent une totale interopérabilité avec votre déploiement SharePoint.
Méthodologie pour la création d’applets de commande SharePoint
Lorsque vous concevez des applets de commande spécifiques à SharePoint, procédez toujours comme suit :
Définissez les noms des applets de commande.
Définissez les noms des propriétés des applets de commande.
Définissez les verbes et les paramètres des applets de commande.
Définissez les erreurs, la progression et le pipeline de vos applets de commande.
Si vous suivez ce processus, le résultat sera une définition complète de l’ensemble des applets de commande pour le composant ou la fonctionnalité que vous développez.
Définir les noms des applets de commande
Lorsque vous définissez un nom d’applet de commande, soyez explicite quant à ce que votre fonctionnalité va gérer. Pensez aux noms comme à des éléments qu’un administrateur système va gérer. Il peut s’agir d’objets SharePoint, tels que SPSite ou SPWeb, ou de fonctionnalités installées, telles que des objets SPFeature, des modèles de formulaires ou des composants WebPart.
Une règle générale est qu’il est préférable d’avoir un plus grand nombre de noms avec moins de propriétés qu’un plus petit nombre de noms avec beaucoup plus de propriétés. Un nom avec plus de 15 propriétés est surchargé.
Identifiez les informations d’état d’exécution non persistantes que vous voulez exposer aux administrateurs système. Identifiez aussi les informations d’état qui peuvent ne pas être conservées, mais qui doivent néanmoins être retournées aux administrateurs système (par exemple, l’état d’exécution d’un service).
Déterminez si un nom nouvellement défini peut être séparé en deux noms différents ou plus. Créez des noms séparés pour les éléments qui sont sémantiquement distincts. Utilisez les spécifications de la fonctionnalité ou du composant pour déterminer si un nom recouvre plusieurs concepts ou fonctionnalités.
Si un nom couvre plusieurs sources de données (physiques ou logiques), divisez le nom selon les limites des sources de données. Identifiez un sous-ensemble de propriétés logiquement indépendant qui est conservé dans une même base de données ou dans un même objet SharePoint. Dans la plupart des cas, ce sous-ensemble devient un nom distinct, mais seulement si les noms résultants sont logiquement indépendants, et seulement s’ils peuvent être clairement compris comme des entités distinctes (c’est-à-dire facilement séparées) sans entraîner de confusion pour les administrateurs système.
Pour chaque objet de source de données persistantes qui est utilisé par plus d’un nom, unifiez ces noms en un seul nom. Unifiez aussi les noms dont la principale différence est qu’ils ont des durées de vie différentes car leur création et leur suppression peuvent être gérées séparément.
Définir les propriétés des noms des applets de commande
Définissez une propriété Identity. Tous les noms doivent avoir une propriété Identity dont la valeur est unique et immuable, telle qu’un GUID.
Créez un pipebind pour le nom. Le pipebind doit combiner toutes les propriétés qui peuvent identifier l’objet de façon univoque.
Définissez l’ensemble complet des propriétés publiques pour le nom. Traitez la définition du nom comme s’il s’agissait d’une API publique. Toutes les propriétés publiques associées sont exposées dans la ligne de commande lorsqu’une instance du nom est retournée.
Définissez un type de données pour chaque propriété. Les propriétés doivent être fortement typées pour que le code de validation du format puisse être attaché au type de propriété plutôt qu’au nom. Par exemple, une propriété qui représente une adresse de messagerie doit être du type EmailAddress plutôt que du type String.
Identifiez les propriétés de taille inhabituellement importante. Assurez-vous que ces propriétés (supérieures à 10 Ko) sont divisées en deux propriétés ou plus.
Identifiez les propriétés qui ont un grand nombre d’éléments (par exemple une collection de plus de 100 éléments). Supprimez les collections de propriétés aussi importantes et répartissez les éléments dans des noms distincts. Ensuite, définissez les verbes New, Remove, Get et Set pour les nouveaux noms.
Par exemple, considérons un scénario dans lequel Users est une propriété d’un objet SPWeb, qui peut avoir un grand nombre d’éléments. Pour éviter des problèmes, créez un nom distinct appelé SPUser qui représente un élément de la liste, puis ajoutez les verbes New, Remove, Get et Set associés.
Définir les verbes et les paramètres des applets de commande
Déterminez les verbes de base (Get, Set, New, Remove) qui s’appliquent à votre nom. Au minimum, les administrateurs système doivent pouvoir obtenir des paramètres et les modifier (ou les définir, via Set). En outre, les administrateurs peuvent aussi avoir besoin de créer de nouvelles instances (New) et de supprimer des instances existantes (Remove).
Définissez le comportement de votre applet de commande Get.
Le verbe Get doit récupérer toutes les instances si aucun paramètre n’est spécifié, et il doit le faire en écrivant les instances dans le pipeline Windows PowerShell. Cependant, toute opération susceptible de retourner un jeu de résultats volumineux doit inclure un paramètre Limit sur lequel est spécifiée une limite par défaut. Bien sûr, si vous limitez un jeu de résultats de cette façon, vous devez avertir les utilisateurs que des résultats supplémentaires sont susceptibles d’être exclus du jeu de résultats limité.
Le verbe Get doit avoir un paramètre Identity. Lorsqu’il est spécifié, l’applet de commande correspondante doit retourner seulement l’instance associée à cette identité. Si l’identité spécifiée n’est pas unique, l’applet de commande doit retourner toutes les instances qui ont la valeur d’identité spécifiée.
Le verbe Get peut avoir des paramètres de filtrage facultatifs supplémentaires. Par exemple, l’applet de commande Get-SPSite peut avoir un paramètre ContentDatabase qui limite le jeu de résultats aux collections de sites qui se trouvent dans une base de données de contenu spécifiée. En outre, le verbe Get doit avoir un paramètre Server si l’applet de commande retourne des informations de configuration locales (c’est-à-dire spécifiques à un ordinateur).
Définissez le comportement de l’applet de commande Set.
Le verbe Set doit avoir un paramètre Identity pour identifier l’instance qui doit être modifiée. Le paramètre doit pouvoir prendre une identité (par exemple un GUID) ou un nom. Si un nom est spécifié et que ce nom correspond à plusieurs instances, l’applet de commande doit renvoyer une erreur.
Le paramètre Identity de l’applet de commande Set doit accepter une entrée via un pipeline.
Le verbe Set doit exposer toutes les propriétés du nom accessibles en écriture qui sont reçues à l’aide de l’applet de commande Get correspondante, excepté celles qui ont des effets négatifs lorsqu’elles sont définies.
Le verbe Set doit avoir un paramètre Instance facultatif qui représente une instance complète de ce type de nom. Le paramètre Instance doit aussi accepter une entrée via un pipeline (par valeur).
Définissez le comportement de l’applet de commande New.
Le verbe New doit prendre comme paramètre un sous-ensemble limité des propriétés du nom accessibles en écriture. Les propriétés restantes doivent être définies à des valeurs par défaut. En outre, l’applet de commande New doit retourner l’objet d’instance nouvellement créé dans le pipeline de façon à ce que des applets de commande ultérieurs puissent agir sur la nouvelle instance.
Définissez le comportement de l’applet de commande Remove.
Votre applet de commande Remove doit avoir un paramètre Identity qui peut prendre une valeur d’identité ou un nom. Si un nom est spécifié et que ce nom correspond à plusieurs instances, l’applet de commande doit renvoyer une erreur.
Le paramètre Identity doit accepter une entrée via un pipeline. En outre, toute opération de suppression doit prendre en charge les paramètres Confirm et WhaIf. Ceci demande peu de travail car Windows PowerShell et les classes de base de SharePoint Foundation 2010 offrent les moyens de prendre en charge ces paramètres.
Identifiez et définissez des verbes supplémentaires pour le nom.
Par exemple, un nom SPContentDatabase peut nécessiter un verbe Mount pour prendre en charge le montage d’une base de données spécifiée. Utilisez des scénarios d’administration et des cas d’utilisation bien testés pour faciliter la sélection des verbes appropriés.
Rappelez-vous que toutes les applets de commande supplémentaires doivent avoir un paramètre Identity qui accepte les entrées via un pipeline. Le paramètre Identity doit accepter l’identité (PipeBind) de l’objet. En outre, toute opération de suppression doit prendre en charge les paramètres Confirm et WhaIf.
Identifiez les propriétés qui ont des effets de bord potentiels négatifs.
Les propriétés qui ont des effets de bord potentiels négatifs peuvent nécessiter des opérations supplémentaires pour limiter ces effets négatifs. Ces applets de commande supplémentaires de limitation doivent avoir un paramètre Identity qui accepte les entrées via un pipeline.
Pour chaque applet de commande que vous définissez, effectuez les actions suivantes :
(a) Identifiez la liste des conditions préalables requises pour l’applet de commande. Par exemple, dans un cas où une applet de commande peut être exécutée seulement dans un certain état du système, l’applet doit vérifier que toutes les conditions préalables requises pour l’état sont satisfaites avant de s’exécuter.
(b) Identifiez la liste des opérations. Spécifiez la liste complète des opérations que l’applet de commande est capable d’exécuter. L’applet de commande doit exécuter puis valider ces opérations. Cette liste des opérations comprend la décomposition fonctionnelle de l’applet de commande.
Définissez les erreurs, la progression et le pipeline des applets de commande.
Identifiez toutes les conditions d’erreur et les comportements liés aux états d’erreur. En d’autres termes, établissez la liste de toutes les conditions dans lesquelles une applet de commande peut aboutir à une erreur. Ensuite, pour chaque condition, décrivez le comportement attendu. Vos applets de commande doivent fournir une gestion d’erreur de base.
Vos applets de commande doivent annuler les modifications partielles lorsqu’une erreur se produit, et elles doivent retourner un message d’erreur significatif (et localisé si nécessaire). En outre, les applets de commande doivent déterminer et indiquer comment un administrateur système peut effectuer une récupération depuis n’importe quelle condition d’erreur.
Différenciez les erreurs amenant la fin de l’exécution de celles qui n’amènent pas la fin de l’exécution.
Identifiez les opérations dont l’exécution est longue. Si la durée d’exécution d’une opération par une applet de commande est prévue pour être supérieure en moyenne à environ vingt secondes, l’applet de commande doit fournir des informations de progression pour éviter que l’opération apparaisse comme étant en suspens.
Assurez-vous que les applets de commande écrivent leurs objets renvoyés directement dans le pipeline. Évitez de mettre en mémoire tampon les objets récupérés dans un tableau interne. L’écriture dans le pipeline permet aux applets de commande intervenant plus tard dans le flux d’agir sans retard sur des objets précédents dans le pipeline.
Regroupez les paramètres similaires. Limitez les applets de commande à 16 paramètres (en dehors des paramètres Identity et Name). Dans les cas où les méthodes des objets sont rarement appelées et où il existe une méthode du modèle objet, aucun paramètre d’applet de commande n’est nécessaire. Dans les cas où un grand nombre de paramètres peuvent être regroupés, écrivez un seul paramètre acceptant l’objet de groupe.
Voir aussi
Concepts
Gestion des erreurs pour les applets de commande SharePoint Foundation
Introduction aux applets de commande pour SharePoint Management Shell