Criando um Provedor de Navegação Windows PowerShell

Este tópico descreve como criar um provedor de navegação Windows PowerShell que possa navegar pelo armazenamento de dados. Esse tipo de provedor suporta comandos recursivos, contêineres aninhados e caminhos relativos.

Observação

Você pode baixar o arquivo-fonte C# (AccessDBSampleProvider05.cs) deste provedor usando o Microsoft Windows Software Development Kit para Windows Vista e os Componentes de Tempo de Execução do .NET Framework 3.0. Para instruções de download, veja Como Instalar o Windows PowerShell e Baixar o Windows PowerShell SDK. Os arquivos fonte baixados estão disponíveis no <diretório PowerShell Samples> . Para mais informações sobre outras implementações de provedores Windows PowerShell, veja Designing Your Windows PowerShell Provider.

O provedor descrito aqui permite que o usuário gerencie um banco de dados Access como um drive, permitindo que ele navegue até as tabelas de dados do banco de dados. Ao criar seu próprio provedor de navegação, você pode implementar métodos que criem caminhos qualificados para drive necessários para navegação, normalizar caminhos relativos, mover itens do armazenamento de dados, assim como métodos que recebam nomes filhos, o caminho pai de um item e testem para identificar se um item é um container.

Cuidado

Esteja ciente de que esse design assume um banco de dados que possui um campo com o nome ID, e que o tipo do campo é LongInteger.

Defina o provedor do Windows PowerShell

Um provedor de navegação Windows PowerShell deve criar uma classe .NET que derive da classe base System.Management.Automation.Provider.NavigationCmdletProvider . Aqui está a definição de classe para o provedor de navegação descrito nesta seção.

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

Note que, neste provedor, o atributo System.Management.Automation.Provider.CmdletProviderAddition inclui dois parâmetros. O primeiro parâmetro especifica um nome amigável para o provedor usado pelo Windows PowerShell. O segundo parâmetro especifica 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. Para esse provedor, não há capacidades específicas do PowerShell do Windows que sejam adicionadas.

Definindo a Funcionalidade Base

Como descrito em Design Your PS Provider, a classe base System.Management.Automation.Provider.NavigationCmdletProvider deriva de várias outras classes que forneciam funcionalidades diferentes do provedor. Portanto, um provedor de navegação Windows PowerShell deve definir toda a funcionalidade fornecida por essas classes.

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 PS. No entanto, a maioria dos provedores (incluindo o fornecido descrito aqui) pode usar a implementação padrão dessa funcionalidade fornecida pelo Windows PowerShell.

Para obter acesso ao armazenamento de dados por meio de um drive PowerShell do Windows, você deve implementar os métodos da classe base System.Management.Automation.Provider.DriveCmdletProvider . Para mais informações sobre como implementar esses métodos, veja Criando um Provedor de Unidades PowerShell para Windows.

Para manipular os itens de um armazenamento de dados, como obtenção, configuração e compensação de itens, o provedor deve implementar os métodos fornecidos pela classe base System.Management.Automation.Provider.ItemCmdletProvider . Para mais informações sobre como implementar esses métodos, veja Criando um Provedor de Itens do Windows PowerShell.

Para acessar os itens filhos, ou seus nomes, do armazenamento de dados, bem como métodos que criam, copiam, renomeiam e removem itens, você deve implementar os métodos fornecidos pela classe base System.Management.Automation.Provider.ContainerCmdletProvider . Para mais informações sobre como implementar esses métodos, veja Criando um Provedor de Contêineres para Windows PowerShell.

Criando um Caminho PowerShell para Windows

O provedor de navegação Windows PowerShell utiliza um caminho interno do Windows PowerShell para navegar pelos itens do armazenamento de dados. Para criar um caminho interno do provedor, o provedor deve implementar o método System.Management.Automation.Provider.NavigationCmdletProvider.MakePath* para suportar chamadas do cmdlet Combine-Path. Esse método combina um caminho pai e filho em um caminho interno do provedor, usando um separador de caminho específico do provedor entre os caminhos pai e filho.

A implementação padrão pega caminhos com "/" ou "\" como separador de caminhos, normaliza o separador de caminho para "\", combina as partes de caminho pai e filho com o separador entre elas, e então retorna uma string que contém os caminhos combinados.

Este provedor de navegação não implementa esse método. No entanto, o código a seguir é a implementação padrão do método System.Management.Automation.Provider.NavigationCmdletProvider.MakePath* .

