Создание провайдера свойств Windows PowerShell

В этой теме описывается, как создать провайдер, который позволяет пользователю управлять свойствами элементов в хранилище данных. В результате такой тип провайдера называют поставщиком свойств Windows PowerShell. Например, провайдер реестра, предоставляемый Windows PowerShell, обрабатывает значения ключей реестра как свойства элемента ключа реестра. Этот тип провайдера должен добавить интерфейс System.Management.Automation.Provider.IPropertyCmdletProvider к реализации класса .NET.

Замечание

Windows PowerShell предоставляет шаблонный файл, который можно использовать для разработки провайдера Windows PowerShell. Файл TemplateProvider.cs доступен в Microsoft Windows Software Development Kit for Windows Vista и компонентах выполнения .NET Framework 3.0. Инструкции по скачиванию смотрите в разделе «Как установить Windows PowerShell» и «Скачать Windows PowerShell SDK». Загруженный шаблон доступен в каталоге <PowerShell Samples> . Вам следует сделать копию этого файла и использовать его для создания нового провайдера Windows PowerShell, устранив ненужные функции. Для получения дополнительной информации о других реализациях провайдеров Windows PowerShell см. раздел «Проектирование вашего провайдера Windows PowerShell».

Caution

Методы вашего поставщика свойств должны записывать любые объекты с помощью метода System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* .

Определение провайдера Windows PowerShell

Поставщик свойств должен создать класс .NET, поддерживающий интерфейс System.Management.Automation.Provider.IPropertyCmdletProvider . Вот объявление класса по умолчанию из файла TemplateProvider.cs, предоставленного Windows PowerShell.

Определение базовой функциональности

Интерфейс System.Management.Automation.Provider.IPropertyCmdletProvider может быть подключён к любому из базовых классов провайдеров, за исключением класса System.Management.Automation.Provider.DriveCmdletProvider. Добавьте базовую функциональность, требуемую для используемого вами базового класса. Для получения дополнительной информации о базовых классах см. раздел «Проектирование вашего провайдера Windows PowerShell».

Извлечение свойств

Для получения свойств провайдер должен реализовать метод System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* для поддержки вызовов из Get-ItemProperty cmdlet. Этот метод извлекает свойства элемента, расположенного на указанном внутреннем пути провайдера (полностью квалифицированный).

Параметр providerSpecificPickList указывает, какие свойства нужно извлекать. Если этот параметр пуст null или пуст, метод должен получить все свойства. Кроме того, System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* записывает экземпляр объекта System.Management.Automation.PSObject , который представляет пакет свойств с полученными свойствами. Метод не должен ничего возвращать.

Рекомендуется, чтобы реализация System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* поддерживала wildcard расширение имён свойств для каждого элемента в списке выбора. Для этого используйте класс System.Management.Automation.WildcardPattern для сопоставления дикой карты.

Вот стандартная реализация System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* из файла TemplateProvider.cs, предоставленного Windows PowerShell.

Что нужно помнить при внедрении GetProperty

К вашей реализации System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* могут применяться следующие условия:

При определении класса провайдера поставщик свойств Windows PowerShell может объявить возможности провайдера ExpandWildcards, Filter, Include или Exclude из перечисления System.Management.Automation.Provider.ProviderCapabilities . В таких случаях реализация метода 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.Provider.CmdletProvider.Force* установлен в false.

Прикрепление динамических параметров к командоустройству Get-ItemProperty

Cmdlet Get-ItemProperty может потребовать дополнительных параметров, которые динамически задаются во время выполнения. Для предоставления этих динамических параметров поставщик свойств Windows PowerShell должен реализовать метод System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* . Параметр указывает на полностью квалифицированный внутренний путь провайдера, а providerSpecificPickList параметр указывает свойства, специфичные для провайдера, path введённые в командной строке. Этот параметр может быть null или пустым, если свойства передаются в cmdlet. В этом случае этот метод возвращает объект с свойствами и полями с атрибутами разбора, похожими на класс cmdlet или объект System.Management.Automation.RuntimeDefinedParameterDictionary . Runtime Windows PowerShell использует возвращённый объект для добавления параметров в cmdlet.

