Crear un proveedor de elementos de Windows PowerShell

Este tema describe cómo crear un proveedor de Windows PowerShell que pueda manipular los datos en un almacén de datos. En este tema, los elementos de datos del almacén se denominan "elementos" del almacén de datos. Como consecuencia, un proveedor que puede manipular los datos del almacén se denomina proveedor de elementos de Windows PowerShell.

El proveedor de elementos de Windows PowerShell descrito en este tema obtiene elementos de datos de una base de datos de Access. En este caso, un "elemento" es una tabla de la base de datos de Access o una fila de una tabla.

Definición de la clase de proveedor de elementos de Windows PowerShell

Un proveedor de elementos de Windows PowerShell debe definir una clase .NET que derive de la clase base System.Management.Automation.Provider.ItemCmdletProvider. La siguiente es la definición de clase para el proveedor de elementos descrito en esta sección.

[CmdletProvider("AccessDB", ProviderCapabilities.None)]

public class AccessDBProvider : ItemCmdletProvider

Tenga en cuenta que en esta definición de clase, el atributo System.Management.Automation.Provider.CmdletProviderAttribute incluye dos parámetros. El primer parámetro especifica un nombre fácil de usar para el proveedor que utiliza Windows PowerShell. El segundo parámetro especifica las capacidades específicas de Windows PowerShell que el proveedor expone al tiempo de ejecución de Windows PowerShell durante el procesamiento de comandos. Para este proveedor, no hay capacidades específicas de Windows PowerShell agregadas.

Definición de funcionalidad básica

Como se describe en Diseño de su proveedor de Windows PowerShell, la clase System.Management.Automation.Provider.DriveCmdletProvider deriva de varias otras clases que proporcionaron una funcionalidad de proveedor diferente. Por lo tanto, un proveedor de elementos de Windows PowerShell debe definir todas las funciones proporcionadas por esas clases.

Para obtener más información sobre cómo implementar la funcionalidad para agregar información de inicialización específica de la sesión y liberar recursos utilizados por el proveedor, consulte Creación de un proveedor básico de Windows PowerShell. Sin embargo, la mayoría de los proveedores, incluido el proveedor que se describe aquí, pueden usar la implementación predeterminada de esta funcionalidad proporcionada por Windows PowerShell.

Antes de que el proveedor de elementos de Windows PowerShell pueda manipular los elementos del almacén, debe implementar los métodos de la clase base System.Management.Automation.Provider.DriveCmdletProvider para acceder al almacén de datos. Para obtener más información sobre la implementación de esta clase, consulte Creación de un proveedor de unidades de Windows PowerShell.

Comprobando la validez de la ruta

Al buscar un elemento de datos, el tiempo de ejecución de Windows PowerShell proporciona una ruta de Windows PowerShell al proveedor, como se define en la sección "Conceptos de PSPath" de Cómo funciona Windows PowerShell. Un proveedor de elementos de Windows PowerShell debe verificar la validez sintáctica y semántica de cualquier ruta que se le pase implementando el método System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath. Este método devuelve true si la ruta es válida y false en caso contrario. Tenga en cuenta que la implementación de este método no debe verificar la existencia del elemento en la ruta, sino sólo que la ruta sea sintáctica y semánticamente correcta.

A continuación se muestra la implementación del método System.Management.Automation.Provider.ItemCmdletProvider.IsValidPath para este proveedor. Tenga en cuenta que esta implementación llama a un método auxiliar NormalizePath para convertir todos los separadores en la ruta en uno uniforme.

protected override bool IsValidPath(string path)
{
    bool result = true;

    // check if the path is null or empty
    if (String.IsNullOrEmpty(path))
    {
        result = false;
    }

    // convert all separators in the path to a uniform one
    path = NormalizePath(path);

    // split the path into individual chunks
    string[] pathChunks = path.Split(pathSeparator.ToCharArray());

    foreach (string pathChunk in pathChunks)
    {
        if (pathChunk.Length == 0)
        {
            result = false;
        }
    }
    return result;
} // IsValidPath

