Sobre a ferramenta Migrador de atividades

Finalidade do migrador de atividades

O Activity Migrator é 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 plataforma UiPath, habilitando o acesso às funcionalidades e recursos mais recentes:

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

Cenários de migração compatíveis

Migração da estrutura do projeto

A migração de um projeto Windows - Legado para a compatibilidade com o Windows é altamente recomendada 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 a uma melhor integração com o .NET Core e as 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 Automação de interface gráfica

Muitas funcionalidades novas de Automação de Interface Gráfica, como Destino Unificado e Healing Agent, são compatíveis apenas com a estrutura de Automação de Interface Gráfica moderna. Portanto, a migração das atividades de Automação de Interface Gráfica clássica para a experiência moderna é necessária.

Migração de atividades do Outlook obsoleta

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

Activity Migrator vs. o conversor Studio Windows - Legacy

Use o conversor Studio Windows - Legacy quando:

• Você só precisa converter projetos do Windows - Legado para Windows um por um.
• Nenhuma migração de atividade é necessária.

Use o Activity Migrator quando:

• Você deseja converter vários projetos Windows - Legado para Windows (conversão em massa é suportada).
• É necessária a migração das atividades UIAutomation ou Mail .
• Qualquer combinação dos cenários acima se aplica.

Onde obter o Migrator de atividades

Siga as etapas abaixo 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 onde o Studio não estiver instalado, instale o .NET Desktop Runtime 8.0.
• Abra os projetos migrados utilizando as versões do Studio 2024.10 ou superiores.

Como usar o Activity Migrator

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.

Comandos disponíveis:

Command	Description
version	Exibe informações da versão.
analyze	Analisar um projeto para migração sem fazer alterações.
upgrade	Migrar um projeto ou partes dele.
bulk	Analisar ou migrar todos os projetos em uma pasta.

Analisar um projeto