Coisas para Lembrar Sobre a Implementação do MakePath

As seguintes condições podem se aplicar à sua implementação de System.Management.Automation.Provider.NavigationCmdletProvider.MakePath*:

Sua implementação do método System.Management.Automation.Provider.NavigationCmdletProvider.MakePath* não deve validar o caminho como um caminho legal e totalmente qualificado no namespace do provedor. Esteja ciente de que cada parâmetro pode representar apenas uma parte de um caminho, e as partes combinadas podem não gerar um caminho totalmente qualificado. Por exemplo, o método System.Management.Automation.Provider.NavigationCmdletProvider.MakePath* para o provedor de Sistema de Arquivos pode receber "windows\system32" no parent parâmetro e "abc.dll" no child parâmetro. O método une esses valores com o separador "\" e retorna "windows\system32\abc.dll", que não é um caminho de sistema de arquivos totalmente qualificado.

Importante

As partes do caminho fornecidas na chamada para System.Management.Automation.Provider.NavigationCmdletProvider.MakePath* podem conter caracteres não permitidos no namespace do provedor. Esses caracteres provavelmente são usados para expansão de coringas e a implementação desse método não deve removê-los.

Recuperando o Caminho Pai

Os provedores de navegação Windows PowerShell implementam o método System.Management.Automation.Provider.NavigationCmdletProvider.GetParentPath* para recuperar a parte pai do caminho específico do provedor indicado, total ou parcial. O método remove a parte filha do caminho e retorna a parte do caminho pai. O root parâmetro especifica o caminho totalmente qualificado até a raiz de um disco. Esse parâmetro pode ser nulo ou vazio se um drive montado não estiver sendo usado para a operação de recuperação. Se uma raiz for especificada, o método deve retornar um caminho para um contêiner na mesma árvore da raiz.

O provedor de navegação de exemplo não sobrepõe esse método, mas usa a implementação padrão. Ele aceita caminhos que usam tanto "/" quanto "\" como separadores de caminho. Primeiro normaliza o caminho para ter apenas separadores "\", depois separa o caminho pai no último "\" e retorna o caminho pai.

Para Lembrar Sobre a Implementação do GetParentPath

Sua implementação do método System.Management.Automation.Provider.NavigationCmdletProvider.GetParentPath* deve dividir o caminho lexicamente no separador de caminho para o namespace do provedor. Por exemplo, o provedor do Sistema de Arquivos usa esse método para procurar o último "\" e retorna tudo à esquerda do separador.

Recuperar o Nome do Caminho Filho

Seu provedor de navegação implementa o método System.Management.Automation.Provider.NavigationCmdletProvider.GetChildName* para recuperar o nome (elemento folha) do filho do item localizado no caminho específico do provedor total ou parcial indicado.

O provedor de navegação de exemplo não substitui esse método. A implementação padrão é mostrada abaixo. Ele aceita caminhos que usam tanto "/" quanto "\" como separadores de caminho. Primeiro, normaliza o caminho para ter apenas separadores "\", depois divide o caminho pai no último "\" e retorna o nome da parte do caminho filho.

Coisas para Lembrar Sobre a Implementação do GetChildName

Sua implementação do método System.Management.Automation.Provider.NavigationCmdletProvider.GetChildName* deve dividir o caminho lexicamente no separador de caminho. Se o caminho fornecido não contiver separadores de caminho, o método deve retornar o caminho sem modificação.

Importante

O caminho fornecido na chamada para esse método pode conter caracteres que são ilegais no namespace do provedor. Esses caracteres provavelmente são usados para expansão de coringas ou correspondência de expressões regulares, e a implementação desse método não deve removê-los.

Determinando se um item é um recipiente

O provedor de navegação pode implementar o método System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer* para determinar se o caminho especificado indica um contêiner. Ele retorna verdadeiro se o caminho representar um contêiner, e falso caso contrário. O usuário precisa desse método para poder usar o Test-Path cmdlet para o caminho fornecido.

O código a seguir mostra a implementação System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer* em nosso provedor de navegação de exemplo. O método verifica se o caminho especificado está correto e se a tabela existe, e retorna verdadeiro se o caminho indicar um contêiner.

