Sobre a ferramenta Migrador de atividades

Finalidade da ferramenta de migração de atividades

A ferramenta de migração de atividades é uma ferramenta de interface de linha de comando (CLI) essencial para organizações que fazem a transição de projetos de automação legados para a moderna UiPath Platform, permitindo o acesso às funcionalidades e recursos mais recentes:

• Automatize o processo de migração ao simplificar e agilizar a transferência da configuração e das dependências do processo.
• Reduza o esforço manual e os erros garantindo a consistência e a precisão durante a migração, em vez de transferir dependências e atividades manualmente.

Cenários de migração compatíveis

Migração da estrutura do projeto

Recomendamos fortemente a migração de um projeto do Windows - Legacy para compatibilidade com o Windows por vários motivos estratégicos, técnicos e relacionados ao suporte:

1. Desempenho aprimorado: os projetos do Windows são executados de forma mais rápida e eficiente devido à melhor integração com o .NET Core e APIs modernas do Windows.
2. Melhor compatibilidade com bibliotecas externas: os projetos do Windows são compatíveis com versões mais recentes de bibliotecas e dependências, facilitando a integração com sistemas externos.

Acesso a recursos modernos de UI Automation

Muitos novos recursos de UI Automation, como Destino unificado e Healing Agent, são compatíveis apenas com o framework de UI Automation moderno.Portanto, você deve migrar das atividades clássicas de UI Automation para a experiência moderna.

Migração de atividades obsoletas do Outlook

A Microsoft está encerrando o Outlook clássico e incentivando a adoção do Microsoft 365.Como resultado, a ferramenta de migração de atividades é compatível com a transição de dependências de automação de UiPath.Mail.Activities (que dependem da API Classic Outlook) para UiPath.MicrosoftOffice365.Activities dependências baseadas no UiPath Integration Service.

Ferramenta de migração de atividades versus Studio Windows - Conversor legado

Use o conversor Studio Windows - Legacy quando:

• Você só precisar converter projetos do Windows - Legacy para Windows um por um.
• Não são necessárias migrações de atividades.

Use a ferramenta de migração de atividades quando:

• Você desejar converter vários projetos do Windows - Legacy para Windows (conversão em massa compatível).
• A migração das atividades de UI Automation ou de e-mail é necessária.
• Qualquer combinação dos cenários acima é aplicável.

Onde obter a ferramenta de migração de atividades

Siga as etapas a seguir para baixar a ferramenta:

1. Navegue até o UiPath Automation Cloud.
2. Selecione o botão Ajuda no canto superior direito.
3. Em Recursos, selecione Downloads.
4. Na lista Download de funcionalidades, selecione Ferramenta de migração de atividades.
5. Selecione o link de download.

Após baixar o arquivo .zip , certifique-se de instalá-lo na pasta <tool-install-dir>.

Requisitos

• Se a ferramenta for usada em uma máquina em que o Studio não está instalado, instale o .NET Desktop Runtime 8.0.
• Abrir projetos migrados com versões do Studio 2024.10 ou posteriores.

Como usar a ferramenta de migração de atividades

Comando: <tool-install-dir>\UiPath.Upgrade.exe

Uso: UiPath.Upgrade.exe [command] [options]

Opções globais

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.

Available commands

Command	Description
version	Mostrar informações da versão.
analyze	Analisar um projeto para migração sem fazer alterações.
upgrade	Migre um projeto ou partes dele.
bulk	Analise ou migre todos os projetos para uma pasta.

Analisar um projeto

Essa opção simula a migração e gera um relatório sem executar a migração real ou modificar o projeto.

Comando: <tool-install-dir>\UiPath.Upgrade.exe analyze

