Criando um Provedor de Unidade PowerShell para Windows

Este tópico descreve como criar um provedor de drive Windows PowerShell que ofereça uma forma de acessar um armazenamento de dados por meio de um drive Windows PowerShell. Esse tipo de provedor também é chamado de provedores de unidades Windows PowerShell. Os drives PowerShell do Windows usados pelo provedor fornecem os meios de conexão ao armazenamento de dados.

O provedor de drive Windows PowerShell descrito aqui fornece acesso a um banco de dados do Microsoft Access. Para esse provedor, o drive PowerShell do Windows representa o banco de dados (é possível adicionar qualquer número de drives a um provedor de drive), os contêineres de nível superior do drive representam as tabelas do banco de dados, e os itens dos containers representam as linhas das tabelas.

Definindo a Classe de Provedor PowerShell do Windows

Seu provedor de drive deve definir uma classe .NET que derive da classe base System.Management.Automation.Provider.DriveCmdletProvider . Aqui está a definição da classe para esse fornecedor de drives:

[CmdletProvider("AccessDB", ProviderCapabilities.None)]
public class AccessDBProvider : DriveCmdletProvider

Note que, neste exemplo, o atributo System.Management.Automation.Provider.CmdletProviderAttribute especifica um nome amigável para o provedor e as capacidades específicas do Windows PowerShell que o provedor expõe ao tempo de execução do Windows PowerShell durante o processamento de comandos. Os valores possíveis para as capacidades do provedor são definidos pela enumeração System.Management.Automation.Provider.ProviderCapabilities . Este provedor de drive não suporta nenhuma dessas capacidades.

Definindo a Funcionalidade Base

Como descrito em Design Your Windows PowerShell Provider, a classe System.Management.Automation.Provider.DriveCmdletProvider deriva da classe base System.Management.Automation.Provider.CmdletProvider que define os métodos necessários para inicializar e desinicializar o provedor. Para implementar funcionalidades para adicionar informações de inicialização específicas de cada sessão e para liberar recursos usados pelo provedor, veja Criando um Provedor Básico de PowerShell para Windows. No entanto, a maioria dos provedores (incluindo o provedor descrito aqui) pode usar a implementação padrão dessa funcionalidade fornecida pelo Windows PowerShell.

Criando Informações sobre o Estado do Disco

Todos os provedores de Windows PowerShell são considerados sem estado, o que significa que seu provedor de drive precisa criar qualquer informação de estado necessária pelo runtime do Windows PowerShell ao ligar para o seu provedor.

Para esse provedor de drive, as informações de estado incluem a conexão com o banco de dados que é mantida como parte das informações do drive. Aqui está um código que mostra como essa informação é armazenada no objeto System.Management.Automation.PSDriveinfo que descreve o disco:

internal class AccessDBPSDriveInfo : PSDriveInfo
{
    private OdbcConnection connection;

    /// <summary>
    /// ODBC connection information.
    /// </summary>
    public OdbcConnection Connection
    {
        get { return connection; }
        set { connection = value; }
    }

    /// <summary>
    /// Constructor that takes one argument
    /// </summary>
    /// <param name="driveInfo">Drive provided by this provider</param>
    public AccessDBPSDriveInfo(PSDriveInfo driveInfo)
        : base(driveInfo)
    { }

} // class AccessDBPSDriveInfo

Criando uma Força

