Criando um Provedor de Propriedades Windows PowerShell

Este tópico descreve como criar um provedor que permita ao usuário manipular as propriedades dos itens em um repositório de dados. Como consequência, esse tipo de provedor é chamado de provedor de propriedades Windows PowerShell. Por exemplo, o provedor de registro fornecido pelo Windows PowerShell lida com os valores-chave do registro como propriedades do item-chave do registro. Esse tipo de provedor deve adicionar a interface System.Management.Automation.Provider.IPropertyCmdletProvider à implementação da classe .NET.

Observação

O Windows PowerShell fornece um arquivo modelo que você pode usar para desenvolver um provedor de PowerShell para Windows. O arquivo TemplateProvider.cs está disponível no Microsoft Windows Software Development Kit para Windows Vista e Componentes de Runtime do .NET Framework 3.0. Para instruções de download, veja Como Instalar o Windows PowerShell e Baixar o Windows PowerShell SDK. O modelo baixado está disponível no <diretório PowerShell Samples> . Você deve fazer uma cópia desse arquivo e usá-la para criar um novo provedor de PowerShell para Windows, removendo qualquer funcionalidade que não precise. Para mais informações sobre outras implementações de provedores Windows PowerShell, veja Designing Your Windows PowerShell Provider.

Cuidado

Os métodos do seu provedor de imóveis devem escrever quaisquer objetos usando o método System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* .

Definindo o provedor Windows PowerShell

Um provedor de imóveis deve criar uma classe .NET que suporte a interface System.Management.Automation.Provider.IPropertyCmdletProvider . Aqui está a declaração padrão da classe do arquivo TemplateProvider.cs fornecido pelo Windows PowerShell.

Definindo a Funcionalidade Base

A interface System.Management.Automation.Provider.IPropertyCmdletProvider pode ser conectada a qualquer uma das classes base do provider, com exceção da classe System.Management.Automation.Provider.DriveCmdletProvider . Adicione a funcionalidade base exigida pela classe base que você está usando. Para mais informações sobre classes base, veja Designing Your Windows PowerShell Provider.

Recuperando Propriedades

Para recuperar propriedades, o provedor deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* para suportar chamadas do Get-ItemProperty cmdlet. Esse método recupera as propriedades do item localizado no caminho interno do provedor especificado (totalmente qualificado).

O providerSpecificPickList parâmetro indica quais propriedades recuperar. Se esse parâmetro for null ou vazio, o método deve recuperar todas as propriedades. Além disso, System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* escreve uma instância de um objeto System.Management.Automation.PSObject que representa um pacote de propriedades com as propriedades recuperadas. O método não deveria devolver nada.

Recomenda-se que a implementação do System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* suporte a expansão coringa dos nomes de propriedades para cada elemento na lista de escolha. Para isso, use a classe System.Management.Automation.WildcardPattern para realizar o correspondimento de padrões coringa.

Aqui está a implementação padrão de System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* a partir do arquivo TemplateProvider.cs fornecido pelo Windows PowerShell.

Coisas para Lembrar Sobre a Implementação do GetProperty

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

Ao definir a classe de provedor, um provedor de propriedade Windows PowerShell pode declarar as capacidades do provedor ExpandWildcards, Filtrar, Incluir ou Excluir da enumeração System.Management.Automation.Provider.ProviderCapabilities . Nesses casos, a implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* precisa garantir que o caminho passado para o método atenda aos requisitos das capacidades especificadas. Para isso, o método deve acessar a propriedade apropriada, por exemplo, as propriedades System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* .
Por padrão, as sobrescrituras desse método não devem recuperar um leitor para objetos que estão ocultos do usuário, a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Um erro deve ser escrito se o caminho representa um item oculto do usuário e System.Management.Automation.Provider.CmdletProvider.Force* for definido como false.

Anexando Parâmetros Dinâmicos ao Cmdlet Get-ItemProperty

O Get-ItemProperty cmdlet pode exigir parâmetros adicionais que são especificados dinamicamente em tempo de execução. Para fornecer esses parâmetros dinâmicos, o provedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* . O path parâmetro indica um caminho interno totalmente qualificado ao provedor, enquanto especifica providerSpecificPickList as propriedades específicas do provedor inseridas na linha de comando. Esse parâmetro pode ser null ou vazio se as propriedades forem direcionadas ao cmdlet. Nesse caso, 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 . O runtime do Windows PowerShell usa o objeto retornado para adicionar os parâmetros ao cmdlet.