Uso: UiPath.Upgrade.exe analyze [options]

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.
-p, --project-path (obrigatório)	Caminho para o projeto a ser analisado ou atualizado. A pasta fornecida como <project-path> deve conter o arquivo project.json do projeto.
-o, --output-path	Caminho de saída para o projeto atualizado (opcional). Se não for especificado, o sistema cria uma nova pasta com o sufixo _Upgraded.
-v, --verbose	Habilitar o registro Verbose.
-f, --output-format	Formato de saída: console (padrão) ou sarif.
-e, --extension-directory	Diretório para pesquisar extensões. Apenas para uso avançado.
--ignore-missing-dependencies	Ignorar dependências ausentes durante a atualização. As dependências ausentes aparecem como avisos. Os fluxos de trabalho afetados podem relatar tipos ausentes, não compilar ou não executar outras migrações necessárias.
--orchestrator-url	A URL do Orchestrator completa, incluindo o nome da organização (por exemplo, https://cloud.uipath.com/myorg).Se não for especificada, usa-se a conexão do Studio. Quando especificado, você também deve fornecer credenciais por meio do Token de acesso pessoal (PAT) usando --orchestrator-pat ou ID do Aplicativo externo e segredo usando --orchestrator-application-id e --orchestrator-application-secret.
--orchestrator-tenant	O nome do tenant do Orchestrator. O valor padrão é DefaultTenant se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para autenticação do Orchestrator, usado para acessar feeds de bibliotecas do Orchestrator. Crie um Token de acesso pessoal e adicione escopo de acesso à API do Orchestrator OR.Execution.Read. Consulte Tokens de acesso pessoal. Ou configure uma ID do aplicativo e um segredo usando --orchestrator-application-id e --orchestrator-application-secret.
--orchestrator-application-id	ID do Aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT). Use com --orchestrator-application-secret. Consulte Gerenciamento de aplicativos OAuth externos.
--orchestrator-application-secret	Segredo do aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT). Use com --orchestrator-application-id. Consulte Gerenciamento de aplicativos OAuth externos.
--enabled-extensions	Lista de extensões para habilitar separada por vírgulas. Por padrão, todas as extensões estão habilitadas.Extensões disponíveis: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista de extensões a serem desabilitadas separada por vírgulas. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilite todas as extensões. Essa opção é mutuamente exclusiva com --enabled-extensions e --disabled-extensions.
--uia-package-version	A versão do pacote de atividades do UI Automation para usar na migração.O padrão é 25.10.21 se não especificado. A versão de destino deve ser superior ao padrão. Se não, o padrão é usado.
--uia-fix-selector-strategy	Quando definido como true, corrige a ambiguidade de enumeração SelectorStrategy em expressões pré-existentes após a migração. Aplica-se à versão 25.10.29 ou posterior do UIAutomation. Padrão: (false). A ambiguidade resulta da enumeração SelectorStrategy existente nos namespaces UiPath.Core e UiPath.UIAutomationNext.Enums. O uso do nome totalmente qualificado resolve esse problema.
--mail-o365-package-version	A versão do pacote de atividades do Microsoft Office 365 a ser usada na migração. O padrão é a versão 3.6.10. A versão de destino deve ser superior ao padrão. Se não, o padrão é usado.
--config	Especifica o caminho para um arquivo JSON de configuração personalizado. A configuração pode ser usada para modificar o comportamento padrão de certas atividades ou atribuir valores constantes a propriedades que exigem entrada do usuário durante a migração. Consulte Arquivo de configuração.

Migrar um projeto

Essa opção executa a migração real de um projeto ou de partes dele.

Comando: <tool-install-dir>\UiPath.Upgrade.exe upgrade