Esta opção simula a migração e gera um relatório sem realizar 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 para analisar ou atualizar. 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, uma nova pasta com o sufixo _Upgraded é criada.
-v, --verbose	Habilite o log detalhado.
-f, --output-format	Formato de saída: console (padrão) ou sarif.
-e, --extension-directory	Diretório para pesquisar extensões. Somente 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, falha ao compilar ou falha ao executar outras migrações necessárias.
--orchestrator-url	A URL completa do Orchestrator, incluindo o nome da organização (por exemplo, https://cloud.uipath.com/myorg). Se não for especificado, a conexão do Studio será usada. 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 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 biblioteca do Orchestrator. Crie um token de acesso pessoal e adicione o escopo de acesso à API do Orchestrator OR.Execution.Read. Consulte Tokens de acesso pessoal. Alternativamente, configure um ID de aplicativo e segredo usando --orchestrator-application-id e --orchestrator-application-secret.
--orchestrator-application-id	ID do aplicativo OAuth para autenticação do Orchestrator (alternativa para PAT). Use com --orchestrator-application-secret. Consulte Gerenciamento de aplicativos externos do OAuth.
--orchestrator-application-secret	Segredo do aplicativo OAuth para autenticação do Orchestrator (alternativa para PAT). Use com --orchestrator-application-id. Consulte Gerenciamento de aplicativos externos do OAuth.
--enabled-extensions	Lista separada por vírgulas de extensões a serem habilitadas. 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 separada por vírgulas de extensões a desabilitar. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilitar todas as extensões. Esta opção é mutuamente exclusiva com --enabled-extensions e --disabled-extensions.
--uia-package-version	A versão do pacote de atividades de Automação de interface gráfica a ser usada para migração. O padrão é 25.10.21 , se não for especificado. A versão de destino deve ser superior à padrão. Se não, o padrão é usado.
--uia-fix-selector-strategy	Quando definido como true, corrige a ambiguidade da enumeração SelectorStrategy em expressões pré-existentes após a migração. Aplica-se à UIAutomation versão 25.10.29 ou superior. Padrão: false. A ambiguidade resulta da enumeração SelectorStrategy existente nos namespaces UiPath.Core e UiPath.UIAutomationNext.Enums . Usar o nome totalmente qualificado resolve esse problema.
--mail-o365-package-version	A versão do pacote de atividades Microsoft Office 365 a ser usada para migração. O padrão é a versão 3.6.10. A versão de destino deve ser superior à padrão. Se não, o padrão é usado.
--config	Especifica o caminho para um arquivo JSON de configuração personalizada. 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 realiza 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)	O 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, uma nova pasta com o sufixo _Upgraded é criada.
-v, --verbose	Habilite o log detalhado.
-f, --output-format	Formato de saída: console (padrão) ou sarif.
-e, --extension-directory	Diretório para pesquisar extensões. Somente 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, falha ao compilar ou falha ao executar outras migrações necessárias.
--orchestrator-url	A URL completa do Orchestrator, incluindo o nome da organização. Se não for especificado, a conexão do Studio será usada. Quando especificado, as credenciais são necessárias.
--orchestrator-tenant	O nome do tenant do Orchestrator. O padrão é DefaultTenant , se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para a autenticação do Orchestrator. Requer o escopo OR.Execution.Read .
--orchestrator-application-id	ID do aplicativo OAuth para autenticação do Orchestrator (alternativa para PAT).
--orchestrator-application-secret	Segredo do aplicativo OAuth (alternativa ao PAT).
--enabled-extensions	Lista separada por vírgulas de extensões a serem habilitadas. Extensões disponíveis: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista separada por vírgulas de extensões a desabilitar. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilitar todas as extensões. mutuamente exclusivo com --enabled-extensions e --disabled-extensions.
--uia-package-version	Versão do pacote UiPath.UIAutomation.Activities de destino. O padrão é 25.10.21.
--uia-fix-selector-strategy	Quando definido como true, corrige a ambiguidade da enumeração SelectorStrategy em expressões pré-existentes após a migração. Aplica-se à UIAutomation versão 25.10.29 ou superior. Padrão: false. A ambiguidade resulta da enumeração SelectorStrategy existente nos namespaces UiPath.Core e UiPath.UIAutomationNext.Enums . Usar o nome totalmente qualificado resolve esse problema.
--mail-o365-package-version	A versão do pacote de atividades Microsoft Office 365 a ser usada para migração. O padrão é a versão 3.6.10. A versão de destino deve ser superior à padrão. Se não, o padrão é usado.
--config	Especifica o caminho para um arquivo JSON de configuração personalizada. 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

Esta 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 é executada em todas as subpastas que contêm um arquivo project.json .
-c, --command (obrigatório)	Comando a executar: analyze ou upgrade.
-v, --verbose	Habilite o log detalhado.
-o, --output-path	Caminho raiz de saída para projetos atualizados. Esta pasta será criada se não existir. Uma nova pasta com o sufixo _Upgraded é criada para o projeto atualizado.
--orchestrator-url	A URL completa do Orchestrator, incluindo o nome da organização.
--orchestrator-tenant	O nome do tenant do Orchestrator. O padrão é DefaultTenant , se não for especificado.
--orchestrator-pat	Token de acesso pessoal (PAT) para a autenticação do Orchestrator. Requer o escopo OR.Execution.Read .
--orchestrator-application-id	ID do aplicativo OAuth para autenticação do Orchestrator (alternativa para PAT).
--orchestrator-application-secret	Segredo do aplicativo OAuth (alternativa ao PAT).
--enabled-extensions	Lista separada por vírgulas de extensões a serem habilitadas. Extensões disponíveis: UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemplo: --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Lista separada por vírgulas de extensões a desabilitar. As extensões disponíveis são preenchidas dinamicamente com base em extensões descobertas.
--disable-all-extensions	Desabilitar todas as extensões. mutuamente exclusivo 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 Automação de Interface Gráfica 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:
  • Opções curtas (por exemplo, -p value) devem usar um espaço para separar a opção de seu valor.
  • Opções longas (por exemplo, --project-path=value) normalmente usam o sinal de igual para vincular explicitamente o valor ao sinalizador específico. Na maioria dos casos, 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 só é compatível com a sintaxe de sinais de igual (por exemplo, --config=value).