Determinar si un artículo existe

Después de verificar la ruta, el tiempo de ejecución de Windows PowerShell debe determinar si existe un elemento de datos en esa ruta. Para admitir este tipo de consulta, el proveedor de elementos de Windows PowerShell implementa el método System.Management.Automation.Provider.ItemCmdletProvider.ItemExists. Este método devuelve true si un elemento se encuentra en la ruta especificada y false (predeterminado) en caso contrario.

A continuación se muestra la implementación del método System.Management.Automation.Provider.ItemCmdletProvider.ItemExists para este proveedor. Tenga en cuenta que este método llama a los métodos auxiliares PathIsDrive, ChunkPath y GetTable y utiliza un objeto DatabaseTableInfo definido por el proveedor. .

protected override bool ItemExists(string path)
{
    // check if the path represented is a drive
    if (PathIsDrive(path))
    {
        return true;
    }

    // Obtain type, table name and row number from path
    string tableName;
    int rowNumber;

    PathType type = GetNamesFromPath(path, out tableName, out rowNumber);

    DatabaseTableInfo table = GetTable(tableName);

    if (type == PathType.Table)
    {
        // if specified path represents a table then DatabaseTableInfo
        // object for the same should exist
        if (table != null)
        {
            return true;
        }
    }
    else if (type == PathType.Row)
    {
        // if specified path represents a row then DatabaseTableInfo should
        // exist for the table and then specified row number must be within
        // the maximum row count in the table
        if (table != null && rowNumber < table.RowCount)
        {
            return true;
        }
    }

    return false;

} // ItemExists

Cosas para recordar sobre la implementación de ItemExists

Las siguientes condiciones pueden aplicarse a su implementación de System.Management.Automation.Provider.ItemCmdletProvider.ItemExists:

• Al definir la clase de proveedor, un proveedor de elementos de Windows PowerShell puede declarar capacidades de proveedor de ExpandWildcards, Filter, Include o Exclude, de la enumeración System.Management.Automation.Provider.ProviderCapabilities. En estos casos, la implementación del método System.Management.Automation.Provider.ItemCmdletProvider.ItemExists debe garantizar que la ruta pasada al método cumpla con los requisitos de las capacidades especificadas. Para hacer esto, 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.
• La implementación de este método debe manejar cualquier forma de acceso al elemento que pueda hacerlo visible para el usuario. Por ejemplo, si un usuario tiene acceso de escritura a un archivo a través del proveedor FileSystem (proporcionado por Windows PowerShell), pero no tiene acceso de lectura, el archivo aún existe y System.Management.Automation.Provider.ItemCmdletProvider.ItemExists devuelve verdadero. Es posible que su implementación requiera verificar un elemento principal para ver si el elemento secundario se puede enumerar.

Adjuntar parámetros dinámicos al cmdlet Test-Path

A veces, el cmdlet Test-Path que llama a System.Management.Automation.Provider.ItemCmdletProvider.ItemExists requiere parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de elementos de Windows PowerShell debe implementar el método System.Management.Automation.Provider.ItemCmdletProvider.ItemExistsDynamicParameters. Este método recupera los parámetros dinámicos del elemento en la ruta indicada y devuelve un objeto que tiene propiedades y campos con atributos de análisis similares a una clase de cmdlet o un objeto System.Management.Automation.RuntimeDefinedParameterDictionary. El tiempo de ejecución de Windows PowerShell utiliza el objeto devuelto para agregar los parámetros al cmdlet Test-Path.

Este proveedor de elementos de Windows PowerShell no implementa este método. Sin embargo, el siguiente código es la implementación predeterminada de este método.

Recuperar un artículo

Para recuperar un elemento, el proveedor de elementos de Windows PowerShell debe anular el método System.Management.Automation.Provider.ItemCmdletProvider.GetItem para admitir llamadas desde el cmdlet Get-Item. Este método escribe el elemento mediante el método System.Management.Automation.Provider.CmdletProvider.WriteItemObject.