Uso: UiPath.Upgrade.exe upgrade [options]

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.
-p, --project-path (obrigatório)	Caminho para a pasta que contém o arquivo project.json do projeto.
-o, --output-path	Caminho de saída para o projeto atualizado (opcional). Se não for especificado, o sistema cria uma nova pasta com o sufixo _Upgraded.
-v, --verbose	Habilitar o registro Verbose.
-f, --output-format	Formato de saída: console (padrão) ou sarif.
-e, --extension-directory	Diretório para pesquisar extensões. Apenas para uso avançado.
--ignore-missing-dependencies	Ignorar dependências ausentes durante a atualização. As dependências ausentes aparecem como avisos. Os fluxos de trabalho afetados podem relatar tipos ausentes, não compilar ou não executar outras migrações necessárias.
--orchestrator-url	A URL completa do Orchestrator, incluindo o nome da organização. Se não for especificada, usa-se a conexão do Studio. Quando especificadas, as credenciais são necessárias.
--orchestrator-tenant	O nome do tenant do Orchestrator. O valor padrão é DefaultTenant se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para autenticação do Orchestrator. Requer o escopo OR.Execution.Read.
--orchestrator-application-id	ID do Aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT).
--orchestrator-application-secret	Segredo do aplicativo OAuth (alternativa ao PAT).
--enabled-extensions	Lista de extensões para habilitar separada por vírgulas. Extensões disponíveis: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista de extensões a serem desabilitadas separada por vírgulas. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilite todas as extensões. Mutuamente exclusivos com --enabled-extensions e --disabled-extensions.
--uia-package-version	Versão UiPath.UIAutomation.Activities do pacote de destino. O padrão é 25.10.21.
--uia-fix-selector-strategy	Quando definido como true, corrige a ambiguidade de enumeração SelectorStrategy em expressões pré-existentes após a migração. Aplica-se à versão 25.10.29 ou posterior do UIAutomation. Padrão: (false). A ambiguidade resulta da enumeração SelectorStrategy existente nos namespaces UiPath.Core e UiPath.UIAutomationNext.Enums. O uso do nome totalmente qualificado resolve esse problema.
--mail-o365-package-version	A versão do pacote de atividades do Microsoft Office 365 a ser usada na migração. O padrão é a versão 3.6.10. A versão de destino deve ser superior ao padrão. Se não, o padrão é usado.
--config	Especifica o caminho para um arquivo JSON de configuração personalizado. A configuração pode ser usada para modificar o comportamento padrão de certas atividades ou atribuir valores constantes a propriedades que exigem entrada do usuário durante a migração. Consulte Arquivo de configuração.

Migração de repositório em massa

Essa opção analisa ou migra todos os projetos encontrados em uma hierarquia de pastas.

Comando: <tool-install-dir>\UiPath.Upgrade.exe bulk

Uso: UiPath.Upgrade.exe bulk [options]

Opção	Description
-?, -h, --help	Mostrar informações de ajuda e uso.
-p, --path (obrigatório)	Caminho para o repositório ou pasta. A migração ocorre em todas as subpastas que contêm um arquivo project.json.
-c, --command (obrigatório)	Comando a executar: analyze ou upgrade.
-v, --verbose	Habilitar o registro Verbose.
-o, --output-path	Caminho raiz de saída para projetos atualizados. Essa pasta é criada se não existir.O sistema cria uma nova pasta com o sufixo _Upgraded para o projeto atualizado.
--orchestrator-url	A URL do Orchestrator completa, incluindo o nome da organização.
--orchestrator-tenant	O nome do tenant do Orchestrator. O valor padrão é DefaultTenant se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para autenticação do Orchestrator. Requer o escopo OR.Execution.Read.
--orchestrator-application-id	ID do Aplicativo OAuth para autenticação do Orchestrator (alternativa ao PAT).
--orchestrator-application-secret	Segredo do aplicativo OAuth (alternativa ao PAT).
--enabled-extensions	Lista de extensões para habilitar separada por vírgulas. Extensões disponíveis: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista de extensões a serem desabilitadas separada por vírgulas. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilite todas as extensões. Mutuamente exclusivos com --enabled-extensions e --disabled-extensions.

Exemplos

Analise um único projeto com saída detalhada:

UiPath.Upgrade.exe analyze -p C:\to-migrate\LegacyProcess -v

Migre um projeto e especifique uma versão do pacote de UI Automation de destino:

UiPath.Upgrade.exe upgrade -p C:\to-migrate\LegacyProcess -o C:\to-migrate\WindowsProcess --uia-package-version=25.10.27 -v

Migre um projeto usando uma configuração de conexão personalizada:

UiPath.Upgrade.exe upgrade --project-path=C:\to-migrate\LegacyProcess --config=C:\to-migrate\connection.json

Execute uma análise em massa em uma pasta:

UiPath.Upgrade.exe bulk -p C:\to-migrate -c analyze

Observação:

• As opções de linha de comando usam as seguintes convenções:
  • As opções curtas (por exemplo, -p value) devem usar um espaço para separar a opção de seu valor.
  • As opções longas (por exemplo, --project-path=value) normalmente usam o sinal de igual para vincular explicitamente o valor ao parâmetro específico.Na maioria dos casos, as opções longas também podem ser especificadas usando um espaço (por exemplo, --project-path value). A opção --config é uma exceção e é compatível apenas com a sintaxe de sinal de igual (por exemplo, --config=value).
