Compartilhar via

Agentes de extensão de cmdlet

  • Artigo

Aplica-se a: Exchange Server 2013

Agentes de extensão de cmdlet são componentes do Microsoft Exchange Server 2013 invocados pelos cmdlets do Exchange 2013 quando os cmdlets são executados. Como o nome sugere, os agentes de extensão de cmdlet estendem as capacidades dos cmdlets que os invocam, auxiliando no processamento de dados ou realizando ações adicionais com base nas exigências do cmdlet. Agentes de extensão de cmdlet estão disponíveis em qualquer função de servidor.

Os agentes podem modificar, substituir ou estender a funcionalidade de cmdlets do Shell de Gerenciamento do Exchange. Um agente pode fornecer um valor para um parâmetro exigido que não seja fornecido em um comando, substituir um valor fornecido por um usuário, realizar outras ações externas ao fluxo de trabalho do cmdlet enquanto um cmdlet é executado e mais.

Por exemplo, o cmdlet New-Mailbox aceita o parâmetro Database que especifica o banco de dados de caixa de correio no qual será criada uma nova caixa de correio. No Microsoft Exchange Server 2007, se você não especificar o parâmetro Banco de Dados ao executar o cmdlet New-Mailbox, o comando falhará. No entanto, no Exchange 2013, o cmdlet New-Mailbox invoca o Mailbox Resources Management agente quando o cmdlet é executado. Se o parâmetro Banco de Dados não for especificado, o Mailbox Resources Management agente determinará automaticamente um banco de dados de caixa de correio adequado para criar a nova caixa de correio e inserir esse valor no parâmetro Banco de Dados .

Os agentes de extensão de cmdlet somente podem ser invocados pelos cmdlets do Exchange 2013 e do Microsoft Exchange Server 2010. Exchange 2007 Os cmdlets e cmdlets fornecidos por outros produtos da Microsoft e de terceiros não invocam os agentes de extensão de cmdlet. Os scripts também não podem invocar agentes de extensão de cmdlet diretamente. Entretanto, se os scripts contiverem cmdlets do Exchange 2013, aqueles cmdlets continuarão chamando os agentes de extensão de cmdlet.

Procurando tarefas de gerenciamento relacionadas a agentes de extensão de cmdlet? Consulte Gerenciar agentes de extensão de cmdlet.

Prioridade do agente

A prioridade de um agente determina a ordem em que o agente é invocado quando um cmdlet é executado. Agentes de maior prioridade, próxima a zero, são invocados primeiro. A prioridade de um agente se torna importante quando dois ou mais agentes tentam definir o valor da mesma propriedade. O agente de maior prioridade a tentar definir um valor de propriedade será bem-sucedido, e todas as tentativas subsequentes de definir a mesma propriedade por agentes de menor prioridade são ignoradas. Por exemplo, se a propriedade Name em um objeto for modificada por um agente com prioridade três e outro agente com prioridade seis modificar o mesmo objeto, a modificação feita pelo agente com a prioridade seis será ignorada.

Se você quiser usar o Scripting agent para definir o valor das propriedades que podem ser definidas por outros agentes de maior prioridade, você terá as seguintes opções:

  • Desabilitar o agente que define a propriedade no momento.

  • Defina a Scripting agent como uma prioridade maior do que o agente existente que você deseja substituir.

  • Mantenha as prioridades dos agentes iguais e verifique se o script executado sob o Scripting agent respeita o valor fornecido pelos outros agentes.

Aviso

Alterar a prioridade ou substituir a funcionalidade de uma agente integrado é uma operação avançada. Certifique-se de ter entendido completamente as alterações que está realizando.

Para mais informações sobre a alteração da prioridade de um agente, consulte Gerenciar agentes de extensão de cmdlet.

Agentes de transporte internos

Exchange 2013 inclui vários agentes que podem ser invocados quando um cmdlet é executado. A tabela a seguir lista os agentes, sua ordem e se os agentes estão habilitados por padrão. Não é possível adicionar ou remover agentes de um servidor que executa o Exchange 2013. No entanto, você pode usar o Scripting agent para executar scripts Windows PowerShell para estender a funcionalidade dos cmdlets que o usam. Para obter mais informações sobre o Scripting agent, consulte a seção "Agente de script" mais tarde neste tópico.

Você pode habilitar ou desabilitar a maioria dos agentes ou alterar a prioridade dos agentes se quiser substituir a funcionalidade de um agente específico pela funcionalidade que você fornece em um script personalizado que você chama usando o Scripting agent. No entanto, alguns agentes não podem ser desativados. Agentes que não podem ser desabilitados são chamados de agentes do sistema e têm sua propriedade IsSystem definida como $True. A tabela a seguir fornece informações sobre agentes de extensão de cmdlet do Exchange 2013, incluindo agentes do sistema.