Aquí está la implementación del método System.Management.Automation.Provider.ItemCmdletProvider.GetItem para este proveedor. Tenga en cuenta que este método utiliza los métodos auxiliares GetTable y GetRow para recuperar elementos que son tablas en la base de datos de Access o filas en una tabla de datos.

protected override void GetItem(string path)
{
    // check if the path represented is a drive
    if (PathIsDrive(path))
    {
        WriteItemObject(this.PSDriveInfo, path, true);
        return;
    }// if (PathIsDrive...

     // Get table name and row information from the path and do 
     // necessary actions
     string tableName;
     int rowNumber;

     PathType type = GetNamesFromPath(path, out tableName, out rowNumber);

     if (type == PathType.Table)
     {
         DatabaseTableInfo table = GetTable(tableName);
         WriteItemObject(table, path, true);
     }
     else if (type == PathType.Row)
     {
         DatabaseRowInfo row = GetRow(tableName, rowNumber);
         WriteItemObject(row, path, false);
     }
     else
     {
         ThrowTerminatingInvalidPathException(path);
     }

 } // GetItem

Cosas para recordar sobre la implementación de GetItem

Las siguientes condiciones pueden aplicarse a una implementación de System.Management.Automation.Provider.ItemCmdletProvider.GetItem:

• Al definir la clase de proveedor, un proveedor de elementos de Windows PowerShell puede declarar capacidades de proveedor de ExpandWildcards, Filter, Include o Exclude, de la enumeración System.Management.Automation.Provider.ProviderCapabilities. En estos casos, la implementación de System.Management.Automation.Provider.ItemCmdletProvider.GetItem debe garantizar que la ruta pasada al método cumpla esos requisitos. Para hacer esto, 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.

• De forma predeterminada, las anulaciones de este método no deberían recuperar objetos que generalmente están ocultos para el usuario a menos que la propiedad System.Management.Automation.Provider.CmdletProvider.Force esté establecida en true. Por ejemplo, el método System.Management.Automation.Provider.ItemCmdletProvider.GetItem para el proveedor FileSystem comprueba la propiedad System.Management.Automation.Provider.CmdletProvider.Force antes de intentar llamar a System.Management.Automation.Provider.CmdletProvider.WriteItemObject para archivos ocultos o del sistema.

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

A veces, el cmdlet Get-Item requiere parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de elementos de Windows PowerShell debe implementar el método System.Management.Automation.Provider.ItemCmdletProvider.GetItemDynamicParameters. Este método recupera los parámetros dinámicos del elemento en la ruta indicada y devuelve un objeto que tiene propiedades y campos con atributos de análisis similares a una clase de cmdlet o un objeto System.Management.Automation.RuntimeDefinedParameterDictionary. El tiempo de ejecución de Windows PowerShell utiliza el objeto devuelto para agregar los parámetros al cmdlet Get-Item.

Este proveedor no implementa este método. Sin embargo, el siguiente código es la implementación predeterminada de este método.

Configurar un elemento

Para configurar un elemento, el proveedor de elementos de Windows PowerShell debe anular el método System.Management.Automation.Provider.ItemCmdletProvider.SetItem para admitir llamadas desde el cmdlet Set-Item. Este método establece el valor del elemento en la ruta especificada.

Este proveedor no proporciona una anulación para el método System.Management.Automation.Provider.ItemCmdletProvider.SetItem. Sin embargo, la siguiente es la implementación predeterminada de este método.

Cosas para recordar sobre la implementación de SetItem

Las siguientes condiciones pueden aplicarse a su implementación de System.Management.Automation.Provider.ItemCmdletProvider.SetItem:

• Al definir la clase de proveedor, un proveedor de elementos de Windows PowerShell puede declarar capacidades de proveedor de ExpandWildcards, Filter, Include o Exclude, de la enumeración System.Management.Automation.Provider.ProviderCapabilities. En estos casos, la implementación de System.Management.Automation.Provider.ItemCmdletProvider.SetItem debe garantizar que la ruta pasada al método cumpla esos requisitos. Para hacer esto, 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.

