Créer un fournisseur immobilier Windows PowerShell

Ce sujet décrit comment créer un fournisseur permettant à l’utilisateur de manipuler les propriétés des éléments dans un magasin de données. En conséquence, ce type de fournisseur est appelé fournisseur de biens Windows PowerShell. Par exemple, le fournisseur de registre fourni par Windows PowerShell gère les valeurs clés du registre comme propriétés de l’élément clé du registre. Ce type de fournisseur doit ajouter l’interface System.Management.Automation.Provider.IPropertyCmdletProvider à l’implémentation de la classe .NET.

Note

Windows PowerShell fournit un fichier modèle que vous pouvez utiliser pour développer un fournisseur Windows PowerShell. Le fichier TemplateProvider.cs est disponible sur le Microsoft Windows Software Development Kit pour Windows Vista et les composants d’exécution .NET Framework 3.0. Pour les instructions de téléchargement, consultez Comment installer Windows PowerShell et télécharger le SDK Windows PowerShell. Le modèle téléchargé est disponible dans le <répertoire PowerShell Samples> . Vous devriez faire une copie de ce fichier et utiliser cette copie pour créer un nouveau fournisseur Windows PowerShell, en supprimant toute fonctionnalité dont vous n’avez pas besoin. Pour plus d’informations sur les autres implémentations de fournisseurs Windows PowerShell, voir Designing Your Windows PowerShell Provider.

Caution

Les méthodes de votre fournisseur immobilier doivent écrire tout objet en utilisant la méthode System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* .

Définition du fournisseur PowerShell de Windows

Un fournisseur immobilier doit créer une classe .NET qui prend en charge l’interface System.Management.Automation.Provider.IPropertyCmdletProvider . Voici la déclaration de classe par défaut issue du fichier TemplateProvider.cs fourni par Windows PowerShell.

Définition de la fonctionnalité de base

L’interface System.Management.Automation.Provider.IPropertyCmdletProvider peut être connectée à n’importe quelle classe de base fournisseur, à l’exception de la classe System.Management.Automation.Provider.DriveCmdletProvider . Ajoutez la fonctionnalité de base requise par la classe de base que vous utilisez. Pour plus d’informations sur les classes de base, voir Designing Your Windows PowerShell Provider.

Récupération des propriétés

Pour récupérer des propriétés, le fournisseur doit implémenter la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* pour supporter les appels depuis le Get-ItemProperty cmdlet. Cette méthode récupère les propriétés de l’élément situé sur le chemin fournisseur-interne spécifié (entièrement qualifié).

Le providerSpecificPickList paramètre indique quelles propriétés récupérer. Si ce paramètre est null ou vide, la méthode devrait récupérer toutes les propriétés. De plus, System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* écrit une instance d’un objet System.Management.Automation.PSObject qui représente un sac de propriétés des propriétés récupérées. La méthode ne devrait rien retourner.

Il est recommandé que la mise en œuvre de System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* prenne en charge l’expansion en wildcard des noms de propriétés pour chaque élément de la liste de choix. Pour cela, utilisez la classe System.Management.Automation.WildcardPattern pour effectuer l’appariement de motifs jokers.

Voici l’implémentation par défaut de System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* à partir du fichier TemplateProvider.cs fourni par Windows PowerShell.

Choses à retenir concernant la mise en œuvre de GetProperty

Les conditions suivantes peuvent s’appliquer à votre implémentation de System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* :

Lors de la définition de la classe de fournisseur, un fournisseur de propriété Windows PowerShell peut déclarer les capacités fournisseurs ExpandWildcards, Filtrer, Inclure ou Exclure, de l’énumération System.Management.Automation.Provider.ProvidersCapabilities . Dans ces cas, la mise en œuvre de la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* doit garantir que le chemin transmis à la méthode répond aux exigences des capacités spécifiées. Pour cela, la méthode doit accéder à la propriété appropriée, par exemple les propriétés System.Management.Automation.Provider.CmdletProvider.Exclude* et System.Management.Automation.Provider.CmdletProvider.Include* propriétés.
Par défaut, les overrices de cette méthode ne devraient pas récupérer un lecteur pour les objets cachés à l’utilisateur, sauf si la propriété System.Management.Automation.Supplier.CmdletProvider.Force* est définie sur true. Une erreur doit être écrite si le chemin représente un élément caché à l’utilisateur et si System.Management.Automation.Provider.CmdletProvider.Force* est défini sur false.

