Creación de un proveedor de propiedades Windows PowerShell

Este tema describe cómo crear un proveedor que permita al usuario manipular las propiedades de los elementos en un almacén de datos. Como consecuencia, este tipo de proveedor se denomina proveedor de propiedades Windows PowerShell. Por ejemplo, el proveedor de registro proporcionado por Windows PowerShell gestiona los valores clave del registro como propiedades del elemento clave del registro. Este tipo de proveedor debe añadir la interfaz System.Management.Automation.Provider.IPropertyCmdletProvider a la implementación de la clase .NET.

Nota:

Windows PowerShell proporciona un archivo plantilla que puedes usar para desarrollar un proveedor de PowerShell para Windows. El archivo TemplateProvider.cs está disponible en el Microsoft Windows Software Development Kit para Windows Vista y los componentes de ejecución de .NET Framework 3.0. Para las instrucciones de descarga, consulta Cómo instalar Windows PowerShell y descargar el SDK de Windows PowerShell. La plantilla descargada está disponible en el <directorio de Ejemplos> de PowerShell. Deberías hacer una copia de este archivo y usarla para crear un nuevo proveedor de PowerShell para Windows, eliminando cualquier funcionalidad que no necesites. Para más información sobre otras implementaciones de proveedores de Windows PowerShell, consulte Diseñando su proveedor de PowerShell para Windows.

Precaución

Los métodos de tu proveedor inmobiliario deben escribir cualquier objeto usando el método System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* .

Definición del proveedor PowerShell de Windows

Un proveedor de propiedades debe crear una clase .NET que soporte la interfaz System.Management.Automation.Provider.IPropertyCmdletProvider . Aquí está la declaración de clase predeterminada del archivo TemplateProvider.cs proporcionado por Windows PowerShell.

Definición de la funcionalidad base

La interfaz System.Management.Automation.Provider.IPropertyCmdletProvider puede conectarse a cualquiera de las clases base de provider, excepto a la clase System.Management.Automation.Provider.DriveCmdletProvider . Añade la funcionalidad base que requiere la clase base que estás usando. Para más información sobre las clases base, consulte Diseñando su proveedor de PowerShell para Windows.

Recuperación de propiedades

Para recuperar propiedades, el proveedor debe implementar el método System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* para soportar llamadas desde el Get-ItemProperty cmdlet. Este método recupera las propiedades del elemento ubicado en la ruta interna del proveedor especificada (totalmente cualificada).

El providerSpecificPickList parámetro indica qué propiedades recuperar. Si este parámetro está null o está vacío, el método debería recuperar todas las propiedades. Además, System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* escribe una instancia de un objeto System.Management.Automation.PSObject que representa una bolsa de propiedades de las propiedades recuperadas. El método no debería devolver nada.

Se recomienda que la implementación de System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* soporte la expansión comodina de los nombres de propiedades para cada elemento de la lista de selección. Para ello, utiliza la clase System.Management.Automation.WildcardPattern para realizar la coincidencia de patrones comodines.

Aquí está la implementación predeterminada de System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* del archivo TemplateProvider.cs proporcionado por Windows PowerShell.

Cosas a recordar sobre la implementación de GetProperty

Las siguientes condiciones pueden aplicarse a tu implementación de System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty*:

Al definir la clase de proveedor, un proveedor de propiedades Windows PowerShell podría declarar capacidades de proveedor de ExpandWildcards, Filtrar, Incluir o Excluir, de la enumeración System.Management.Automation.Provider.ProviderCapabilities . En estos casos, la implementación del método System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* debe garantizar que la ruta que se le pasa al método cumpla con los requisitos de las capacidades especificadas. Para ello, el método debe acceder a la propiedad adecuada, por ejemplo, las propiedades System.Management.Automation.Provider.CmdletProvider.Exclude* y System.Management.Automation.Provider.CmdletProvider.Include* .
Por defecto, las sobrescrituras de este método no deberían recuperar un lector para objetos ocultos al usuario a menos que la propiedad System.Management.Automation.Provider.CmdletProvider.Force* esté configurada en true. Se debe escribir un error si la ruta representa un elemento oculto al usuario y System.Management.Automation.Provider.CmdletProvider.Force* está configurado como false.

Adjuntar parámetros dinámicos al Get-ItemProperty cmdlet

El Get-ItemProperty cmdlet puede requerir parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de propiedades de Windows PowerShell debe implementar el método System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* . El path parámetro indica un camino interno del proveedor totalmente cualificado, mientras que especifica providerSpecificPickList las propiedades específicas del proveedor introducidas en la línea de comandos. Este parámetro puede estar null vacío si las propiedades se canalizan al cmdlet. En este caso, este método devuelve un objeto que tiene propiedades y campos con atributos de análisis similar a una clase cmdlet o un objeto System.Management.Automation.RuntimeDefinedParameterDictionary . El entorno de ejecución de Windows PowerShell utiliza el objeto devuelto para añadir los parámetros al cmdlet.

Aquí está la implementación predeterminada de System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* del archivo TemplateProvider.cs proporcionado por Windows PowerShell.

Establecer propiedades

Para establecer propiedades, el proveedor de propiedades de Windows PowerShell debe implementar el método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* para soportar llamadas desde el Set-ItemProperty cmdlet. Este método establece una o más propiedades del elemento en el camino especificado y sobrescribe las propiedades suministradas según sea necesario. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* también escribe una instancia de un objeto System.Management.Automation.PSObject que representa una bolsa de propiedades de las propiedades actualizadas.

Aquí está la implementación predeterminada de System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* del archivo TemplateProvider.cs proporcionado por Windows PowerShell.