protected override bool IsItemContainer(string path)
{
   if (PathIsDrive(path)) 
   { 
       return true; 
   }
   
   string[] pathChunks = ChunkPath(path);
   string tableName;
   int rowNumber;

   PathType type = GetNamesFromPath(path, out tableName, out rowNumber);
   
   if (type == PathType.Table)
   {
      foreach (DatabaseTableInfo ti in GetTables())
      {
          if (string.Equals(ti.Name, tableName, StringComparison.OrdinalIgnoreCase))
          {
              return true;
          }
      } // foreach (DatabaseTableInfo...
   } // if (pathChunks...

   return false;
} // IsItemContainer

Coisas para Lembrar Sobre a Implementação do IsItemContainer

Sua classe .NET do provedor de navegação pode declarar as capacidades do provedor ExpandWildcards, Filtrar, Incluir ou Excluir, da enumeração System.Management.Automation.Provider.ProviderCapabilities . Neste caso, a implementação do System.Management.Automation.Provider.NavigationCmdletProvider.IsItemContainer* precisa garantir que o caminho passado atenda aos requisitos. Para isso, o método deve acessar a propriedade apropriada, por exemplo, a propriedade System.Management.Automation.Provider.CmdletProvider.Exclude* .

Movendo um Item

Para dar suporte ao Move-Item cmdlet, seu provedor de navegação implementa o método System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem* . Esse método move o item especificado pelo path parâmetro para o contêiner no caminho fornecido no destination parâmetro.

O provedor de navegação de exemplo não sobrepõe o método System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem* . A seguir está a implementação padrão.

Coisas para Lembrar Sobre a Implementação do MoveItem

Sua classe .NET do provedor de navegação pode declarar as capacidades do provedor ExpandWildcards, Filtrar, Incluir ou Excluir, da enumeração System.Management.Automation.Provider.ProviderCapabilities . Nesse caso, a implementação do System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem* deve garantir que o caminho percorrido atenda aos requisitos. Para isso, o método deve acessar a propriedade apropriada, por exemplo, o CmdletProvider.Exclude property.

Por padrão, as sobrescrituras desse método não devem mover objetos sobre objetos existentes, a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Por exemplo, o provedor do Sistema de Arquivos não copiará C:\temp\abc.txt sobre um arquivo C:\bar.txt existente a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Se o caminho especificado no destination parâmetro existir e for um contêiner, a propriedade System.Management.Automation.Provider.CmdletProvider.Force* não é necessária. Neste caso, System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem* deve mover o item indicado pelo path parâmetro para o contêiner indicado pelo destination parâmetro como filho.

Sua implementação do método System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem* deve chamar System.Management.Automation.Provider.CmdletProvider.ShouldProcess e verificar seu valor de retorno antes de fazer qualquer alteração no armazenamento de dados. Esse método é usado para confirmar a execução de uma operação quando uma alteração é feita no estado do sistema, por exemplo, a exclusão de arquivos. System.Management.Automation.Provider.CmdletProvider.ShouldProcess envia o nome do recurso a ser alterado para o usuário, com o runtime do Windows PowerShell levando em conta quaisquer configurações de linha de comando ou variáveis de preferência para determinar o que deve ser exibido ao usuário.

Após a chamada para System.Management.Automation.Provider.CmdletProvider.ShouldProcess retorna true, o método System.Management.Automation.Provider.NavigationCmdletProvider.MoveItem* deve chamar o método System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Esse método envia uma mensagem ao usuário para permitir feedback que indique se a operação deve continuar. Seu provedor deve ligar para System.Management.Automation.Provider.CmdletProvider.ShouldContinue como uma verificação adicional para modificações potencialmente perigosas do sistema.

Anexando Parâmetros Dinâmicos ao Cmdlet Move-Item

Às vezes, o Move-Item cmdlet requer parâmetros adicionais que são fornecidos dinamicamente em tempo de execução. Para fornecer esses parâmetros dinâmicos, o provedor de navegação deve implementar o método System.Management.Automation.Provider.NavigationCmdletProvider.MoveItemDynamicParameters* para obter os valores de parâmetros necessários do item no caminho indicado, e retornar um objeto que tenha propriedades e campos com atributos de análise semelhantes a uma classe cmdlet ou a um objeto System.Management.Automation.RuntimeDefinedParameterDictionary .

Este provedor de navegação não implementa esse método. No entanto, o código a seguir é a implementação padrão de System.Management.Automation.Provider.NavigationCmdletProvider.MoveItemDynamicParameters*.

Normalizando um Caminho Relativo

Seu provedor de navegação implementa o método System.Management.Automation.Provider.NavigationCmdletProvider.NormalizeRelativePath* para normalizar o caminho totalmente qualificado indicado no path parâmetro como relativo ao caminho especificado pelo basePath parâmetro. O método retorna uma representação de string do caminho normalizado. Ele escreve um erro se o path parâmetro especificar um caminho inexistente.

