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

2025-03-25

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

Примечание.

Windows PowerShell предоставляет файл шаблона, который можно использовать для разработки поставщика Windows PowerShell. Файл TemplateProvider.cs доступен в пакете средств разработки программного обеспечения Microsoft Windows для Windows Vista и .NET Framework 3.0. Инструкции по скачиванию см. в статье Установка Windows PowerShell и скачивание пакета SDK для Windows PowerShell. Скачанный шаблон доступен в каталоге>примеров PowerShell<. Необходимо сделать копию этого файла и использовать копию для создания нового поставщика Windows PowerShell, удаляя все функциональные возможности, которые не требуются. Дополнительные сведения о других реализациях поставщика Windows PowerShell см. в статье Проектированиепоставщика Windows PowerShell.

Осторожность

Методы поставщика свойств должны записывать любые объекты с помощью метода System.Management.Automation.Provider.КомандлетProvider.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. Этот метод извлекает свойства элемента, расположенного по указанному внутреннему пути поставщика (полностью).

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

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

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

Сведения о реализации GetProperty

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

При определении класса поставщика поставщик свойств Windows PowerShell может объявлять возможности поставщика расширений, фильтров, включения или исключения из перечисления System.Management.Automation.Provider.ProviderCapabilities. В таких случаях реализация метода System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* должна убедиться, что путь, передаваемый методу, соответствует требованиям указанных возможностей. Для этого метод должен получить доступ к соответствующему свойству, например к свойствам System.Management.Automation.Provider.КомандлетProvider.Exclude* и System.Management.Automation.Provider.КомандлетProvider.Include*.
По умолчанию переопределения этого метода не должны извлекать средство чтения для объектов, скрытых от пользователя, если свойство System.Management.Automation.Provider.CmdletProvider.Force* имеет значение true. Ошибка должна быть записана, если путь представляет элемент, скрытый от пользователя, и System.Management.Automation.Provider.КомандлетProvider.Force* имеет значение false.

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

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

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

Настройка свойств

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

После вызова System.Management.Automation.Provider.КомандлетProvider.ShouldProcess возвращает true, если могут быть сделаны потенциально опасные изменения системы, метод System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* метод должен вызвать метод System.Management.Automation.Provider.Командлет.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. Этот метод задает одно или несколько свойств для элемента, расположенного по указанному пути.

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

Важно помнить о реализации ClearProperty

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

При определении класса поставщика поставщик свойств Windows PowerShell может объявлять возможности поставщика расширений, фильтров, включения или исключения из перечисления System.Management.Automation.Provider.ProviderCapabilities. В таких случаях реализация метода System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* должна гарантировать, что путь, передаваемый методу, соответствует требованиям указанных возможностей. Для этого метод должен получить доступ к соответствующему свойству, например к свойствам System.Management.Automation.Provider.КомандлетProvider.Exclude* и System.Management.Automation.Provider.КомандлетProvider.Include*.
По умолчанию переопределения этого метода не должны извлекать средство чтения для объектов, скрытых от пользователя, если свойство System.Management.Automation.Provider.CmdletProvider.Force* имеет значение true. Ошибка должна быть записана, если путь представляет элемент, скрытый от пользователя, и System.Management.Automation.Provider.КомандлетProvider.Force* имеет значение false.
Реализация метода System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* должна вызывать System.Management.Automation.Provider.КомандлетProvider.ShouldProcess, прежде чем вносить изменения в хранилище данных. Этот метод используется для подтверждения выполнения операции перед изменением состояния системы, например очистка содержимого. System.Management.Automation.Provider.КомандлетProvider.ShouldProcess отправляет имя ресурса, которое необходимо изменить пользователю, при этом среда выполнения Windows PowerShell учитывает все параметры командной строки или переменные предпочтения при определении того, что нужно отобразить.

После вызова System.Management.Automation.Provider.КомандлетProvider.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 можно вернуть, если динамические параметры не добавляются.

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