建立 Windows PowerShell 屬性提供者

本主題說明如何建立一個提供者，讓使用者能操作資料儲存中項目的屬性。因此，這類提供者被稱為 Windows PowerShell 屬性提供者。例如，Windows PowerShell 提供的登錄檔提供者會將登錄檔鍵值視為登錄檔鍵項的屬性。這類提供者必須在 .NET 類別的實作中加入 System.Management.Automation.Provider.IPropertyCmdletProvider 介面。

備註

Windows PowerShell 提供了一個範本檔案，你可以用來開發 Windows PowerShell 提供者。 TemplateProvider.cs檔案可在 Windows Vista Microsoft 軟體開發套件及 .NET Framework 3.0 執行時元件中取得。如需下載說明，請參閱《如何安裝 Windows PowerShell》及《Download the Windows PowerShell SDK》。下載的範本可在 <PowerShell 範例> 目錄中取得。你應該複製這個檔案，並用它來建立新的 Windows PowerShell 提供者，移除不需要的功能。欲了解更多關於其他 Windows PowerShell 提供者實作的資訊，請參閱「設計您的 Windows PowerShell 提供者」。

謹慎

你的屬性提供者的方法應該會使用 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 提供者。

取得資產

要取得屬性，提供者必須實作 System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* 方法來支援 cmdlet 的 Get-ItemProperty 呼叫。此方法會取得位於指定提供者內部路徑（完全限定路徑）的項目屬性。

參數表示 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 列舉中的 ExpandWildcard、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 空的。此時，此方法回傳一個具有屬性與欄位的物件，解析屬性類似於 cmdlet 類別或 System.Management.Automation.RuntimeDefinedParameterDictionary 物件。 Windows PowerShell 執行時會使用回傳的物件來將參數加入 cmdlet。

這是 Windows PowerShell 提供的 TemplateProvider.cs 檔案中 System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* 的預設實作。

設定屬性

要設定屬性，Windows PowerShell 屬性提供者必須實作 System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* 方法，以支援從 cmdlet 呼叫 Set-ItemProperty 。此方法會在指定路徑上設定一個或多個物件的屬性，並視需要覆蓋所提供的屬性。 System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* 也會寫入一個 System.Management.Automation.PSObject 物件的實例，代表更新後屬性的屬性袋。

這是 Windows PowerShell 提供的 TemplateProvider.cs 檔案中 System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* 的預設實作。

實施 Set-ItemProperty 時需要注意的事項

以下條件可能適用於 System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* 的實作：

在定義提供者類別時，Windows PowerShell 屬性提供者可能會宣告 System.Management.Automation.Provider.ProviderCapabilities 列舉中的 ExpandWildcard、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 回傳 true後，如果系統可能進行潛在危險的修改， System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* 方法應呼叫 System.Management.Automation.Provider.CmdletProvider.ShouldContinue 方法。此方法會向使用者發送確認訊息，允許額外回饋以指示操作是否應該繼續。

為 Set-ItemProperty 指令小子附加動態參數

Set-ItemProperty指令長可能會在執行時動態指定額外參數。為了提供這些動態參數，Windows PowerShell 屬性提供者必須實作 System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* 方法。此方法回傳一個物件，其屬性與欄位的解析屬性類似於 cmdlet 類別或 System.Management.Automation.RuntimeDefinedParameterDictionary 物件。若不需加入動態參數，則可回傳該 null 值。

這是 Windows PowerShell 提供的 TemplateProvider.cs 檔案中 System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* 的預設實作。

清算性質

要清除屬性，Windows PowerShell 屬性提供者必須實作 System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* 方法，以支援指令長的 Clear-ItemProperty 呼叫。此方法為位於指定路徑的項目設定一個或多個屬性。

這是 Windows PowerShell 提供的 TemplateProvider.cs 檔案中 System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* 的預設實作。

關於實施 ClearProperty 需要記住的一點

以下條件可能適用於您對 System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* 的實作：

在定義提供者類別時，Windows PowerShell 屬性提供者可能會宣告 System.Management.Automation.Provider.ProviderCapabilities 列舉中的 ExpandWildcard、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* 方法。此方法回傳一個物件，其屬性與欄位的解析屬性類似於 cmdlet 類別或 System.Management.Automation.RuntimeDefinedParameterDictionary 物件。若不需加入動態參數，則可回傳該 null 值。

這是 Windows PowerShell 提供的 TemplateProvider.cs 檔案中 System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* 的預設實作。