Windows PowerShellプロパティプロバイダーの作成

このトピックでは、データストア内のアイテムのプロパティを操作できるプロバイダーの作成方法について説明します。そのため、この種のプロバイダーはWindows PowerShellプロパティプロバイダーと呼ばれます。例えば、Windows PowerShellが提供するレジストリプロバイダーは、レジストリキーの価値をレジストリキー項目のプロパティとして扱います。このタイプのプロバイダーは、.NETクラスの実装に System.Management.Automation.Provider.IPropertyCmdletProvider インターフェースを追加しなければなりません。

注

Windows PowerShellは、Windows PowerShellプロバイダーを開発するためのテンプレートファイルを提供しています。 TemplateProvider.csファイルはMicrosoft Windows Windows Software Development Kit for Windows Vistaおよび.NET Framework 3.0 Runtime Componentsで利用可能です。ダウンロード手順については、「 Windows PowerShellのインストール方法」および「Windows PowerShell SDKのダウンロード」をご覧ください。ダウンロードしたテンプレートは <PowerShell Samples> ディレクトリで利用可能です。このファイルのコピーを作成し、新しいWindowsのPowerShellプロバイダーを作成するために使うべきで、不要な機能は削除してください。他のWindows PowerShellプロバイダー実装の詳細については、「 Windows PowerShell Providerの設計」をご覧ください。

注意事項

プロパティプロバイダーのメソッドは、 System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* メソッドを使ってオブジェクトを書き込むべきです。

Windows PowerShell プロバイダーの定義

プロパティプロバイダーは、 System.Management.Automation.Provider.IPropertyCmdletProvider インターフェースをサポートする.NETクラスを作成しなければなりません。こちらはWindows PowerShellが提供するTemplateProvider.csファイルのデフォルトのクラス宣言です。

基本機能の定義

System.Management.Automation.Provider.IPropertyCmdletProviderインターフェースは、System.Management.Automation.Provider.DriveCmdletProviderクラスを除く任意のプロバイダーベースクラスにアタッチできます。使っているベースクラスに必要な基本機能を追加してください。ベースクラスの詳細については、「 Windows PowerShell Providerの設計」をご覧ください。

プロパティの取得

プロパティを取得するためには、プロバイダーはGet-ItemPropertyコマンドレットからの呼び出しをサポートするためにSystem.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*メソッドを実装する必要があります。このメソッドは指定されたプロバイダー内部パス(完全限定)にあるアイテムのプロパティを取得します。

providerSpecificPickListパラメータはどのプロパティを取得するかを示します。このパラメータが null または空であれば、メソッドはすべてのプロパティを取得する必要があります。さらに、 System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* は、取得したプロパティバッグを表す System.Management.Automation.PSObject オブジェクトのインスタンスを書き込みます。メソッドは何も返さないはずです。

System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*の実装は、ピックリスト内の各要素のプロパティ名のワイルドカード拡張をサポートすることが推奨されます。これを行うには、 System.Management.Automation.WildcardPattern クラスを使ってワイルドカードパターンマッチングを実行します。

こちらはWindows PowerShellが提供するTemplateProvider.csファイルからの System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* のデフォルト実装です。

GetPropertyの実装について覚えておくべきこと

System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*の実装には、以下の条件が適用される可能性があります:

プロバイダークラスを定義する際、Windows PowerShellプロパティプロバイダーは System.Management.Automation.Provider.ProviderCapabilities 列挙からExpandWildcards、Filter、Include、またはExcludeのプロバイダー能力を宣言することがあります。この場合、 System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* メソッドの実装は、そのメソッドに渡されるパスが指定された能力の要件を満たしていることを保証する必要があります。これを行うには、メソッドは適切なプロパティにアクセスする必要があります。例えば、System.Management.Automation.Provider.CmdletProvider.Exclude* や System.Management.Automation.Provider.CmdletProvider.Include* プロパティなどです。
デフォルトでは、このメソッドのオーバーライドは、 System.Management.Automation.Provider.CmdletProvider.Force* プロパティが trueに設定されていない限り、ユーザーから隠されたオブジェクトのリーダーを取得しません。パスがユーザーから隠されたアイテムを表し、 System.Management.Automation.Provider.CmdletProvider.Force* が falseに設定されている場合、エラーを書くべきです。