• A saída padrão do comando upgrade é um relatório SARIF armazenado no projeto original em uma pasta .upgrade. O sistema salva o projeto migrado no caminho de saída.

Arquivo de configuração

Use um arquivo de configuração para definir valores constantes para propriedades de atividades que exigem entrada manual durante a migração ou para substituir o comportamento de migração padrão.

Passe o caminho do arquivo para a ferramenta de migração usando a opção --config com o operador de atribuição =, como neste exemplo: --config=C:\to-migrate\connection.json.

O arquivo de configuração deve seguir este formato:

{
  "{reserved-configuration-key}": "{value}",
  "...": "...",
  "{path-to-workflow} > {activity-display-name}": {
    "{property-name}": "{property-value}"
  }
}

Observação:

• Atualmente, o único {property-name} que pode ser atribuído é Connection Id.
• {reserved-configuration-key} representa alterações de comportamento específicas da atividade:
  • SaveOutlookMailMessage_IgnoreSaveAsType: se definida como true, a opção desabilita a verificação Save as type para tipos não compatíveis. Assim, a atividade pode ser migrada independentemente de Save as type option.
• * atua como um curinga e corresponde a qualquer valor em {path-to-workflow} e {activity-display-name}.
• Quando várias entradas correspondem ao mesmo fluxo de trabalho e atividade, apenas a última correspondência é aplicada.

Obtenção da ConnectionId do Orchestrator

A partir de março de 2026, as conexões mudaram do Integration Service para o Orchestrator. Você pode recuperar o ConnectionId diretamente da URL de conexão no Orchestrator:

1. Navegue até sua conexão no Orchestrator: acesse a pasta do Orchestrator onde sua conexão do Microsoft Outlook 365 está localizada.
2. Abra a conexão: clique na conexão para visualizar seus detalhes.
3. Verifique a URL: o ConnectionId está visível na URL do navegador com o seguinte formato: https://cloud.uipath.com/{OrganizationName}/{TenantName}/orchestrator_/connections/{ConnectionId}/edit/tid={TId}

Configuração de IDs de conexão para atividades de produtividade

O sistema não preenche a propriedade ConnectionId automaticamente durante a migração.Você deve defini-la manualmente por fluxo de trabalho/atividade usando um arquivo de configuração. O arquivo de configuração pode ser passado para a ferramenta de migração de atividades usando o argumento de linha de comando --config <config>.

O exemplo a seguir atribui diferentes IDs de conexão a atividades de produtividade específicas (Microsoft Office 365, GSuite), usando um fallback curinga:

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    },
    "*\\Projects\\MailMigration\\Main.xaml > Get *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000002"
    },
    "*\\Projects\\MailMigration\\* > Send Mail": {
        "ConnectionId": "00000000-0000-0000-0000-000000000003"
    }
}

Neste exemplo:

• * > * corresponde a todas as atividades e atua como um fallback quando não há entradas correspondentes abaixo.
• *\\Projects\\MailMigration\\Main.xaml > Get * corresponde a qualquer atividade cujo nome de exibição comece com Get em Main.xaml.
• *\\Projects\\MailMigration\\* > Send Mail corresponde à atividade Send Mail em todos os fluxos de trabalho na pasta MailMigration.

Comportamento do escopo do aplicativo UI Automation após migração

A maioria das atividades modernas de UI Automation requer um escopo de aplicativo (atividade Use Application/Browser).Durante a migração, dois tipos de escopos são criados:

Escopos criados organicamente

Esses escopos são gerados automaticamente ao migrar atividades com escopo clássicas, como Abrir navegador e Anexar navegador. Esses escopos não são otimizados para evitar alterar a intenção e o fluxo originais do fluxo de trabalho migrado.

Escopos gerados sinteticamente

Geramos esses escopos para garantir que o fluxo de trabalho seja compilado e executado corretamente após a migração. Quando dois escopos consecutivos têm propriedades idênticas (por exemplo, o mesmo seletor ou mecanismo de OCR), eles são mesclados em um único escopo enquanto preservam a ordem original da atividade.

Limitações

Atividades do UIAutomation

