Documentação de produtos
Citrix Virtual Apps and Desktops
Service Current Release 2402 LTSR 2311 2308 2305 2303 2212 2209 2206 2203 LTSR 1912 LTSR
Ver PDF

Solucionar problemas de configuração automatizada e informações adicionais

January 23, 2026
Contribuição de: 
C

Importante:

Para mensagens de erro comuns da Configuração automatizada e soluções correspondentes, consulte o FAQ de solução de problemas no artigo da Central de Conhecimento CTX277730.

Erros da ferramenta de configuração automatizada

As operações da ferramenta de configuração automatizada podem, às vezes, produzir erros. Quando isso acontece, podem ocorrer falhas ao processar componentes como Catálogos de Máquinas, Grupos de Entrega ou Políticas de Grupo, por exemplo. O uso de OnErrorAction e parâmetros de continuação permite que você capture erros durante o processamento, resolva-os e continue de onde parou.

O valor padrão de OnErrorAction é StopCompEnd. Quando ocorre um erro, a ferramenta conclui o processamento do componente atual. Nenhum componente adicional é processado, e os erros não são propagados para componentes subsequentes e dependentes. Depois de resolver quaisquer erros, você pode executar novamente seus cmdlets com qualquer parâmetro de continuação aplicado.

Parâmetro OnErrorAction

Você pode definir valores de parâmetro OnErrorAction em comandos de migração para controlar como a ferramenta responde aos erros que encontra ao processar componentes.

Esta tabela mostra os valores dos parâmetros e suas descrições:

Valor Descrição
Continue Tenta processar o máximo de todos os componentes possível.
Pause Pausa no final do processamento e solicita que você continue ou pare.
StopCompEnd Tenta processar o máximo do componente possível. Para após a conclusão do componente. (Padrão)
StopImmediately O processamento para quando um erro é encontrado.

Cmdlets de migração

Você pode aplicar o parâmetro OnErrorAction aos seguintes comandos de migração:

  • Compare-CvadAcToSite
  • Import-CvadAcToSite
  • Merge-CvadAcToSite
  • New-CvadAcToSite
  • Restore-CvadAcToSite

Exemplo: Merge-CvadAcToSite -OnErrorAction StopImmediately

Parâmetros de retomada

Esses parâmetros definem como a ferramenta retoma após uma operação pausar ou parar devido a um erro.

Você pode aplicar parâmetros de retomada a cmdlets de migração que incluem um dos seguintes valores de parâmetro OnErrorAction:

  • Pause
  • StopCompEnd
  • StopImmediately

Esta tabela mostra os valores dos parâmetros e suas descrições:

Valor Descrição
-AllRemaining Requer um componente inicial. O processamento começa no componente inicial e processa todos os componentes restantes. Vários componentes são processados.
-Resume Usa o componente de CurrentComponent.txt como ponto de partida. Todos os restantes são definidos como verdadeiros. Vários componentes são processados.
-Repeat Usa o componente de CurrentComponent.txt como ponto de partida. Todos os restantes são definidos como falsos. Apenas um componente é processado.

O último componente processado é armazenado no arquivo CurrentComponent.txt na pasta AutoConfig. Não é recomendável editar este arquivo. Se você especificar -Resume ou -Repeat, e CurrentComponent.txt estiver ausente ou inválido, o processamento para e você é solicitado a selecionar um componente.

Definindo o OnErrorAction no arquivo CustomerInfo.yml

Você também pode definir valores de OnErrorAction no arquivo CustomerInfo.yml. Defina os valores usando os seguintes cmdlets:

  • Para um novo arquivo: New-CvadAcCustomerInfoFile -OnErrorAction Continue | Pause | StopCompEnd | StopImmediately
  • Para um arquivo existente: Set-CvadAcCustomerInfoFile -OnErrorAction Continue | Pause | StopCompEnd | StopImmediately

Logs

A execução de qualquer cmdlet resulta na criação de um arquivo de log e em uma entrada no arquivo de log de histórico principal. Todos os arquivos de log de operação são colocados em uma pasta de backup. Todos os nomes de arquivo de log começam com CitrixLog, e então mostram a operação de configuração automática e a data e hora da execução do cmdlet. Os logs não são excluídos automaticamente.

O log de histórico principal está localizado em *%HOMEPATH%\Documents\Citrix\AutoConfig*, no arquivo chamado History.Log. Cada execução de cmdlet resulta em uma entrada de log principal contendo a data, operação, resultado, backup e locais dos arquivos de log da execução.

Você também pode usar o cmdlet New-CvadAcZipInfoForSupport para coletar logs e enviá-los à Citrix para suporte. Este cmdlet compacta todos os arquivos de log e .yml em um único arquivo zip. Informações confidenciais do cliente (CustomerInfo.yml e CvadAcSecurity.yml) não são incluídas no arquivo zip. O arquivo Icon.yml também é excluído devido ao seu tamanho. O arquivo zip é colocado em %HOMEPATH%\Documents\Citrix\AutoConfig e nomeado CvadAcSupport_yyyy_mm_dd_hh_mm_ss.zip, com base na data e hora. Este arquivo zip também pode servir como backup.