A configuração para agentes é armazenada no nível da organização. Quando você ativa ou desativa um agente, ou quando determina sua prioridade, você define a configuração daquele agente em todos os servidores da organização. A exceção é adicionar scripts ao Scripting agent. Você deve atualizar os scripts em cada servidor individualmente. Para obter mais informações sobre como configurar scripts para uso com o Scripting agent, consulte a seção "Agente de scripts" mais tarde neste tópico.

Aviso

Alterar a prioridade de agentes, ou habilitar e desabilitar agentes, pode causar efeitos indesejados se você não compreender completamente o que cada agente faz e como eles interagem com os cmdlets do Exchange. Antes de alterar a configuração de um agente, certifique-se de compreender totalmente as alterações e os resultados que deseja, e de verificar se o script personalizado irá funcionar conforme o pretendido.

Agentes de extensão de cmdlet do Exchange 2013

Nome do Agente Prioridade Habilitada por padrão Agente de sistema
Admin Audit Log agent 255 Verdadeiro Sim
Scripting agent 6 Falso Não
Mailbox Resources Management agent 5 Verdadeiro Não
OAB Resources Management agent 4 Verdadeiro Não
Query Base DN agent 3 Verdadeiro Não
Provisioning Policy agent 2 Verdadeiro Não
Rus agent 1 Verdadeiro Não
Mailbox Creation Time agent 0 Verdadeiro Não

Agente de script

Você pode usar o Scripting agent agente de extensão de cmdlet no Exchange 2013 para inserir sua própria lógica de script na execução de cmdlets do Exchange. Usando o Scripting agent, você pode adicionar condições, substituir valores e configurar relatórios.

Aviso

Quando você habilita o Scripting agent agente de extensão de cmdlet, o agente é invocado sempre que um cmdlet é executado em um servidor que executa o Exchange 2013. Isso inclui não apenas cmdlets executados diretamente por você no Shell de Gerenciamento do Exchange, mas também cmdlets executados pelos serviços do Exchange e o Centro de administração do Exchange (EAC). Recomendamos que você teste seus scripts e todas as alterações feitas no arquivo de configuração antes de copiar o arquivo de configuração atualizado para seus servidores do Exchange 2013 e habilite o agente de extensão de Scripting agent cmdlet.

Sempre que um cmdlet do Exchange é executado, o cmdlet invoca o agente de extensão de Scripting agent cmdlet. Quando esse agente é chamado, o cmdlet verifica se algum script está configurado para ser invocado por ele. Caso um script deva ser executado para um cmdlet, este tentará invocar todas as APIs definidas no script. As seguintes APIs estão disponíveis e são invocadas na seguinte ordem:

  1. ProvisionDefaultProperties: essa API pode ser usada para definir valores de propriedades em objetos quando eles são criados. Quando um valor é definido, esse valor é retornado ao cmdlet e o cmdlet define o valor na propriedade. Você pode preencher os valores nas propriedades se o usuário não tiver especificado um valor ou substituir o valor especificado pelo usuário. Essa API respeita os valores definidos pelos agentes de prioridade mais alta. O Scripting agent agente de extensão de cmdlet não substituirá os valores definidos por agentes de prioridade mais alta.

  2. UpdateAffectedIConfigurable: essa API pode ser usada para definir valores de propriedades em objetos após a conclusão de todo o processamento, mas a Validate API ainda não foi invocada. Essa API respeita os valores definidos pelos agentes de prioridade mais alta. O Scripting agent agente de extensão de cmdlet não substituirá os valores definidos por agentes de prioridade mais alta.

  3. Validar: essa API pode ser usada para validar os valores nas propriedades de um objeto que estão prestes a ser definidas pelo cmdlet. Essa API é chamada um pouco antes de um cmdlet gravar algum dado. Você pode configurar verificações de validação que permitem que um cmdlet tenha êxito ou falhe. Se um cmdlet for aprovado nas verificações de validação nessa API, ele terá permissão para gravar os dados. Se o cmdlet não for aprovado nas verificações de validação, ele retornará todos os erros definidos nessa API.

  4. OnComplete: essa API é usada depois que todo o processamento de cmdlet é concluído. Pode ser usada para executar tarefas posteriores ao processamento, como gravação de dados em um banco de dados externo.

Observação

O Scripting agent agente de extensão de cmdlet não é invocado quando cmdlets com o Get verbo são executados.

Arquivo de configuração do Agente de script

O Scripting agent arquivo de configuração contém todos os scripts que você deseja Scripting agent executar. Os scripts no arquivo de configuração estão contidos nas marcas XML que definem o começo e o fim do script e os vários parâmetros de entrada necessários para passar os dados ao script. Os scripts são escritos com o uso da sintaxe Windows PowerShell. O arquivo de configuração é um arquivo XML que usa os elementos ou atributos na tabela a seguir.