Attacher des paramètres dynamiques au Get-ItemProperty cmdlet

Le Get-ItemProperty cmdlet peut nécessiter des paramètres supplémentaires spécifiés dynamiquement à l’exécution. Pour fournir ces paramètres dynamiques, le fournisseur de propriétés PowerShell de Windows doit implémenter la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* . Le path paramètre indique un chemin interne au fournisseur entièrement qualifié, tandis que le providerSpecificPickList paramètre spécifie les propriétés spécifiques au fournisseur saisies sur la ligne de commande. Ce paramètre peut être null vide ou vide si les propriétés sont envoyées par pip vers le cmdlet. Dans ce cas, cette méthode retourne un objet ayant des propriétés et des champs avec des attributs d’analyse similaires à une classe cmdlet ou à un objet System.Management.Automation.RuntimeDefinedParameterDictionary . L’exécution PowerShell de Windows utilise l’objet retourné pour ajouter les paramètres au cmdlet.

Voici l’implémentation par défaut de System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* à partir du fichier TemplateProvider.cs fourni par Windows PowerShell.

Définition de propriétés

Pour définir les propriétés, le fournisseur de propriétés PowerShell Windows doit implémenter la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* afin de supporter les appels depuis le Set-ItemProperty cmdlet. Cette méthode définit une ou plusieurs propriétés de l’élément sur le chemin spécifié, et écrase les propriétés fournies selon les besoins. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* écrit également une instance d’un objet System.Management.Automation.PSObject qui représente un sac de propriétés des propriétés mises à jour.

Voici l’implémentation par défaut de System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* à partir du fichier TemplateProvider.cs fourni par Windows PowerShell.

Choses à retenir concernant la mise en œuvre de Set-ItemProperty

Les conditions suivantes peuvent s’appliquer à une implémentation de System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* :

Lors de la définition de la classe de fournisseur, un fournisseur de propriété Windows PowerShell peut déclarer les capacités fournisseurs ExpandWildcards, Filtrer, Inclure ou Exclure, de l’énumération System.Management.Automation.Provider.ProvidersCapabilities . Dans ces cas, la mise en œuvre de la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* doit garantir que le chemin transmis à la méthode répond aux exigences des capacités spécifiées. Pour cela, la méthode doit accéder à la propriété appropriée, par exemple les propriétés System.Management.Automation.Provider.CmdletProvider.Exclude* et System.Management.Automation.Provider.CmdletProvider.Include* propriétés.
Par défaut, les overrices de cette méthode ne devraient pas récupérer un lecteur pour les objets cachés à l’utilisateur, sauf si la propriété System.Management.Automation.Supplier.CmdletProvider.Force* est définie sur true. Une erreur doit être écrite si le chemin représente un élément caché à l’utilisateur et si System.Management.Automation.Provider.CmdletProvider.Force* est défini sur false.
Votre implémentation de la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* doit appeler System.Management.Automation.Provider.CmdletProvider.ShouldProcess et vérifier sa valeur de retour avant d’effectuer toute modification du stockage de données. Cette méthode est utilisée pour confirmer l’exécution d’une opération lorsqu’un changement d’état système est effectué, par exemple le renommage de fichiers. System.Management.Automation.Provider.CmdletProvider.ShouldProcess envoie le nom de la ressource à changer à l’utilisateur, avec l’exécution Windows PowerShell et en gérant les paramètres en ligne de commande ou variables de préférence pour déterminer ce qui doit être affiché.

Après le retour truede l’appel à System.Management.Automation.Provider.CmdletProvider.ShouldProcess, si des modifications potentiellement dangereuses du système peuvent être effectuées, la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* doit appeler la méthode System.Management.Automation.Provider.CmdletProvider.ShouldContinue. Cette méthode envoie un message de confirmation à l’utilisateur pour permettre un retour supplémentaire indiquant que l’opération doit être poursuivie.

