Concepts clés pour l’écriture d’applets de commande pour SharePoint Management Shell

Dernière modification : jeudi 1 octobre 2009

S’applique à : SharePoint Foundation 2010

Dans cet article
Paramètres des applets de commande
Pipelines et mise en pipeline
Objets PipeBind

Il existe plusieurs concepts clés qui sont opératoires lorsque vous écrivez des applets de commande Windows PowerShell pour SharePoint. Bien que n’étant pas exhaustif, le contenu qui suit décrit quelques-uns des concepts importants qui sous-tendent l’implémentation de Windows PowerShell pour SharePoint.

Paramètres des applets de commande

Bien que les utilisateurs entrent les valeurs des paramètres en tant que chaînes, Windows PowerShell tente de convertir ces valeurs de chaîne dans leur type correct, sur la base de la définition des paramètres. Ainsi, les applets de commande que vous écrivez doivent fournir un moyen de vérifier que les valeurs des paramètres qui sont passées à l’applet de commande sont d’un type de données valide.

Évitez de passer des paramètres de type chaîne ou entier, à moins que toutes les valeurs de ce type soient valides pour le paramètre. Au lieu de cela, définissez une classe qui limite davantage la plage et le format des paramètres. Validez aussi les paramètres à l’aide la méthode Parse(String) du type de paramètre. Windows PowerShell prend en charge l’utilisation de la méthode Parse() pour convertir un type de chaîne en d’autres types de de données.

Pipelines et mise en pipeline

Parmi les améliorations les plus significatives offertes par Windows PowerShell par rapport aux capacités de Cmd.exe figure la possibilité pour Windows PowerShell de combiner en mode natif une série d’applets de commande simples en un pipeline, qui est une série (ou séquence) de commandes. Le pipeline permet à des objets en sortie d’une commande d’être passés (ou mis en pipeline) en tant qu’objets en entrée aux commandes suivantes. Les pipelines de commandes permettent aux développeurs d’applets de commande de créer des pipelines de commandes complexes et souples, dont les objets en sortie peuvent être enregistrés et réutilisés.

Le processus de mise en pipeline repose sur le comportement des applets de commande, où les objets en sortie sont écrits dans un pipeline d’objets qui est contrôlé par Windows PowerShell. Ceci permet à Windows PowerShell d’essayer de faire correspondre l’objet du pipeline avec les paramètres de l’applet de commande suivante.

Pour que la mise en pipeline fonctionne, il doit y avoir une correspondance explicite entre la sortie de l’applet de commande précédente et l’entrée des applets de commande suivantes. Cette correspondance peut être au niveau de l’objet, où l’objet précédent dans le pipeline correspond à un paramètre de l’applet de commande suivante. (Ceci s’appelle mise en œuvre de pipeline par valeur.) La correspondance peut également se produire au niveau de la propriété, où les propriétés de l’objet précédent correspondent aux paramètres de l’applet de commande suivante.

Mise en œuvre de pipeline par valeur

La mise en œuvre de pipeline par valeur signifie qu’une applet de commande en aval dans le flux consommera la totalité d’un objet provenant du pipeline, à condition que l’objet soit du type correct. La mise en œuvre de pipeline par valeur se fait généralement via l’utilisation d’applets de commande Set, où le fait de passer un objet tout entier permet d’économiser une opération de lecture depuis une source de données, ainsi que via l’utilisation d’applets de commande New qui prennent en charge le clonage. La mise en œuvre de pipeline par valeur est également utilisée dans les cas où l’applet de commande en aval dans le flux ne peut pas relire l’objet qui est produit en sortie par l’applet de commande en amont dans le flux.

Objets PipeBind

Les objets PipeBind sont des objets spéciaux qui sont uniques à Windows PowerShell pour SharePoint et qui fournissent une deuxième couche d’ensembles de paramètres spécialisés qui sont optimisés pour SharePoint Foundation.

Lorsque vous utilisez des objets SharePoint Foundation 2010 en tant que paramètres d’applet de commande, vous devez utiliser l’objet PipeBind approprié à la place de l’objet SharePoint. Ceci est essentiel car cela permet à l’utilisateur de l’applet de commande de spécifier la valeur du paramètre de façon appropriée. L’objet PipeBind représente en fait une couche qui se trouve entre l’entrée de l’utilisateur pour un paramètre et l’objet du paramètre lui-même.

Par exemple, une applet de commande qui prend un paramètre SPSite peut prendre l’objet SPSite lui-même, ou l’identificateur GUID pour cette collection de sites, ou encore l’URL de la collection de sites. C’est la responsabilité de l’objet SPSitePipeBind de s’assurer que, quelle que soit la représentation présentée par l’environnement d’exécution Windows PowerShell, l’applet de commande elle-même est présentée avec l’objet SPSite réel.

Implémentation d’un objet PipeBind

Lors de l’implémentation d’un objet PipeBind, vous devez procéder par dérivation depuis la classe de base SPCmdletPipeBind<TCmdletObject>. Pour implémenter cette classe, procédez comme suit :

1. Implémentez le constructeur de la classe.

2. Remplacez la méthode Read() de l’objet.

La classe PipeBind doit avoir au moins un constructeur, même si elle peut en avoir davantage. Lorsque Windows PowerShell essaie de lier des paramètres, il procède par itération à travers l’ensemble des constructeurs publics pour un paramètre spécifié et tente de faire correspondre l’entrée du paramètre avec un constructeur PipeBind. Cela signifie que pour chaque type possible d’entrée représentant un paramètre, il doit exister un constructeur correspondant.

La méthode Read() sur l’objet SPCmdletPipeBind<TCmdletObject> retourne le type d’objet qui est défini dans le modèle objet SharePoint Foundation : public virtual TCmdletObject Read().

Notez que la méthode Read() doit être remplacée pour chaque implémentation d’objet PipeBind de façon à garantir que chaque objet du modèle objet est correctement récupéré. Vous pouvez créer des remplacements supplémentaires de la méthode Read() autant que nécessaire pour fournir les paramètres requis.

Identité et atomicité des applets de commande

Les applets de commande doivent avoir un paramètre Identity qui spécifie l’objet sur lequel il faut agir. Lorsque vous écrivez des applets de commande, vous devez spécifier un identificateur unique en tant que valeur pour le paramètre Identity. Notez cependant que les nouvelles applets de commande n’ont pas initialement d’identificateur ; l’identificateur d’un objet ne peut exister qu’après son instanciation.

L’exécution des applets de commande doit simuler l’atomicité. En d’autres termes, une applet de commande doit ou bien réussir et amener le système à un état modifié, ou bien échouer et ramener le système à l’état où il se trouvait avant son exécution. Les applets de commande doivent donc fournir une méthode permettant de restaurer l’état du système en cas d’échec.