• De forma predeterminada, las anulaciones de este método no deben establecer ni escribir objetos que estén ocultos para el usuario a menos que la propiedad System.Management.Automation.Provider.CmdletProvider.Force esté establecida en true. Se debe enviar un error al método System.Management.Automation.Provider.CmdletProvider.WriteError si la ruta representa un elemento oculto y System.Management.Automation.Provider.CmdletProvider.Force está establecido en false.

• Su implementación del método System.Management.Automation.Provider.ItemCmdletProvider.SetItem debe llamar a System.Management.Automation.Provider.CmdletProvider.ShouldProcess y verificar su valor de retorno antes de realizar cambios 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 almacén de datos, por ejemplo, eliminar archivos. El método System.Management.Automation.Provider.CmdletProvider.ShouldProcess envía el nombre del recurso que se va a cambiar al usuario, y el tiempo de ejecución de Windows PowerShell tiene en cuenta cualquier configuración de línea de comandos o variables de preferencia para determinar qué se debe mostrar.

  Después de que la llamada a System.Management.Automation.Provider.CmdletProvider.ShouldProcess devuelva true, el método System.Management.Automation.Provider.ItemCmdletProvider.SetItem debe llamar al método System.Management.Automation.Provider.CmdletProvider .Método debería continuar. Este método envía un mensaje al usuario para permitir comentarios para verificar si la operación debe continuar. La llamada a System.Management.Automation.Provider.CmdletProvider.ShouldContinue permite una verificación adicional de modificaciones del sistema potencialmente peligrosas.

Recuperando parámetros dinámicos para SetItem

A veces, el cmdlet Set-Item requiere parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de elementos de Windows PowerShell debe implementar el método System.Management.Automation.Provider.ItemCmdletProvider.SetItemDynamicParameters. Este método recupera los parámetros dinámicos del elemento en la ruta indicada y devuelve un objeto que tiene propiedades y campos con atributos de análisis similares a una clase de cmdlet o un objeto System.Management.Automation.RuntimeDefinedParameterDictionary. El tiempo de ejecución de Windows PowerShell utiliza el objeto devuelto para agregar los parámetros al cmdlet Set-Item.

Este proveedor no implementa este método. Sin embargo, el siguiente código es la implementación predeterminada de este método.

Borrar un artículo

Para borrar un elemento, el proveedor de elementos de Windows PowerShell implementa el método System.Management.Automation.Provider.ItemCmdletProvider.ClearItem para admitir llamadas desde el cmdlet Clear-Item. Este método borra el elemento de datos en la ruta especificada.

Este proveedor no implementa este método. Sin embargo, el siguiente código es la implementación predeterminada de este método.

Cosas para recordar sobre la implementación de ClearItem

Las siguientes condiciones pueden aplicarse a una implementación de System.Management.Automation.Provider.ItemCmdletProvider.ClearItem:

• Al definir la clase de proveedor, un proveedor de elementos de Windows PowerShell puede declarar capacidades de proveedor de ExpandWildcards, Filter, Include o Exclude, de la enumeración System.Management.Automation.Provider.ProviderCapabilities. En estos casos, la implementación de System.Management.Automation.Provider.ItemCmdletProvider.ClearItem debe garantizar que la ruta pasada al método cumpla esos requisitos. Para hacer esto, 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.

• De forma predeterminada, las anulaciones de este método no deben establecer ni escribir objetos que estén ocultos para el usuario a menos que la propiedad System.Management.Automation.Provider.CmdletProvider.Force esté establecida en true. Se debe enviar un error al método System.Management.Automation.Provider.CmdletProvider.WriteError si la ruta representa un elemento que está oculto para el usuario y System.Management.Automation.Provider.CmdletProvider.Force está establecido en falso .