Cosas a recordar sobre la implementación de Set-ItemProperty

Las siguientes condiciones pueden aplicarse a una implementación de System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*:

Al definir la clase de proveedor, un proveedor de propiedades Windows PowerShell podría declarar capacidades de proveedor de ExpandWildcards, Filtrar, Incluir o Excluir, de la enumeración System.Management.Automation.Provider.ProviderCapabilities . En estos casos, la implementación del método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* debe garantizar que la ruta que se transmite al método cumpla con los requisitos de las capacidades especificadas. Para ello, el método debe acceder a la propiedad adecuada, por ejemplo, las propiedades System.Management.Automation.Provider.CmdletProvider.Exclude* y System.Management.Automation.Provider.CmdletProvider.Include* .
Por defecto, las sobrescrituras de este método no deberían recuperar un lector para objetos ocultos al usuario a menos que la propiedad System.Management.Automation.Provider.CmdletProvider.Force* esté configurada en true. Se debe escribir un error si la ruta representa un elemento oculto al usuario y System.Management.Automation.Provider.CmdletProvider.Force* está configurado como false.
Tu implementación del método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* debe llamar a System.Management.Automation.Provider.CmdletProvider.ShouldProcess y verificar su valor de retorno antes de realizar cualquier cambio en el almacén de datos. Este método se utiliza para confirmar la ejecución de una operación cuando se realiza un cambio en el estado del sistema, por ejemplo, renombrar archivos. System.Management.Automation.Provider.CmdletProvider.ShouldProcess envía el nombre del recurso a cambiar al usuario, con el entorno de ejecución de Windows PowerShell y gestionando cualquier configuración de línea de comandos o variable de preferencia para determinar qué debe mostrarse.

Tras la llamada a System.Management.Automation.Provider.CmdletProvider.ShouldProcesstrue, si se pueden realizar modificaciones potencialmente peligrosas del sistema, el método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* debe llamar al método System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Este método envía un mensaje de confirmación al usuario para permitir retroalimentación adicional que indique que la operación debe continuar.

Adjuntación de parámetros dinámicos para el cmdlet de Set-ItemProperty

El Set-ItemProperty cmdlet puede requerir parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de propiedades de PowerShell de Windows debe implementar el método System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* . Este método devuelve un objeto que tiene propiedades y campos con atributos de análisis similar a una clase cmdlet o a un objeto System.Management.Automation.RuntimeDefinedParameterDictionary . El null valor puede devolverse si no se añaden parámetros dinámicos.

Propiedades de desmonte

Para limpiar propiedades, el proveedor de propiedades de Windows PowerShell debe implementar el método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* para soportar llamadas desde el Clear-ItemProperty cmdlet. Este método establece una o más propiedades para el elemento ubicado en el camino especificado.

Aquí está la implementación predeterminada de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* del archivo TemplateProvider.cs proporcionado por Windows PowerShell.

Cosas a recordar sobre la implementación de ClearProperty

Las siguientes condiciones pueden aplicarse a tu implementación de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty*:

Al definir la clase de proveedor, un proveedor de propiedades Windows PowerShell podría declarar capacidades de proveedor de ExpandWildcards, Filtrar, Incluir o Excluir, de la enumeración System.Management.Automation.Provider.ProviderCapabilities . En estos casos, la implementación del método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* debe garantizar que la ruta pasada al método cumpla con los requisitos de las capacidades especificadas. Para ello, el método debe acceder a la propiedad adecuada, por ejemplo, las propiedades System.Management.Automation.Provider.CmdletProvider.Exclude* y System.Management.Automation.Provider.CmdletProvider.Include* .
Por defecto, las sobrescrituras de este método no deberían recuperar un lector para objetos ocultos al usuario a menos que la propiedad System.Management.Automation.Provider.CmdletProvider.Force* esté configurada en true. Se debe escribir un error si la ruta representa un elemento oculto al usuario y System.Management.Automation.Provider.CmdletProvider.Force* está configurado como false.
Tu implementación del método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* debe llamar a System.Management.Automation.Provider.CmdletProvider.ShouldProcess y verificar su valor de retorno antes de realizar cualquier cambio en el almacén de datos. Este método se utiliza para confirmar la ejecución de una operación antes de que se realice un cambio en el estado del sistema, como borrar contenido. System.Management.Automation.Provider.CmdletProvider.ShouldProcess envía el nombre del recurso a cambiar al usuario, teniendo en cuenta el entorno de ejecución de Windows PowerShell cualquier configuración de línea de comandos o variable de preferencia para determinar qué debe mostrarse.

Tras la llamada a System.Management.Automation.Provider.CmdletProvider.ShouldProcess , truesi se pueden realizar modificaciones potencialmente peligrosas del sistema, el método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* debe llamar al método System.Management.Automation.Provider.CmdletProvider.ShouldContinue (Debería)Continuar . Este método envía un mensaje de confirmación al usuario para permitir retroalimentación adicional que indique que la operación potencialmente peligrosa debe continuar.

Adjuntar parámetros dinámicos al Clear-ItemProperty cmdlet

El Clear-ItemProperty cmdlet puede requerir parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de propiedades de Windows PowerShell debe implementar el método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* . Este método devuelve un objeto que tiene propiedades y campos con atributos de análisis similar a una clase cmdlet o a un objeto System.Management.Automation.RuntimeDefinedParameterDictionary . El null valor puede devolverse si no se añaden parámetros dinámicos.

Aquí está la implementación predeterminada de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* del archivo TemplateProvider.cs proporcionado por Windows PowerShell.