Para permitir que o runtime do Windows PowerShell crie um drive, o provedor de drive deve implementar o método System.Management.Automation.Provider.DriveCmdletProvider.NewDrive* . O código a seguir mostra a implementação do método System.Management.Automation.Provider.DriveCmdletProvider.NewDrive* para esse provedor de drives:

      protected override PSDriveInfo NewDrive(PSDriveInfo drive)
      {
          // check if drive object is null
          if (drive == null)
          {
              WriteError(new ErrorRecord(
                  new ArgumentNullException("drive"), 
                  "NullDrive",
                  ErrorCategory.InvalidArgument, 
                  null)
              );
           
              return null;
          }
       
          // check if drive root is not null or empty
          // and if its an existing file
          if (String.IsNullOrEmpty(drive.Root) || (File.Exists(drive.Root) == false))
          {
              WriteError(new ErrorRecord(
                  new ArgumentException("drive.Root"), 
                  "NoRoot",
                  ErrorCategory.InvalidArgument, 
                  drive)
              );

              return null;
          }

          // create a new drive and create an ODBC connection to the new drive
          AccessDBPSDriveInfo accessDBPSDriveInfo = new AccessDBPSDriveInfo(drive);

          OdbcConnectionStringBuilder builder = new OdbcConnectionStringBuilder();

          builder.Driver = "Microsoft Access Driver (*.mdb)";
          builder.Add("DBQ", drive.Root);
         
          OdbcConnection conn = new OdbcConnection(builder.ConnectionString);
          conn.Open();
          accessDBPSDriveInfo.Connection = conn;

          return accessDBPSDriveInfo;
      } // NewDrive

Sua substituição desse método deve fazer o seguinte:

Verifique se o membro System.Management.Automation.PSDriveinfo.Root* existe e que uma conexão com o armazenamento de dados pode ser feita.
Crie um drive e preencha o membro da conexão, em suporte ao New-PSDrive cmdlet.
Valide o objeto System.Management.Automation.PSDriveinfo para o drive proposto.
Modificar o objeto System.Management.Automation.PSDriveinfo que descreve o disco com qualquer informação de desempenho ou confiabilidade necessária, ou forneça dados extras para os chamadores que usam o disco.
Gerencie falhas usando o método System.Management.Automation.Provider.CmdletProvider.WriteError e então retorne null.

Esse método retorna ou as informações do drive que foram passadas para o método ou uma versão específica do provedor dele.

Anexando Parâmetros Dinâmicos ao NewDrive

O New-PSDrive cmdlet suportado pelo seu provedor de drive pode exigir parâmetros adicionais. Para anexar esses parâmetros dinâmicos ao cmdlet, o provedor implementa o método System.Management.Automation.Provider.DriveCmdletProvider.NewDriveDynamicParameters* . Esse método retorna um objeto que possui propriedades e campos com atributos de análise semelhantes a uma classe cmdlet ou a um objeto System.Management.Automation.RuntimeDefinedParameterDictionary .

Esse provedor de drive não anula esse método. No entanto, o código a seguir mostra a implementação padrão desse método:

Remoção de um Disco

Para fechar a conexão com o banco de dados, o provedor de drive deve implementar o método System.Management.Automation.Provider.DriveCmdletProvider.RemoveDrive* . Esse método fecha a conexão com o drive após limpar qualquer informação específica do provedor.

O código a seguir mostra a implementação do método System.Management.Automation.Provider.DriveCmdletProvider.RemoveDrive* para este provedor de drives:

protected override PSDriveInfo RemoveDrive(PSDriveInfo drive)
{
    // check if drive object is null
    if (drive == null)
    {
        WriteError(new ErrorRecord(
            new ArgumentNullException("drive"), 
            "NullDrive",
            ErrorCategory.InvalidArgument, 
            drive)
        );

       return null;
    }

    // close ODBC connection to the drive
    AccessDBPSDriveInfo accessDBPSDriveInfo = drive as AccessDBPSDriveInfo;

    if (accessDBPSDriveInfo == null)
    {
        return null;
    }
    accessDBPSDriveInfo.Connection.Close();
  
    return accessDBPSDriveInfo;
} // RemoveDrive

Se o drive puder ser removido, o método deve retornar a informação passada ao método através do drive parâmetro. Se o drive não puder ser removido, o método deve escrever uma exceção e então retornar null. Se seu provedor não sobrescrever esse método, a implementação padrão desse método apenas retorna a informação do drive passada como entrada.