• A versão de destino mínima compatível de UiPath.UIAutomation.Activities é 25.10.21.
• Algumas propriedades de atividades têm limitações de migração. Veja as listas de atividades compatíveis:
  • Atividades do UI Automation compatíveis
  • Atividades do UI Automation não compatíveis
• Os fluxos de trabalho migrados que usam atividades modernas de UI Automation podem ser executados mais lentamente do que os fluxos de trabalho originais que usam atividades clássicas de UI Automation.

Atividades de produtividade

• A versão de destino mínima compatível de UiPath.MicrosoftOffice365.Activities é 3.6.10.
• Veja as listas de atividades compatíveis:
  • Atividades de email compatíveis
  • Atividades de email não compatíveis

Limitações da ferramenta

• Por padrão, a ferramenta de migração de atividades usa feeds NuGet configurados em NuGet.config: Official, Local e Marketplace. Para incluir feeds de bibliotecas do Orchestrator, use as opções para os comandos analyze, upgrade e bulk: --orchestrator-url, --orchestrator-tenant, --orchestrator-pat, --orchestrator-application-id e --orchestrator-application-secret.
• As atividades que usam tipos ou assemblies gerados dinamicamente (por exemplo, algumas atividades do Excel podem ter nomes de colunas como propriedades em um tipo gerado dinamicamente) podem causar um erro Type not found em arquivos .xaml após a migração.

Regra do Analisador de Fluxo de Trabalho do Studio

• A regra Analisador de fluxo de trabalho ST-AMG-001 está disponível a partir do Studio 2025.10.8Suporte em Longo Prazo e Studio 2026.0.189 STS.

Melhores práticas de migração

Antes da migração

1. Faça backup de seus projetos: sempre crie um backup completo antes de executar quaisquer comandos de migração.
2. Atualize os pacotes do Studio e de atividades: use a versão mais recente do UiPath Studio e certifique-se de que as versões de pacotes de destino atendam aos requisitos mínimos (UiPath.UIAutomation.Activities >= 25.10.21 e UiPath.MicrosoftOffice365.Activities >= 3.6.10).
3. Analise antes de atualizar: execute primeiro o comando analyze. Use UiPath.Upgrade.exe analyze -p -v para gerar um relatório SARIF e identificar possíveis problemas sem modificar o projeto.
4. Verificar dependências e feeds do NuGet: confirme se os feeds Oficial, Local e Marketplace estão configurados corretamente em NuGet.config.
5. Migre as bibliotecas primeiro quando um projeto depende de projetos de bibliotecas: somente depois migre os projetos que as consomem.

Durante a migração

5. Comece com um único projeto: teste a migração em um projeto usando UiPath.Upgrade.exe upgrade -p -v antes de executar uma operação em massa.
6. Use a migração em massa para vários projetos: uma vez validado, execute UiPath.Upgrade.exe bulk -p -v. Certifique-se de que a estrutura das pastas esteja limpa e consistente.
7. Forneça um arquivo de configuração para IDs de conexão: para atividades do Microsoft 365 ou do GSuite, crie um arquivo de configuração com os valores ConnectionId necessários e o transmita a --config:

{
    "* > *": {
        "ConnectionId": "00000000-0000-0000-0000-000000000001"
    }
}

Após a migração

8. Revise o relatório do SARIF: verifique a pasta .upgrade no diretório do projeto e resolva quaisquer problemas sinalizados.
9. Abra o projeto migrado no Studio e execute Analisar Projeto: revise os resultados da regra ST-AMG-001 do Analisador de Fluxo de Trabalho (disponível no Studio 2025.10.8 Suporte em Longo Prazo/ Studio 2026.0.189 STS ou superior) para identificar atividades que exigem ações pós-migração.
10. Validar escopos de aplicativo: confirme que os escopos mesclados comportam-se conforme o esperado. Teste fluxos de trabalho com atividades Use Application/Browser.
11. Executar testes de ponta a ponta: execute fluxos de trabalho migrados em um ambiente controlado antes de implantar na produção.

Desempenho e manutenção

12. Otimizar seletores de UI Automation: após a migração, revise os seletores para obter precisão e estabilidade.
13. Monitorar período de execução: as atividades modernas podem ser executadas mais lentamente no início. Otimize onde necessário.
14. Documentar suas alterações: mantenha um registro de projetos migrados, versões de destino e configurações aplicadas para fins de auditoria e reversão.