Get-ItemProperty コマンドレットへの動的パラメータの付与

Get-ItemPropertyコマンドレットは実行時に動的に指定される追加パラメータを必要とする場合があります。これらの動的パラメータを提供するために、Windows PowerShellプロパティプロバイダーは System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* メソッドを実装しなければなりません。 pathパラメータは完全に限定されたプロバイダー内部パスを示し、providerSpecificPickListパラメータはコマンドラインに入力されるプロバイダー固有のプロパティを指定します。このパラメータは、プロパティがコマンドレットにパイプされている場合、 null か空になることがあります。この場合、このメソッドはコマンドレットクラスや System.Management.Automation.RuntimeDefinedParameterDictionary オブジェクトに似た解析属性を持つプロパティとフィールドを持つオブジェクトを返します。 Windows PowerShellランタイムは、返されたオブジェクトを使ってパラメータをコマンドレットに追加します。

こちらはWindowsPowerShellが提供するTemplateProvider.csファイルからの System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* のデフォルト実装です。

プロパティの設定

プロパティを設定するには、Windows PowerShellプロパティプロバイダーが System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* メソッドを実装し、 Set-ItemProperty コマンドレットからの呼び出しをサポートする必要があります。このメソッドは指定されたパスでアイテムの1つ以上のプロパティを設定し、必要に応じて提供されたプロパティを上書きします。 System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* は、更新されたプロパティバッグを表す System.Management.Automation.PSObject オブジェクトのインスタンスも書きます。

こちらはWindowsPowerShellが提供するTemplateProvider.csファイルからの System.Management.Automation.Provider.IPropertyCmdlet.SetProperty* のデフォルト実装です。

Set-ItemProperty を導入する際に覚えておくべきこと

System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*の実装には、以下の条件が適用される可能性があります:

プロバイダークラスを定義する際、Windows PowerShellプロパティプロバイダーは System.Management.Automation.Provider.ProviderCapabilities 列挙からExpandWildcards、Filter、Include、またはExcludeのプロバイダー能力を宣言することがあります。このような場合、 System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* メソッドの実装は、そのメソッドに渡されるパスが指定された能力の要件を満たすことを保証しなければなりません。これを行うには、メソッドは適切なプロパティにアクセスする必要があります。例えば、System.Management.Automation.Provider.CmdletProvider.Exclude* や System.Management.Automation.Provider.CmdletProvider.Include* プロパティなどです。
デフォルトでは、このメソッドのオーバーライドは、 System.Management.Automation.Provider.CmdletProvider.Force* プロパティが trueに設定されていない限り、ユーザーから隠されたオブジェクトのリーダーを取得しません。パスがユーザーから隠されたアイテムを表し、 System.Management.Automation.Provider.CmdletProvider.Force* が falseに設定されている場合、エラーを書くべきです。
System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*メソッドの実装は、データストアに変更を加える前にSystem.Management.Automation.Provider.CmdletProvider.ShouldProcessを呼び出して返り値を確認するべきです。この方法は、システム状態に変更があった場合、例えばファイル名の変更など、操作の実行を確認するために使用されます。 System.Management.Automation.Provider.CmdletProvider.ShouldProcess は、変更するリソース名をユーザーに送信し、Windows PowerShellランタイムでコマンドライン設定や優先変数を管理し、表示すべき内容を決定します。

System.Management.Automation.Provider.CmdletProvider.ShouldProcessへの呼び出し後、潜在的に危険なシステム変更が可能な場合、System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*メソッドはSystem.Management.Automation.Provider.CmdletProvider.ShouldContinue メソッドを呼び出すべきです。この方法は、操作を継続すべきかを示す追加のフィードバックをユーザーに送信します。