Inicializando Drives Padrão

Seu provedor de drive implementa o método System.Management.Automation.Provider.DriveCmdletProvider.InitializeDefaultDrives* para montar os drives. Por exemplo, o provedor do Active Directory pode montar um drive para o contexto padrão de nomenclatura se o computador estiver conectado a um domínio.

Esse método retorna uma coleção de informações dos discos sobre os discos inicializados, ou uma coleção vazia. A chamada a esse método é feita após o runtime do Windows PowerShell chamar o método System.Management.Automation.Provider.CmdletProvider.Start* para inicializar o provedor.

Este provedor de drive não sobrepõe o método System.Management.Automation.Provider.DriveCmdletProvider.InitializeDefaultDrives* . No entanto, o código a seguir mostra a implementação padrão, que retorna uma coleção de discos vazia:

Coisas para Lembrar Sobre a Implementação do InitializeDefaultDrives

Todos os provedores de drive devem montar um drive root para ajudar o usuário na descoberta. O drive raiz pode listar locais que servem como raiz para outros drives montados. Por exemplo, o provedor do Active Directory pode criar um drive que liste os contextos de nomeação encontrados nos namingContext atributos do Ambiente de Sistema Distribuído raiz (DSE). Isso ajuda os usuários a descobrir pontos de montagem para outros discos.

Exemplo de código

Para um código de exemplo completo, veja AccessDbProviderSample02 Code Sample.

Testando o Provedor de Unidades PowerShell do Windows

Quando seu provedor de Windows PowerShell estiver registrado no Windows PowerShell, você pode testá-lo executando os cmdlets suportados na linha de comando, incluindo quaisquer cmdlets disponibilizados por derivação. Vamos testar o fornecedor do sample drive.

Execute o Get-PSProvider cmdlet para recuperar a lista de provedores e garantir que o provedor do drive AccessDB esteja presente:

PS>Get-PSProvider

O seguinte resultado é exibido:

Name                 Capabilities                  Drives
----                 ------------                  ------
AccessDB             None                          {}
Alias                ShouldProcess                 {Alias}
Environment          ShouldProcess                 {Env}
FileSystem           Filter, ShouldProcess         {C, Z}
Function             ShouldProcess                 {function}
Registry             ShouldProcess                 {HKLM, HKCU}

Garanta que exista um nome de servidor de banco de dados (DSN) para o banco acessando a parte de Fontes de Dados das Ferramentas Administrativas do sistema operacional. Na tabela DSN do usuário , clique duas vezes em MS Access Database e adicione o caminho C:\ps\northwind.mdbdo drive .

Crie um novo drive usando o provedor de sample drive:

New-PSDrive -Name mydb -Root C:\ps\northwind.mdb -PSProvider AccessDb`

O seguinte resultado é exibido:

Name     Provider     Root                   CurrentLocation
----     --------     ----                   ---------------
mydb     AccessDB     C:\ps\northwind.mdb

Valide a conexão. Como a conexão é definida como um membro do disco, você pode verificar usando o cmdlet Get-PDDrive.

Observação

O usuário ainda não pode interagir com o provedor como um drive, pois o provedor precisa de funcionalidade de contêiner para essa interação. Para mais informações, veja Criando um Provedor de Contêineres Windows PowerShell.

PS> (Get-PSDrive mydb). Conexão

O seguinte resultado é exibido:
```
ConnectionString  : Driver={Microsoft Access Driver (*.mdb)};DBQ=C:\ps\northwind.mdb
ConnectionTimeout : 15
Database          : C:\ps\northwind
DataSource        : ACCESS
ServerVersion     : 04.00.0000
Driver            : odbcjt32.dll
State             : Open
Site              :
Container         :
```
Remova o drive e saia da carcaça:
```
PS> Remove-PSDrive mydb
PS> exit
```