O provedor de navegação de exemplo não substitui esse método. A seguir está a implementação padrão.

Coisas para Lembrar Sobre a Implementação do NormalizeRelativePath

Sua implementação de System.Management.Automation.Provider.NavigationCmdletProvider.NormalizeRelativePath* deve analisar o path parâmetro, mas não precisa usar análise sintática pura. Você é incentivado a projetar esse método para usar o caminho para buscar as informações do caminho no armazenamento de dados e criar um caminho que corresponda à sintaxe do caringamento e do caminho padronizado.

Exemplo de código

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

Definição de Tipos de Objetos e Formatação

É possível para um provedor adicionar membros a objetos existentes ou definir novos objetos. Para mais informações,veja Estendendo Tipos de Objeto e Formatação.

Construindo o provedor Windows PowerShell

Para mais informações, veja Como Registrar Cmdlets, Provedores e Aplicações Anfitriãs.

Testando o provedor 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 os cmdlets disponibilizados por derivação. Este exemplo testará o provedor de navegação por exemplo.

Execute seu novo shell e use o Set-Location cmdlet para definir o caminho que indicará o banco de dados Access.
```
Set-Location mydb:
```

Agora execute o Get-ChildItem cmdlet para recuperar uma lista dos itens do banco de dados, que são as tabelas disponíveis no banco de dados. Para cada tabela, esse cmdlet também recupera o número de linhas da tabela.

Get-ChildItem | Format-Table RowCount, Name -AutoSize

RowCount   Name
--------   ----
     180   MSysAccessObjects
       0   MSysACEs
       1   MSysCmdbars
       0   MSysIMEXColumns
       0   MSysIMEXSpecs
       0   MSysObjects
       0   MSysQueries
       7   MSysRelationships
       8   Categories
      91   Customers
       9   Employees
    2155   Order Details
     830   Orders
      77   Products
       3   Shippers
      29   Suppliers

Use o Set-Location cmdlet novamente para definir a localização da tabela de dados dos Funcionários.
```
Set-Location Employees
```
Agora vamos usar o Get-Location cmdlet para recuperar o caminho até a tabela dos Empregados.
```
Get-Location
```
```
Path
----
mydb:\Employees
```

Agora use o Get-ChildItem cmdlet transmitido ao Format-Table cmdlet. Esse conjunto de cmdlets recupera os itens para a tabela de dados Employees, que são as linhas da tabela. Eles são formatados conforme especificado pelo Format-Table cmdlet.

Get-ChildItem | Format-Table RowNumber, PSIsContainer, Data -AutoSize

RowNumber   PSIsContainer   Data
---------   --------------   ----
0           False            System.Data.DataRow
1           False            System.Data.DataRow
2           False            System.Data.DataRow
3           False            System.Data.DataRow
4           False            System.Data.DataRow
5           False            System.Data.DataRow
6           False            System.Data.DataRow
7           False            System.Data.DataRow
8           False            System.Data.DataRow

Agora você pode executar o Get-Item cmdlet para recuperar os itens da linha 0 da tabela de dados Employees.

Get-Item 0

PSPath        : AccessDB::C:\PS\Northwind.mdb\Employees\0
PSParentPath  : AccessDB::C:\PS\Northwind.mdb\Employees
PSChildName   : 0
PSDrive       : mydb
PSProvider    : System.Management.Automation.ProviderInfo
PSIsContainer : False
Data           : System.Data.DataRow
RowNumber      : 0

Use o Get-Item cmdlet novamente para recuperar os dados dos funcionários dos itens na linha 0.

(Get-Item 0).Data

EmployeeID      : 1
LastName        : Davis
FirstName       : Sara
Title           : Sales Representative
TitleOfCourtesy : Ms.
BirthDate       : 12/8/1968 12:00:00 AM
HireDate        : 5/1/1992 12:00:00 AM
Address         : 4567 Main Street
                  Apt. 2A
City            : Buffalo
Region          : NY
PostalCode      : 98052
Country         : USA
HomePhone       : (206) 555-9857
Extension       : 5467
Photo           : EmpID1.bmp
Notes           : Education includes a BA in psychology from
                  Colorado State University. She also completed "The
                  Art of the Cold Call."  Nancy is a member of
                  Toastmasters International.
ReportsTo       : 2