Cada arquivo de log inclui o seguinte:

  • O nome da operação e se o modo de verificação está habilitado
  • A data e hora de início e término
  • Múltiplas entradas para as ações de cada componente e notificações de sucesso/falha
  • Resumo das ações realizadas, incluindo várias contagens de objetos criados
  • Correções sugeridas, quando aplicável
  • Local da pasta de backup, quando aplicável
  • Local do log principal
  • Duração

Arquivos de diagnóstico

Os arquivos de diagnóstico ajudam você a determinar e resolver problemas. Os seguintes arquivos são criados quando a operação correspondente é executada. Eles estão localizados na subpasta específica da ação em %HOMEPATH%\Documents\Citrix\AutoConfig. Inclua esses arquivos ao fornecer informações para suporte à resolução de problemas.

Exportar

PoshSdk_yyyy_mm_dd_hh_mm_ss.ps1

Este arquivo contabiliza todas as chamadas do SDK do Broker PowerShell feitas para exportar a configuração do site para arquivos.

Importar, Mesclar, Restaurar, Sincronizar, Fazer Backup, Comparar

Transaction_yyyy_mm_dd_hh_mm_ss.txt

Este arquivo documenta cada chamada de API Rest e informações relacionadas.

RestApiContent_yyyy_mm_dd_hh_mm_ss.txt

Este arquivo contém todo o conteúdo da API Rest de Add, Update e Delete.

Problemas resultantes de dependências

Importações e mesclagens podem falhar devido a dependências ausentes. Alguns problemas comuns são:

  1. As Políticas de Grupo estão sem filtros de grupo de entrega. As causas usuais são grupos de entrega que não foram importados.
  2. Os aplicativos falham ao importar ou mesclar. A causa usual é a falta de grupos de entrega ou grupos de aplicativos que não foram importados.
  3. Os grupos de aplicativos estão sem uma RestrictToTag. As causas usuais são tags que não foram importadas.
  4. As conexões de host falham. A causa usual é a falta de informações de segurança no arquivo CvadAcSecurity.yml.
  5. Os catálogos de máquinas falham. A causa usual são as conexões de host que não foram importadas.
  6. Máquinas ausentes de catálogos de máquinas e grupos de entrega. A causa usual são máquinas que não foram encontradas no Active Directory.
  7. Usuários ausentes de grupos de entrega. A causa usual são usuários que não foram encontrados no Active Directory.

Recomendações

  • Não execute mais de uma instância da Configuração automatizada por vez. A execução de várias instâncias simultâneas produz resultados imprevisíveis no site da nuvem. Se isso ocorrer, execute novamente uma instância da Configuração automatizada para levar o site ao estado esperado.
  • Não trabalhe nem altere dados no Studio enquanto a Configuração automatizada estiver em execução.
  • Sempre verifique visualmente os resultados de mesclagem, importação ou restauração no Studio para garantir que o site da nuvem atenda às expectativas.

Pastas

Localização raiz da pasta padrão

Todas as operações da ferramenta de configuração automatizada ocorrem na pasta raiz ou em subpastas dentro dela. A pasta raiz está localizada em %HOMEPATH%\Documents\Citrix\AutoConfig.

Exportar

Todos os arquivos exportados são colocados em dois locais de pasta, proporcionando facilidade de uso e um histórico de exportações. As exportações são sempre colocadas na pasta raiz. Cópias são colocadas em uma subpasta chamada Export com a data e hora da exportação.

A pasta raiz sempre contém a configuração do site local exportada mais recentemente. Cada subpasta Export contém a exportação feita na data e hora indicadas, o que mantém um histórico de exportações. Você pode usar qualquer subpasta Export para configurar o site da nuvem. A Configuração automatizada não exclui nem modifica subpastas de exportação existentes.

Importar/Mesclar/Sincronizar/Comparar

As operações de Import, Merge e Compare sempre são originadas de arquivos localizados na pasta raiz. Cada operação resulta na criação de uma subpasta para a qual os arquivos na pasta raiz são copiados, fornecendo um histórico de arquivos de origem que alteram o site da nuvem.

Restaurar

A operação Restore usa uma subpasta existente para configurar o site da nuvem. A pasta de origem é especificada no parâmetro -RestoreFolder obrigatório. Ao contrário de outros comandos, nenhuma nova subpasta é criada porque a operação Restore usa uma subpasta existente. A pasta de restauração pode ser a pasta raiz, mas ainda deve ser especificada no parâmetro -RestoreFolder.

Backups

A Configuração Automatizada inicializa, atualiza e faz backup de uma configuração de site da nuvem. Quando usada ao longo do tempo, muitas configurações diferentes podem mudar no site da nuvem. Para facilitar o uso a longo prazo e preservar as alterações do histórico, a Configuração Automatizada usa um esquema de preservação para salvar esse histórico de alterações e fornecer um método para restaurar estados anteriores.

Os backups da configuração do site da nuvem são sempre feitos em uma subpasta chamada Backup com a data e hora do backup. A Configuração Automatizada não exclui nem modifica subpastas de exportação existentes.