Atributos do arquivo de configuração do Agente de script

Elemento Atributo Descrição
Configuration Não aplicável Esse elemento contém todos os scripts que o Scripting agent agente de extensão cmdlet pode executar. A Feature marca é uma criança dessa marca.

Há apenas uma Configuration marca no arquivo de configuração.
Feature Não aplicável Esse elemento contém um conjunto de scripts relacionados a um recurso. Cada script, definido na ApiCall marca filho, estende uma parte específica do pipeline de execução de cmdlet. Essa marca contém os Name atributos e Cmdlets .

Pode haver várias Feature marcas na Configuration marca.
Name Esse atributo contém o nome do recurso. Use esse atributo para ajudar a identifica qual recurso é estendido pelos scripts contidos na marca.
Cmdlets Esse atributo contém uma lista dos cmdlets do Exchange usados pelo conjunto de scripts dessa extensão de recurso. É possível especificar vários cmdlets separando cada cmdlet com uma vírgula.
ApiCall Não se aplica Esse elemento contém scripts que podem estender uma parte do pipeline de execução do cmdlet. Cada script é definido pelo nome de chamada da API no pipeline de execução do cmdlet sendo estendido. A seguir, os nomes de API que podem ser estendidos:
  • ProvisionDefaultProperties
  • UpdateAffectedIConfigurable
  • Validate
  • OnComplete
Name Esse atributo inclui o nome da chamada de API que está estendendo o pipeline de execução do cmdlet.
Common Não se aplica Esse elemento contém funções que podem ser usadas por qualquer script no arquivo de configuração.

Cada servidor do Exchange 2013 inclui o arquivo ScriptingAgentConfig.xml.sample na %ExchangeInstallPath%CmdletExtensionAgents pasta. Esse arquivo deve ser renomeado como ScriptingAgentConfig.xml em cada servidor Exchange 2013 se você habilitar o agente de extensão do cmdlet Scripting Agent. O arquivo de configuração de amostra contém scripts de amostra que podem ser usados para ajudá-lo a entender como adicionar scripts ao arquivo de configuração.

Após você adicionar um script ao arquivo de configuração ou se você fizer uma mudança no arquivo de configuração, será preciso atualizar o arquivo em todos os servidores Exchange 2013 de sua organização. Isso deve ser feito para garantir que cada servidor contenha uma versão atualizada dos scripts que o agente de extensão de Scripting Agent cmdlet executa.

Alguns caracteres geralmente usados nos scripts também têm um significado especial no XML. Para usar esses caracteres no seu script, seu sequências de escape. Por exemplo, os seguintes caracteres usam uma sequência de escape:

  • Em vez de um sinal maior que ( > ), use >
  • Em vez de um sinal menor que ( < ), use $lt;
  • Em vez de um ampersand ( & ), use &amp;

Habilitar o Agente de script

O Scripting agent agente de extensão de cmdlet é desabilitado por padrão. Quando você habilita o Scripting agent, o agente é habilitado para toda a organização do Exchange 2013. Antes de habilitar o Scripting agent, verifique se o Scripting agent arquivo de configuração foi corretamente renomeado e atualizado com seus scripts em cada servidor do Exchange 2013. Você receberá uma mensagem de erro sempre que um cmdlet for executado se não renomear o arquivo de configuração corretamente ou copiar um arquivo de configuração para esse computador a partir de outro servidor do Exchange 2013.

Para habilitar o Scripting agent, você deve fazer o seguinte:

  1. Renomeie o arquivo ScriptingAgentConfig.xml.sample para ScriptingAgentConfig.xml em %ExchangeInstallPath%Bin\CmdletExtensionAgents cada servidor do Exchange 2013 em sua organização.

    Observação

    É possível copiar o arquivo de configuração de um servidor Exchange 2013 para outros servidores Exchange 2013. Certifique-se de atualizar o arquivo de configuração que deseja copiar antes de copiá-lo.

  2. Adicione seu script ao arquivo de configuração renomeado em cada servidor Exchange 2013 de sua organização.

  3. Habilite o Scripting agent agente de extensão de cmdlet. Para mais informações sobre como habilitar os agentes de extensão do cmdlet, consulte Gerenciar agentes de extensão de cmdlet.

Prioridade do Agente de Scripts

Por padrão, o Scripting agent agente de extensão de cmdlet é executado após todos os outros agentes, com exceção do Scripting agent agente. Se quiser um script criado para substituir um agente existente, desabilite o outro agente ou altere a prioridade de qualquer agente para que o agente de extensão de Scripting agent cmdlet seja executado primeiro. Para obter mais informações sobre como desabilitar ou alterar as prioridades dos agentes, consulte Gerenciar agentes de extensão de cmdlet.