• A saída padrão do comando upgrade é um relatório do SARI armazenado no projeto original em uma pasta .upgrade . O projeto migrado é salvo 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 o migrador 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:

• No momento, 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 for definida como true, a opção desabilita a verificação Save as type para tipos não compatíveis. A atividade pode ser migrada assim, independentemente do 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.

Obtendo o ConnectionId do Orchestrator

A partir de março de 2026, as conexões foram movidas do Integration Service para o Orchestrator. Você pode recuperar o ConnectionId diretamente do 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. Abrir a conexão: clique na conexão para ver 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}

Como configurar IDs de conexão para atividades de produtividade

A propriedade ConnectionId não é preenchida automaticamente durante a migração. Você deve defini-lo manualmente por fluxo de trabalho/atividade usando um arquivo de configuração. O arquivo de configuração pode ser passado para o Activity Migrator usando o argumento de linha de comando --config <config> .

O exemplo a seguir atribui diferentes IDs de conexão a atividades específicas de Produtividade (Microsoft Office 365, GSuite), usando um fallback de 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 de Automação de Interface Gráfica pós-migração

A maioria das atividades de Automação de Interface Gráfica moderna requer um escopo de aplicativo ( atividade Use Application/Browser ). Durante a migração, dois tipos de escopos são criados:

Escopos criados naturalmente

Esses escopos são gerados automaticamente ao migrar atividades com escopo clássico, como Open Browser e Attach Browser. 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

Esses escopos são gerados 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, preservando a ordem de atividade original.

Limitações

Atividades do UIAutomation

• A versão mínima de destino compatível de UiPath.UIAutomation.Activities é 25.10.21.
• Algumas propriedades de atividade têm limitações de migração. Consulte as listas de atividades compatíveis:
  • Atividades compatíveis com a Automação de Interface Gráfica
  • Atividades de Automação de interface gráfica não compatíveis
• Os fluxos de trabalho migrados usando atividades de Automação de Interface Gráfica moderna podem ser executados mais lentamente do que os fluxos de trabalho originais usando atividades de Automação de Interface Gráfica clássica.

Atividades de produtividade

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

Limitações da ferramenta

• Por padrão, a ferramenta Activity Migrator usa feeds NuGet configurados em NuGet.config: Oficial, Local e Marketplace. Para incluir feeds de biblioteca 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.
• 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 de Tipo não encontrado em arquivos .xaml após a migração.

Regra do Analisador de Fluxo de Trabalho do Studio

• A regra do Analisador de Fluxo de Trabalho ST-AMG-001 está disponível a partir do Studio 2025.10.8 LTS e Studio 2026.0.189 STS.

Melhores práticas de migração

Antes de migrar

1. Faça o backup dos seus projetos: sempre crie um backup completo antes de executar qualquer comando de migração.
2. Atualizar o Studio e os pacotes de atividades: use a versão mais recente do UiPath Studio e certifique-se de que as versões dos pacotes de destino atendam aos requisitos mínimos (UiPath.UIAutomation.Activities >= 25.10.21 e UiPath.MicrosoftOffice365.Activities >= 3.6.10).
3. Analisar antes de atualizar: execute o comando analyze primeiro. Use UiPath.Upgrade.exe analyze -p -v para gerar um relatório do SARIF e identificar problemas potenciais 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 biblioteca: só então migre os projetos que as consomem.

Durante a migração

5. Começar 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. Usar a migração em massa para vários projetos: depois de validado, execute UiPath.Upgrade.exe bulk -p -v. Certifique-se de que a estrutura da pasta 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 passe-o com --config:

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

Após migrar

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

Desempenho e manutenção

12. Otimizar os seletores do UI Automation: após a migração, revise os seletores quanto à precisão e estabilidade.
13. Monitorar o tempo de execução: as atividades modernas podem ser executadas mais lentamente inicialmente. Otimize quando necessário.
14. Documente suas alterações: mantenha um registro dos projetos migrados, versões de destino e configurações aplicadas para fins de auditoria e reversão.