• Su implementación del método System.Management.Automation.Provider.ItemCmdletProvider.SetItem debe llamar a System.Management.Automation.Provider.CmdletProvider.ShouldProcess y verificar su valor de retorno antes de realizar cambios 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 almacén de datos, por ejemplo, eliminar archivos. El método System.Management.Automation.Provider.CmdletProvider.ShouldProcess envía el nombre del recurso que se va a cambiar al usuario, con el tiempo de ejecución de Windows PowerShell y maneja cualquier configuración de línea de comandos o variables de preferencia para determinar qué se debe mostrar.

  Después de que la llamada a System.Management.Automation.Provider.CmdletProvider.ShouldProcess devuelva true, el método System.Management.Automation.Provider.ItemCmdletProvider.SetItem debe llamar al método System.Management.Automation.Provider.CmdletProvider .Método debería continuar. Este método envía un mensaje al usuario para permitir comentarios para verificar si la operación debe continuar. La llamada a System.Management.Automation.Provider.CmdletProvider.ShouldContinue permite una verificación adicional de modificaciones del sistema potencialmente peligrosas.

Recuperar parámetros dinámicos para ClearItem

A veces, el cmdlet Clear-Item requiere parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de elementos de Windows PowerShell debe implementar el método System.Management.Automation.Provider.ItemCmdletProvider.ClearItemDynamicParameters. Este método recupera los parámetros dinámicos del elemento en la ruta indicada y devuelve un objeto que tiene propiedades y campos con atributos de análisis similares a una clase de cmdlet o un objeto System.Management.Automation.RuntimeDefinedParameterDictionary. El tiempo de ejecución de Windows PowerShell utiliza el objeto devuelto para agregar los parámetros al cmdlet Clear-Item.

Este proveedor de artículos no implementa este método. Sin embargo, el siguiente código es la implementación predeterminada de este método.

Realizar una acción predeterminada para un elemento

Un proveedor de elementos de Windows PowerShell puede implementar el método System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction para admitir llamadas desde el cmdlet Invoke-Item, que permite al proveedor realizar una acción predeterminada para el elemento en la ruta especificada. Por ejemplo, el proveedor de FileSystem podría usar este método para llamar a ShellExecute para un elemento específico.

Este proveedor no implementa este método. Sin embargo, el siguiente código es la implementación predeterminada de este método.

Cosas para recordar sobre la implementación de InvokeDefaultAction

Las siguientes condiciones pueden aplicarse a una implementación de System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction:

• Al definir la clase de proveedor, un proveedor de elementos de Windows PowerShell puede declarar capacidades de proveedor de ExpandWildcards, Filter, Include o Exclude, de la enumeración System.Management.Automation.Provider.ProviderCapabilities. En estos casos, la implementación de System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultAction debe garantizar que la ruta pasada al método cumpla esos requisitos. Para hacer esto, 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.

• De forma predeterminada, las anulaciones de este método no deben establecer ni escribir objetos ocultos para el usuario a menos que la propiedad System.Management.Automation.Provider.CmdletProvider.Force esté establecida en true. Se debe enviar un error al método System.Management.Automation.Provider.CmdletProvider.WriteError si la ruta representa un elemento que está oculto para el usuario y System.Management.Automation.Provider.CmdletProvider.Force está establecido en falso .

Recuperar parámetros dinámicos para InvokeDefaultAction

A veces, el cmdlet Invoke-Item requiere parámetros adicionales que se especifican dinámicamente en tiempo de ejecución. Para proporcionar estos parámetros dinámicos, el proveedor de elementos de Windows PowerShell debe implementar el método System.Management.Automation.Provider.ItemCmdletProvider.InvokeDefaultActionDynamicParameters. Este método recupera los parámetros dinámicos del elemento en la ruta indicada y devuelve un objeto que tiene propiedades y campos con atributos de análisis similares a una clase de cmdlet o un objeto System.Management.Automation.RuntimeDefinedParameterDictionary. El tiempo de ejecución de Windows PowerShell utiliza el objeto devuelto para agregar los parámetros dinámicos al cmdlet Invoke-Item.