Attache des paramètres dynamiques pour le cmdlet Set-ItemProperty

Le Set-ItemProperty cmdlet peut nécessiter des paramètres supplémentaires spécifiés dynamiquement à l’exécution. Pour fournir ces paramètres dynamiques, le fournisseur de propriétés PowerShell Windows doit implémenter la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* . Cette méthode renvoie un objet ayant des propriétés et des champs avec des attributs d’analyse similaires à une classe cmdlet ou à un objet System.Management.Automation.RuntimeDefinedParameterDictionary . La null valeur peut être retournée si aucun paramètre dynamique ne doit être ajouté.

Propriétés de déminage

Pour effacer les propriétés, le fournisseur de propriétés Windows PowerShell doit implémenter la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* pour supporter les appels depuis le Clear-ItemProperty cmdlet. Cette méthode définit une ou plusieurs propriétés pour l’élément situé sur le chemin spécifié.

Voici l’implémentation par défaut de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* à partir du fichier TemplateProvider.cs fourni par Windows PowerShell.

Chose à retenir concernant la mise en œuvre de ClearProperty

Les conditions suivantes peuvent s’appliquer à votre implémentation de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* :

Lors de la définition de la classe de fournisseur, un fournisseur de propriété Windows PowerShell peut déclarer les capacités fournisseurs ExpandWildcards, Filtrer, Inclure ou Exclure, de l’énumération System.Management.Automation.Provider.ProvidersCapabilities . Dans ces cas, la mise en œuvre de la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* doit garantir que le chemin transmis à la méthode répond aux exigences des capacités spécifiées. Pour cela, la méthode doit accéder à la propriété appropriée, par exemple les propriétés System.Management.Automation.Provider.CmdletProvider.Exclude* et System.Management.Automation.Provider.CmdletProvider.Include* propriétés.
Par défaut, les overrices de cette méthode ne devraient pas récupérer un lecteur pour les objets cachés à l’utilisateur, sauf si la propriété System.Management.Automation.Supplier.CmdletProvider.Force* est définie sur true. Une erreur doit être écrite si le chemin représente un élément caché à l’utilisateur et si System.Management.Automation.Provider.CmdletProvider.Force* est défini sur false.
Votre implémentation de la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* doit appeler System.Management.Automation.Provider.CmdletProvider.ShouldProcess et vérifier sa valeur de retour avant d’apporter toute modification au magasin de données. Cette méthode est utilisée pour confirmer l’exécution d’une opération avant qu’un changement d’état du système ne soit effectué, comme l’effacement du contenu. System.Management.Automation.Provider.CmdletProvider.ShouldProcess envoie le nom de la ressource à changer à l’utilisateur, le runtime PowerShell de Windows tenant compte des paramètres en ligne de commande ou des variables de préférence pour déterminer ce qui doit être affiché.

Après le retour truede l’appel à System.Management.Automation.Provider.CmdletProvider.ShouldProcess, si des modifications potentiellement dangereuses du système peuvent être effectuées, la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* doit appeler la méthode System.Management.Automation.Provider.CmdletProvider.ShouldContinue. Cette méthode envoie un message de confirmation à l’utilisateur pour permettre un retour supplémentaire indiquant que l’opération potentiellement dangereuse doit être poursuivie.

Attacher des paramètres dynamiques au Clear-ItemProperty cmdlet

Le Clear-ItemProperty cmdlet peut nécessiter des paramètres supplémentaires spécifiés dynamiquement à l’exécution. Pour fournir ces paramètres dynamiques, le fournisseur de propriétés PowerShell Windows doit implémenter la méthode System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* . Cette méthode renvoie un objet ayant des propriétés et des champs avec des attributs d’analyse similaires à une classe cmdlet ou à un objet System.Management.Automation.RuntimeDefinedParameterDictionary . La null valeur peut être retournée si aucun paramètre dynamique ne doit être ajouté.

Voici l’implémentation par défaut de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* à partir du fichier TemplateProvider.cs fourni par Windows PowerShell.