Você pode usar os backups para restaurar componentes específicos ou sua configuração inteira. Para restaurar todo o grupo de entrega e os componentes do catálogo de máquinas, use o cmdlet:

Restore-CvadAcToSite -RestoreFolder %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss -DeliveryGroups -MachineCatalogs

Nota:

As informações do arquivo de backup no cmdlet anterior são baseadas em seus próprios backups.

Para restaurar toda a configuração do site da nuvem, use o cmdlet:

Restore-CvadAcToSite -RestoreFolder %HOMEPATH%\Documents\Citrix\AutoConfig/Backup_yyyy_mm_dd_hh_mm_ss

Nota:

As informações do arquivo de backup no cmdlet anterior são baseadas em seus próprios backups.

Alterando a pasta raiz padrão

As operações de Export, Import, Merge, Sync e Compare podem alterar a pasta raiz padrão usando o parâmetro –AlternateFolder. A criação e o gerenciamento de subpastas por operação permanecem os mesmos conforme descrito anteriormente.

Arquivos copiados para subpastas

Todos os arquivos com extensão “.yml” são copiados para subpastas de operação, exceto os seguintes:

  • CustomerInfo.yml
  • ZoneMapping.yml
  • CvadAcSecurity.yml

Backups automáticos de segurança do site da nuvem

Um backup da configuração atual do site da nuvem é feito antes de executar operações que alteram a configuração. Isso inclui os parâmetros Import, Merge, Sync e Restore. O backup está sempre em uma subpasta abaixo da subpasta operacional.

No caso de Restore, a pasta de backup é uma subpasta da pasta especificada no parâmetro -RestoreFolder.

Automação

Os cmdlets da ferramenta de configuração automatizada podem ser executados em scripts de automação sem intervenção do administrador, suprimindo os prompts e a exibição dos resultados do log na conclusão do cmdlet. Você também pode definir parâmetros para fazer o mesmo usando o arquivo CustomerInfo.yml.

Adicione o seguinte parâmetro aos cmdlets de modificação da nuvem para suprimir a exibição de prompts.

-Confirm $false

Adicione o seguinte parâmetro aos cmdlets para suprimir a exibição do log na conclusão do cmdlet.

-DisplayLog $false

Adicione o seguinte parâmetro aos cmdlets para suprimir o registro em log na janela de comando do PowerShell.

-Quiet

Como outro método, os seguintes parâmetros podem ser colocados no arquivo CustomerInfo.yml.

Confirm: False

DisplayLog: False

Exportando de PCs que não sejam o Delivery Controller™

A ferramenta de configuração automatizada usa vários SDKs do Citrix PowerShell para exportar a configuração do site local para arquivos. Esses SDKs são instalados automaticamente no Delivery Controller, permitindo que a ferramenta seja executada no Delivery Controller sem ações extras. Ao executar em máquinas que não são Delivery Controller, é necessário instalar o conjunto de SDKs do Citrix PowerShell necessários para a ferramenta. Este conjunto de SDKs faz parte do Citrix Studio, que pode ser instalado a partir da mídia de instalação do Citrix Virtual Apps and Desktops™.

Nota:

A Configuração automatizada não pode ser executada no Cloud Connector.

Migrando para o Citrix Cloud™ Government e Japan Control Plane

Os ambientes Citrix Cloud Government e Japan Control Plane usam diferentes pontos de acesso para autenticar e alocar tokens de acesso. Este requisito exclusivo se aplica a qualquer ferramenta de configuração automatizada que acesse a nuvem. Execute as seguintes etapas para usar a Configuração automatizada nesses ambientes.

  1. Na pasta %HOMEPATH%\Documents\Citrix\AutoConfig, edite CustomerInfo.yml.

  2. Adicione uma das seguintes linhas, dependendo do ambiente ao qual você deseja se conectar, ao CustomerInfo.yml (ou altere-a, se já estiver presente).

    Environment: 'ProductionGov'

    ou

    Environment: 'ProductionJP'

A Configuração Automatizada agora pode ser usada nesses ambientes.

Coleta de dados do Citrix Cloud

Para obter informações sobre quais dados o Citrix Cloud coleta, consulte Citrix Cloud Services Customer Content and Log Handling.

Recursos adicionais

Fórum de discussão

Visite o fórum de discussão da Citrix para Configuração Automatizada.

Vídeo

Assista a Under the Hood of the Automated Configuration Tool for Citrix Virtual Apps and Desktops no YouTube.

Treinamento

O Cloud Learning Center contém guias em vídeo passo a passo para construir uma implantação de serviço, incluindo as tarefas descritas neste artigo. Consulte Migrating Citrix Virtual Apps and Desktops to Citrix Cloud Learning Path.

Solucionar problemas de configuração automatizada e informações adicionais
January 23, 2026
Contribuição de: 
C
January 23, 2026
Contribuição de: 
C

Neste artigo

Feedback do site | Your privacy choices footer linkSuas escolhas de privacidade | Privacidade e termos legais | Preferências de cookies | Configurações de consentimento | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.