Вот стандартная реализация System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* из TemplateProvider.cs файла, предоставленного Windows PowerShell.

Установка свойств

Для установки свойств провайдер свойств Windows PowerShell должен реализовать метод System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* для поддержки вызовов из Set-ItemProperty cmdlet. Этот метод устанавливает одно или несколько свойств элемента на указанном пути и перезаписывает предоставленные свойства по мере необходимости. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* также записывает экземпляр объекта System.Management.Automation.PSObject , который представляет пакет свойств обновлённых свойств.

Вот стандартная реализация System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* из TemplateProvider.cs файла, предоставленного Windows PowerShell.

Что стоит помнить о внедрении Set-ItemProperty

К реализации System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* могут применяться следующие условия:

При определении класса провайдера поставщик свойств Windows PowerShell может объявить возможности провайдера ExpandWildcards, Filter, Include или Exclude из перечисления System.Management.Automation.Provider.ProviderCapabilities . В таких случаях реализация метода 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.Provider.CmdletProvider.Force* установлен в false.
Ваша реализация метода System.Management.Automation.Provider.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

Cmdlet Set-ItemProperty может потребовать дополнительных параметров, которые динамически задаются во время выполнения. Для предоставления этих динамических параметров поставщик свойств Windows PowerShell должен реализовать метод System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* . Этот метод возвращает объект с свойствами и полями с атрибутами разбора, похожими на класс cmdlet или объект System.Management.Automation.RuntimeDefinedParameterDictionary . null Значение может быть возвращено, если динамические параметры не добавляются.

Чистящие свойства

Для очистки свойств провайдер свойств Windows PowerShell должен реализовать метод System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* для поддержки вызовов из cmdlet Clear-ItemProperty . Этот метод задаёт одно или несколько свойств для элемента, расположенного на указанном пути.

Вот стандартная реализация System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* из файла TemplateProvider.cs, предоставленного Windows PowerShell.

Что нужно помнить при внедрении ClearProperty

К вашей реализации System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* могут применяться следующие условия:

При определении класса провайдера поставщик свойств Windows PowerShell может объявить возможности провайдера ExpandWildcards, Filter, Include или Exclude из перечисления System.Management.Automation.Provider.ProviderCapabilities . В таких случаях реализация метода 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.Provider.CmdletProvider.Force* установлен в false.
Ваша реализация метода System.Management.Automation.Provider.Provider.IPropertyCmdletProvider.ClearProperty* должна вызывать System.Management.Automation.Provider.CmdletProvider.ShouldProcess и проверять его возвращаемое значение перед внесением изменений в хранилище данных. Этот метод используется для подтверждения выполнения операции до внесения изменения состояния системы, например, очистки содержимого. System.Management.Automation.Provider.CmdletProvider.ShouldProcess отправляет пользователю имя ресурса для изменения, при этом среда выполнения Windows PowerShell учитывает любые командные строки или переменные предпочтений при определении того, что должно отображаться.

После вызова System.Management.Automation.Provider.Provider.CmdletProvider.ShouldProcess возвращается true, если возможны потенциально опасные системные изменения, метод System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* должен вызвать метод System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Этот метод отправляет пользователю подтверждающее сообщение, чтобы получить дополнительную обратную связь, указывающую на продолжение потенциально опасной операции.

Прикрепление динамических параметров к командоустройству Clear-ItemProperty

Cmdlet Clear-ItemProperty может потребовать дополнительных параметров, которые динамически задаются во время выполнения. Для предоставления этих динамических параметров поставщик свойств Windows PowerShell должен реализовать метод System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* . Этот метод возвращает объект с свойствами и полями с атрибутами разбора, похожими на класс cmdlet или объект System.Management.Automation.RuntimeDefinedParameterDictionary . null Значение может быть возвращено, если динамические параметры не добавляются.

Вот стандартная реализация System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* из файла TemplateProvider.cs, предоставленного Windows PowerShell.