Criação de um Fornecedor de Propriedades Windows PowerShell

Este tópico descreve como criar um fornecedor que permita ao utilizador manipular as propriedades dos itens num armazenamento de dados. Como consequência, este tipo de fornecedor é referido como fornecedor de propriedades Windows PowerShell. Por exemplo, o fornecedor do Registo fornecido pelo Windows PowerShell trata os valores-chave do registo como propriedades do item-chave do registo. Este tipo de fornecedor deve adicionar a interface System.Management.Automation.Provider.IPropertyCmdletProvider à implementação da classe .NET.

Observação

O Windows PowerShell fornece um ficheiro modelo que pode usar para desenvolver um fornecedor Windows PowerShell. O ficheiro TemplateProvider.cs está disponível no Microsoft Windows Software Development Kit para Windows Vista e .NET Framework 3.0 Runtime Components. Para instruções de download, consulte Como Instalar o Windows PowerShell e Descarregar o Windows PowerShell SDK. O modelo descarregado está disponível no <diretório PowerShell Samples> . Deves fazer uma cópia deste ficheiro e usar a cópia para criar um novo fornecedor de PowerShell para Windows, removendo qualquer funcionalidade que não precises. Para mais informações sobre outras implementações de fornecedores Windows PowerShell, consulte Designing Your Windows PowerShell Provider.

Atenção

Os métodos do seu fornecedor imobiliário devem escrever quaisquer objetos usando o método System.Management.Automation.Provider.CmdletProvider.Writepropertyobject* .

Definição do fornecedor Windows PowerShell

Um fornecedor de propriedades deve criar uma classe .NET que suporte a interface System.Management.Automation.Provider.IPropertyCmdletProvider . Aqui está a declaração de classe padrão do ficheiro TemplateProvider.cs fornecido pelo Windows PowerShell.

Definição da Funcionalidade Base

A interface System.Management.Automation.Provider.IPropertyCmdletProvider pode ser ligada 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 está a usar. Para mais informações sobre classes base, consulte Desenhar o Seu Fornecedor PowerShell para Windows.

Recuperação de Propriedades

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

O providerSpecificPickList parâmetro indica quais as propriedades a recuperar. Se este parâmetro for null ou vazio, o método deverá 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 das propriedades recuperadas. O método não deverá devolver nada.

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

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

Coisas a Lembrar Sobre a Implementação do GetProperty

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

Ao definir a classe de fornecedor, um fornecedor de propriedades Windows PowerShell pode declarar capacidades de fornecedor de ExpandWildcards, Filtrar, Incluir ou Excluir, da enumeração System.Management.Automation.Provider.ProviderCapabilities . Nestes casos, a implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.GetProperty* precisa de garantir que o caminho passado para o método cumpre os requisitos das capacidades especificadas. Para isso, o método deve aceder à propriedade apropriada, por exemplo, as propriedades System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* .
Por defeito, as sobreposições deste método não devem recuperar um leitor para objetos que estão ocultos ao utilizador, a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Deve ser escrito um erro se o caminho representar um item oculto ao utilizador e se System.Management.Automation.Provider.CmdletProvider.Force* estiver definido como false.

Anexação de 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 estes parâmetros dinâmicos, o fornecedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.GetPropertyDynamicParameters* . O path parâmetro indica um caminho interno do fornecedor totalmente qualificado, enquanto o providerSpecificPickList parâmetro especifica as propriedades específicas do fornecedor inseridas na linha de comandos. Este parâmetro pode ser null ou vazio se as propriedades forem canalizadas para o cmdlet. Neste caso, este método devolve um objeto que tem 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 devolvido para adicionar os parâmetros ao cmdlet.

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

Propriedades de configuração

Para definir propriedades, o fornecedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* para suportar chamadas do Set-ItemProperty cmdlet. Este 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 ficheiro TemplateProvider.cs fornecido pelo Windows PowerShell.

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

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

Ao definir a classe de fornecedor, um fornecedor de propriedades Windows PowerShell pode declarar capacidades de fornecedor de ExpandWildcards, Filtrar, Incluir ou Excluir, da enumeração System.Management.Automation.Provider.ProviderCapabilities . Nestes casos, a implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* deve garantir que o caminho passado para o método cumpre os requisitos das capacidades especificadas. Para isso, o método deve aceder à propriedade apropriada, por exemplo, as propriedades System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* .
Por defeito, as sobreposições deste método não devem recuperar um leitor para objetos que estão ocultos ao utilizador, a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Deve ser escrito um erro se o caminho representar um item oculto ao utilizador e se System.Management.Automation.Provider.CmdletProvider.Force* estiver definido como false.
A sua implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.SetProperty* deve chamar System.Management.Automation.Provider.CmdletProvider.ShouldProcess e verificar o seu valor de retorno antes de fazer quaisquer alterações ao armazenamento de dados. Este método é usado para confirmar a execução de uma operação quando é feita uma alteração no estado do sistema, por exemplo, renomear ficheiros. System.Management.Automation.Provider.CmdletProvider.ShouldProcess envia o nome do recurso a ser alterado para o utilizador, com o runtime do Windows PowerShell e tratando de quaisquer definições de linha de comandos ou variáveis de preferência para determinar o que deve ser exibido.

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

Anexação de 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 estes parâmetros dinâmicos, o fornecedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.SetPropertyDynamicParameters* . Este método devolve um objeto que tem 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 devolvido se não forem adicionados parâmetros dinâmicos.

Propriedades de Limpeza

Para limpar propriedades, o fornecedor de propriedades Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* para suportar chamadas do Clear-ItemProperty cmdlet. Este 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 ficheiro TemplateProvider.cs fornecido pelo Windows PowerShell.

Coisa a Lembrar Sobre a Implementação do ClearProperty

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

Ao definir a classe de fornecedor, um fornecedor de propriedades Windows PowerShell pode declarar capacidades de fornecedor de ExpandWildcards, Filtrar, Incluir ou Excluir, da enumeração System.Management.Automation.Provider.ProviderCapabilities . Nestes casos, a implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* precisa de garantir que o caminho passado para o método cumpre os requisitos das capacidades especificadas. Para isso, o método deve aceder à propriedade apropriada, por exemplo, as propriedades System.Management.Automation.Provider.CmdletProvider.Exclude* e System.Management.Automation.Provider.CmdletProvider.Include* .
Por defeito, as sobreposições deste método não devem recuperar um leitor para objetos que estão ocultos ao utilizador, a menos que a propriedade System.Management.Automation.Provider.CmdletProvider.Force* esteja definida como true. Deve ser escrito um erro se o caminho representar um item oculto ao utilizador e se System.Management.Automation.Provider.CmdletProvider.Force* estiver definido como false.
A sua implementação do método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearProperty* deve chamar System.Management.Automation.Provider.CmdletProvider.ShouldProcess e verificar o seu valor de retorno antes de fazer quaisquer alterações ao armazenamento de dados. Este método é usado para confirmar a execução de uma operação antes de ser feita uma alteração ao estado do sistema, como limpar conteúdo. System.Management.Automation.Provider.CmdletProvider.ShouldProcess envia o nome do recurso a ser alterado para o utilizador, com o runtime do Windows PowerShell a ter em conta quaisquer definições de linha de comandos ou variáveis de preferência para determinar o que deve ser exibido.

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

Anexação de 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 estes parâmetros dinâmicos, o fornecedor de propriedades do Windows PowerShell deve implementar o método System.Management.Automation.Provider.IPropertyCmdletProvider.ClearPropertyDynamicParameters* . Este método devolve um objeto que tem 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 devolvido se não forem adicionados parâmetros dinâmicos.

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