Este proveedor de artículos no implementa este método. Sin embargo, el siguiente código es la implementación predeterminada de este método.

Implementación de métodos y clases auxiliares.

Este proveedor de elementos implementa varios métodos y clases auxiliares que utilizan los métodos de anulación públicos definidos por Windows PowerShell. El código de estos métodos y clases auxiliares se muestra en la sección Ejemplo de código.

Método NormalizePath

Este proveedor de elementos implementa un método auxiliar NormalizePath para garantizar que la ruta tenga un formato coherente. El formato especificado utiliza una barra invertida (\) como separador.

Método PathIsDrive

Este proveedor de elementos implementa un método auxiliar PathIsDrive para determinar si la ruta especificada es realmente el nombre de la unidad.

Método ChunkPath

Este proveedor de elementos implementa un método auxiliar ChunkPath que divide la ruta especificada para que el proveedor pueda identificar sus elementos individuales. Devuelve una matriz compuesta por los elementos de la ruta.

Método GetTable

Este proveedor de elementos implementa el método auxiliar GetTables que devuelve un objeto DatabaseTableInfo que representa información sobre la tabla especificada en la llamada.

Método GetRow

El método System.Management.Automation.Provider.ItemCmdletProvider.GetItem de este proveedor de elementos llama al método auxiliar GetRows. Este método auxiliar recupera un objeto DatabaseRowInfo que representa información sobre la fila especificada en la tabla.

Clase DatabaseTableInfo

Este proveedor de elementos define una clase DatabaseTableInfo que representa una colección de información en una tabla de datos de la base de datos. Esta clase es similar a la clase System.IO.Directoryinfo.

El proveedor de elementos de muestra define un método DatabaseTableInfo.GetTables que devuelve una colección de objetos de información de tabla que definen las tablas en la base de datos. Este método incluye un bloque try/catch para garantizar que cualquier error de la base de datos aparezca como una fila con cero entradas.

Clase DatabaseRowInfo

Este proveedor de elementos define la clase auxiliar DatabaseRowInfo que representa una fila en una tabla de la base de datos. Esta clase es similar a la clase System.IO.FileInfo.

El proveedor de muestra define un método DatabaseRowInfo.GetRows para devolver una colección de objetos de información de fila para la tabla especificada. Este método incluye un bloque try/catch para detectar excepciones. Cualquier error no generará información de fila.

Ejemplo de código

Para obtener un código de muestra completo, consulte Ejemplo de código de AccessDbProviderSample03.

Definición de tipos de objetos y formato

Al escribir un proveedor, puede ser necesario agregar miembros a objetos existentes o definir objetos nuevos. Cuando termine, cree un archivo de Tipos que Windows PowerShell pueda usar para identificar los miembros del objeto y un archivo de Formato que defina cómo se muestra el objeto. Para obtener más información, consulte Ampliación de tipos de objetos y formato.

Construyendo el proveedor de Windows PowerShell

Consulte Cómo registrar cmdlets, proveedores y aplicaciones host.

Prueba del proveedor de Windows PowerShell

Cuando este proveedor de elementos de Windows PowerShell está registrado en Windows PowerShell, solo puede probar la funcionalidad básica y de unidad del proveedor. Para probar la manipulación de elementos, también debe implementar la funcionalidad de contenedor descrita en Implementación de un proveedor de contenedor de Windows PowerShell.

Ver también

• SDK de Windows PowerShell
• Guía del programador de Windows PowerShell
• Crear proveedores de Windows PowerShell
• Diseño de su proveedor de Windows PowerShell
• Ampliación de tipos de objetos y formato
• Cómo funciona Windows PowerShell
• Crear un proveedor de contenedor de Windows PowerShell
• Crear un proveedor de Drive Windows PowerShell
• Cómo registrar cmdlets, proveedores y aplicaciones host