Aqui está a implementação padrão de System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* do arquivo TemplateProvider.cs fornecido pelo Windows PowerShell.

Definindo propriedades

Para definir propriedades, o provedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* para suportar chamadas do Set-ItemProperty cmdlet. Esse método define uma ou mais propriedades do item no caminho especificado e sobrescreve as propriedades fornecidas conforme necessário. System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* também escreve uma instância de um objeto System.Management.Automation.PSObject que representa um pacote de propriedades das propriedades atualizadas.

Aqui está a implementação padrão de System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* a partir do arquivo TemplateProvider.cs fornecido pelo Windows PowerShell.

Coisas para lembrar sobre a implementação de Set-ItemProperty

As seguintes condições podem se aplicar a uma implementação de System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty*:

Ao definir a classe de provedor, um provedor de propriedade Windows PowerShell pode declarar as capacidades do provedor ExpandWildcards, Filtrar, Incluir ou Excluir da enumeração System.Management.Automation.Provider.ProviderCapabilities . Nesses casos, a implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* deve garantir que o caminho passado para o método atenda aos requisitos das capacidades especificadas. Para isso, o método deve acessar a propriedade apropriada, por exemplo, as propriedades System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* .
Por padrão, as sobrescrituras desse método não devem recuperar um leitor para objetos que estão ocultos do usuário, a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Um erro deve ser escrito se o caminho representa um item oculto do usuário e System.Management.Automation.Provider.CmdletProvider.Force* for definido como false.
Sua implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* 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, renomear 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 e cuidando de quaisquer configurações de linha de comando ou variáveis de preferência para determinar o que deve ser exibido.

Após a chamada para System.Management.Automation.Provider.CmdletProvider.ShouldProcess retornar true, se modificações potencialmente perigosas do sistema forem feitas, o método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* deve chamar o método System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Esse método envia uma mensagem de confirmação ao usuário para permitir feedback adicional indicando que a operação deve continuar.

Anexando parâmetros dinâmicos para o cmdlet Set-ItemProperty

O Set-ItemProperty cmdlet pode exigir parâmetros adicionais que são especificados dinamicamente em tempo de execução. Para fornecer esses parâmetros dinâmicos, o provedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* . 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 . O null valor pode ser retornado se não forem adicionados parâmetros dinâmicos.

Aqui está a implementação padrão de System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* do arquivo TemplateProvider.cs fornecido pelo Windows PowerShell.

Propriedades de Limpeza

Para limpar propriedades, o provedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* para suportar chamadas do Clear-ItemProperty cmdlet. Esse método define uma ou mais propriedades para o item localizado no caminho especificado.

Aqui está a implementação padrão de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* a partir do arquivo TemplateProvider.cs fornecido pelo Windows PowerShell.

Coisa para Lembrar Sobre a Implementação do ClearProperty

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

Ao definir a classe de provedor, um provedor de propriedade Windows PowerShell pode declarar as capacidades do provedor ExpandWildcards, Filtrar, Incluir ou Excluir da enumeração System.Management.Automation.Provider.ProviderCapabilities . Nesses casos, a implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* precisa garantir que o caminho passado para o método atenda aos requisitos das capacidades especificadas. Para isso, o método deve acessar a propriedade apropriada, por exemplo, as propriedades System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* .
Por padrão, as sobrescrituras desse método não devem recuperar um leitor para objetos que estão ocultos do usuário, a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Um erro deve ser escrito se o caminho representa um item oculto do usuário e System.Management.Automation.Provider.CmdletProvider.Force* for definido como false.
Sua implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* 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 antes de uma alteração no estado do sistema, como limpar conteúdo. 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.

Após a chamada para System.Management.Automation.Provider.CmdletProvider.ShouldProcess retornar true, se modificações potencialmente perigosas do sistema forem feitas, o método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* deve chamar o método System.Management.Automation.Provider.CmdletProvider.ShouldContinue . Esse método envia uma mensagem de confirmação ao usuário para permitir feedback adicional indicando que a operação potencialmente perigosa deve continuar.

Anexando Parâmetros Dinâmicos ao Cmdlet Clear-ItemProperty

O Clear-ItemProperty cmdlet pode exigir parâmetros adicionais que são especificados dinamicamente em tempo de execução. Para fornecer esses parâmetros dinâmicos, o provedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* . 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 . O null valor pode ser retornado se não forem adicionados parâmetros dinâmicos.

Aqui está a implementação padrão de System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* do arquivo TemplateProvider.cs fornecido pelo Windows PowerShell.