Set-ItemProperty コマンドレットの動的パラメータの付与

Set-ItemPropertyコマンドレットは実行時に動的に指定される追加パラメータを必要とする場合があります。これらの動的パラメータを提供するために、Windows PowerShellプロパティプロバイダーは System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* メソッドを実装しなければなりません。このメソッドは、コマンドレットクラスや System.Management.Automation.RuntimeDefinedParameterDictionary オブジェクトに似た解析属性を持つプロパティやフィールドを持つオブジェクトを返します。動的パラメータを追加しなければ、 null 値を返すことができます。

クリアリングプロパティ

プロパティをクリアするには、Windows PowerShellプロパティプロバイダーが System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* メソッドを実装し、 Clear-ItemProperty コマンドレットからの呼び出しをサポートする必要があります。このメソッドは指定されたパスにあるアイテムに対して1つ以上のプロパティを設定します。

こちらはWindowsPowerShellが提供するTemplateProvider.csファイルからの System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* のデフォルト実装です。

ClearPropertyの導入について覚えておくべきこと

System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*の実装には、以下の条件が適用される場合があります:

プロバイダークラスを定義する際、Windows PowerShellプロパティプロバイダーは System.Management.Automation.Provider.ProviderCapabilities 列挙からExpandWildcards、Filter、Include、またはExcludeのプロバイダー能力を宣言することがあります。このような場合、 System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* メソッドの実装は、そのメソッドに渡されるパスが指定された能力の要件を満たしていることを保証する必要があります。これを行うには、メソッドは適切なプロパティにアクセスする必要があります。例えば、System.Management.Automation.Provider.CmdletProvider.Exclude* や System.Management.Automation.Provider.CmdletProvider.Include* プロパティなどです。
デフォルトでは、このメソッドのオーバーライドは、 System.Management.Automation.Provider.CmdletProvider.Force* プロパティが trueに設定されていない限り、ユーザーから隠されたオブジェクトのリーダーを取得しません。パスがユーザーから隠されたアイテムを表し、 System.Management.Automation.Provider.CmdletProvider.Force* が falseに設定されている場合、エラーを書くべきです。
System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*メソッドの実装は、データストアに変更を加える前にSystem.Management.Automation.Provider.CmdletProvider.ShouldProcessを呼び出し、返却値を検証すべきです。この方法は、システム状態の変更(例えばコンテンツのクリア)を行う前に操作の実行を確認するために使用されます。 System.Management.Automation.Provider.CmdletProvider.ShouldProcess は、変更するリソース名をユーザーに送信し、Windows PowerShellランタイムはコマンドラインの設定や好み変数を考慮して表示すべき内容を決定します。

System.Management.Automation.Provider.CmdletProvider.ShouldProcessへの呼び出し後、true返すと、潜在的に危険なシステム変更が可能な場合は、System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*メソッドがSystem.Management.Automation.Provider.CmdletProvider.ShouldContinue メソッドを呼び出すべきです。この方法は、潜在的に危険な操作を継続すべきかを示す追加のフィードバックをユーザーに送信します。

Clear-ItemProperty コマンドレットへの動的パラメータの付与

Clear-ItemPropertyコマンドレットは実行時に動的に指定される追加パラメータを必要とする場合があります。これらの動的パラメータを提供するために、Windows PowerShellプロパティプロバイダーは System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* メソッドを実装しなければなりません。このメソッドは、コマンドレットクラスや System.Management.Automation.RuntimeDefinedParameterDictionary オブジェクトに似た解析属性を持つプロパティやフィールドを持つオブジェクトを返します。動的パラメータを追加しなければ、 null 値を返すことができます。

こちらはWindowsPowerShellが提供するTemplateProvider.csファイルからの System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* のデフォルト実装です。