À propos de l’outil Migrateur d’activités

Objectif du migrateur d’activités

Le migrateur d’activités est un outil essentiel d’interface de ligne de commande (CLI) pour les organisations qui transfèrent les projets d’automatisation existants vers la plate-forme moderne UiPath, permettant ainsi d’accéder aux dernières fonctionnalités et capacités :

• Automatisez le processus de migration en simplifiant et en optimisant le transfert de la configuration et des dépendances du processus.
• Réduisez les efforts manuels et les erreurs en garantissant la cohérence et la précision pendant la migration, au lieu de transférer manuellement les dépendances et les activités.

Scénarios de migration pris en charge

Migration d'infrastructures de projet

La migration d’un projet Windows – Legacy vers la compatibilité Windows est fortement recommandée pour plusieurs raisons stratégiques, techniques et liées à l’assistance :

1. Performances améliorées : les projets Windows s’exécutent plus rapidement et plus efficacement grâce à une meilleure intégration avec .NET Core et les API Windows modernes.
2. Meilleure compatibilité avec les bibliothèques externes : les projets Windows prennent en charge les nouvelles versions des bibliothèques et des dépendances, ce qui facilite l'intégration aux systèmes externes.

Accès aux capacités UI Automation modernes

De nombreuses nouvelles fonctionnalités d'UI Automation, telles que Unified Target et Healing Agent, ne sont compatibles qu'avec l'infrastructure UI Automation moderne. Par conséquent, la migration des activités UI Automation classiques vers l'expérience moderne est nécessaire.

Migration des activités Outlook obsolètes

Microsoft met fin à Outlook classique et encourage l’adoption de Microsoft 365. Par conséquent, le migrateur d’activités prend en charge la transition des dépendances d’automatisation de UiPath.Mail.Activities (qui reposent sur l’API Outlook classique) à UiPath.MicrosoftOffice365.Activities en fonction de UiPath Integration Service.

Migrateur d’activité vs. le convertisseur Studio Windows - Legacy

Utilisez le convertisseur Studio Windows - Legacy lorsque :

• Il vous suffit de convertir les projets Windows - Héritage vers Windows un par un.
• Aucune migration d’activité n’est requise.

Utilisez le migreur d'activité lorsque :

• Vous souhaitez convertir plusieurs projets hérités depuis Windows en projets Windows (convertissement en bloc pris en charge).
• La migration des activités UI Automation ou E-mail est nécessaire.
• Toute combinaison des scénarios ci-dessus s'applique.

Où obtenir le migrateur d’activité

Suivez les étapes ci-dessous pour télécharger l’outil :

1. Accédez à UiPath Automation Cloud.
2. Sélectionnez le bouton Aide dans le coin supérieur droit.
3. Sous Ressources, sélectionnez Téléchargements.
4. Dans la liste Téléchargement de fonctionnalités , sélectionnez Outil de migration d’activité.
5. Sélectionnez le lien de téléchargement.

Après avoir téléchargé le fichier .zip assurez-vous de l'installer dans le dossier <tool-install-dir> .

Prérequis

• Si l'outil est utilisé sur une machine où Studio n'est pas installé, installez .NET Desktop Runtime 8.0.
• Ouvrez les projets migrés avec les versions de Studio 2024.10 ou ultérieures.

Comment utiliser le migreur d'activité

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

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

Options globales:

Option	Description
-?, -h, --help	Affiche l'aide et les informations d’utilisation.

Commandes disponibles:

Commande	Description
version	Afficher les informations de version.
analyze	Analysez un projet pour la migration sans apporter de modifications.
upgrade	Migrez un projet ou des parties de celui-ci.
bulk	Analysez ou migrez tous les projets dans un dossier.

Analyser un projet

Cette option simule la migration et génère un rapport sans effectuer la migration réelle ou modifier le projet.

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

Utilisation: UiPath.Upgrade.exe analyze [options]

Option	Description
-?, -h, --help	Affiche l'aide et les informations d’utilisation.
-p, --project-path (requis)	Chemin d'accès au projet à analyser ou à mettre à niveau. Le dossier fourni en tant que <project-path> doit contenir le fichier project.json du projet.
-o, --output-path	Chemin de sortie du projet mis à niveau (facultatif). Si ce champ n’est pas spécifié, un nouveau dossier avec le suffixe _Upgraded sera créé.
-v, --verbose	Activer la journalisation détaillée.
-f, --output-format	Format de sortie : console (par défaut) ou sarif.
-e, --extension-directory	Répertoire de recherche des extensions. Pour un usage avancé uniquement.
--ignore-missing-dependencies	Ignorer les dépendances manquantes lors de la mise à niveau. Les dépendances manquantes s’affichent sous forme d’avertissements. Les workflows affectés peuvent signaler des types manquants, échouer à compiler ou ne pas effectuer d'autres migrations nécessaires.
--orchestrator-url	L’URL complète d’Orchestrator, y compris le nom de l’organisation (par exemple, https://cloud.uipath.com/myorg). Si elle n'est pas spécifiée, la connexion de Studio est utilisée. Lorsque cela est spécifié, vous devez également fournir des informations d'identification via le jeton d'accès personnel (PAT) à l'aide de --orchestrator-pat ou un ID d'application externe et une clé secrète à l'aide de --orchestrator-application-id et --orchestrator-application-secret.
--orchestrator-tenant	Nom du locataire Orchestrator. La valeur par défaut est DefaultTenant si ce champ n’est pas spécifié.
--orchestrator-pat	Jeton d'accès personnel (PAT) pour l'authentification Orchestrator, utilisé pour accéder aux flux de la bibliothèque Orchestrator. Créez un jeton d'accès personnel et ajoutez l'étendue d'accès à l'API Orchestrator OR.Execution.Read. Reportez-vous à Jetons d’accès personnels. Vous pouvez également configurer un ID d’application et une clé secrète à l’aide --orchestrator-application-id et --orchestrator-application-secret.
--orchestrator-application-id	ID d’application OAuth pour l’authentification Orchestrator (alternative à PAT). À utiliser avec --orchestrator-application-secret. Reportez-vous à Gestion des applications externes OAuth.
--orchestrator-application-secret	Clé secrète d'application OAuth pour l'authentification Orchestrator. À utiliser avec --orchestrator-application-id. Reportez-vous à Gestion des applications externes OAuth.
--enabled-extensions	Liste d’extensions à activer, séparées par des virgules. Par défaut, toutes les extensions sont activées. Extensions disponibles : UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemple : --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Liste d'extensions à désactiver, séparées par des virgules. Les extensions disponibles sont renseignées dynamiquement en fonction des extensions découvertes.
--disable-all-extensions	Désactiver toutes les extensions. Cette option s'exclut mutuellement avec --enabled-extensions et --disabled-extensions.
--uia-package-version	La version du package d'activités UIAutomation à utiliser pour la migration. La valeur par défaut est 25.10.21 si ce champ n’est pas spécifié. La version cible doit être supérieure à la version par défaut. Sinon, la valeur par défaut est utilisée.
--uia-fix-selector-strategy	Lorsqu'il est défini sur true, corrige l'ambiguïté d'énumération SelectorStrategy dans les expressions préexistantes après la migration. S’applique à UIAutomation version 25.10.29 ou versions ultérieures. Par défaut : false. L'ambiguïté résulte de l'énumération SelectorStrategy existante dans les espaces de noms UiPath.Core et UiPath.UIAutomationNext.Enums . L’utilisation du nom complet résoudra ce problème.
--mail-o365-package-version	La version du package d'activités Microsoft Office 365 à utiliser pour la migration. La valeur par défaut est la version 3.6.10. La version cible doit être supérieure à la version par défaut. Sinon, la valeur par défaut est utilisée.
--config	Spécifie le chemin d'accès à un fichier JSON de configuration personnalisé. La configuration peut être utilisée pour modifier le comportement par défaut de certaines activités ou attribuer des valeurs constantes aux propriétés qui nécessitent une intervention de l'utilisateur pendant la migration. Reportez-vous au Fichier de configuration.

Migrer un projet

Cette option effectue la migration réelle d'un projet ou de certaines parties de celui-ci.

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

Utilisation: UiPath.Upgrade.exe upgrade [options]

Option	Description
-?, -h, --help	Affiche l'aide et les informations d’utilisation.
-p, --project-path (requis)	Chemin d'accès au dossier contenant le fichier project.json du projet.
-o, --output-path	Chemin de sortie du projet mis à niveau (facultatif). Si ce champ n’est pas spécifié, un nouveau dossier avec le suffixe _Upgraded sera créé.
-v, --verbose	Activer la journalisation détaillée.
-f, --output-format	Format de sortie : console (par défaut) ou sarif.
-e, --extension-directory	Répertoire de recherche des extensions. Pour un usage avancé uniquement.
--ignore-missing-dependencies	Ignorer les dépendances manquantes lors de la mise à niveau. Les dépendances manquantes s’affichent sous forme d’avertissements. Les workflows affectés peuvent signaler des types manquants, échouer à compiler ou ne pas effectuer d'autres migrations nécessaires.
--orchestrator-url	Il s’agit de l’URL complète d’Orchestrator, y compris le nom de l’organisation. Si elle n'est pas spécifiée, la connexion de Studio est utilisée. Lorsqu'il est spécifié, les informations d'identification sont requises.
--orchestrator-tenant	Nom du locataire Orchestrator. La valeur par défaut est DefaultTenant si ce champ n’est pas spécifié.
--orchestrator-pat	Jeton d'accès personnel (PAT) pour l'authentification Orchestrator. Nécessite l'étendue OR.Execution.Read .
--orchestrator-application-id	ID d’application OAuth pour l’authentification Orchestrator (alternative à PAT).
--orchestrator-application-secret	Clé secrète d’application OAuth (alternative au PAT).
--enabled-extensions	Liste d’extensions à activer, séparées par des virgules. Extensions disponibles : UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemple : --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Liste d'extensions à désactiver, séparées par des virgules. Les extensions disponibles sont renseignées dynamiquement en fonction des extensions découvertes.
--disable-all-extensions	Désactiver toutes les extensions. mutuellement exclusif avec --enabled-extensions et --disabled-extensions.
--uia-package-version	Version du package cible UiPath.UIAutomation.Activities . La valeur par défaut est 25.10.21.
--uia-fix-selector-strategy	Lorsqu'il est défini sur true, corrige l'ambiguïté d'énumération SelectorStrategy dans les expressions préexistantes après la migration. S’applique à UIAutomation version 25.10.29 ou versions ultérieures. Par défaut : false. L'ambiguïté résulte de l'énumération SelectorStrategy existante dans les espaces de noms UiPath.Core et UiPath.UIAutomationNext.Enums . L’utilisation du nom complet résoudra ce problème.
--mail-o365-package-version	La version du package d'activités Microsoft Office 365 à utiliser pour la migration. La valeur par défaut est la version 3.6.10. La version cible doit être supérieure à la version par défaut. Sinon, la valeur par défaut est utilisée.
--config	Spécifie le chemin d'accès à un fichier JSON de configuration personnalisé. La configuration peut être utilisée pour modifier le comportement par défaut de certaines activités ou attribuer des valeurs constantes aux propriétés qui nécessitent une intervention de l'utilisateur pendant la migration. Reportez-vous au Fichier de configuration.

Migration de référentiel en bloc

Cette option analyse ou migre tous les projets trouvés dans une hiérarchie de dossiers.

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

Utilisation: UiPath.Upgrade.exe bulk [options]

Option	Description
-?, -h, --help	Affiche l'aide et les informations d’utilisation.
-p, --path (requis)	Chemin d'accès au référentiel ou dossier. La migration est effectuée sur tous les sous-dossiers contenant un fichier project.json .
-c, --command (requis)	Commande à exécuter : analyze ou upgrade.
-v, --verbose	Activer la journalisation détaillée.
-o, --output-path	Chemin d’accès racine de sortie pour les projets mis à niveau. Ce dossier est créé s'il n'existe pas. Un nouveau dossier avec le suffixe _Upgraded est créé pour le projet mis à niveau.
--orchestrator-url	Il s’agit de l’URL complète d’Orchestrator, y compris le nom de l’organisation.
--orchestrator-tenant	Nom du locataire Orchestrator. La valeur par défaut est DefaultTenant si ce champ n’est pas spécifié.
--orchestrator-pat	Jeton d'accès personnel (PAT) pour l'authentification Orchestrator. Nécessite l'étendue OR.Execution.Read .
--orchestrator-application-id	ID d’application OAuth pour l’authentification Orchestrator (alternative à PAT).
--orchestrator-application-secret	Clé secrète d’application OAuth (alternative au PAT).
--enabled-extensions	Liste d’extensions à activer, séparées par des virgules. Extensions disponibles : UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemple : --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Liste d'extensions à désactiver, séparées par des virgules. Les extensions disponibles sont renseignées dynamiquement en fonction des extensions découvertes.
--disable-all-extensions	Désactiver toutes les extensions. mutuellement exclusif avec --enabled-extensions et --disabled-extensions.

Exemples

Analyser un projet unique avec une sortie détaillée :

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

Migrez un projet et spécifiez une version de package cible UI Automation :

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

Migrez un projet à l’aide d’une configuration de connexion personnalisée :

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

Exécutez une analyse groupée sur un dossier :

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

Remarque :

• Les options de ligne de commande utilisent les conventions suivantes :
  • Les options courtes (par exemple, -p value) doivent utiliser un espace pour séparer l'option de sa valeur.
  • Les options longues (par exemple, --project-path=value) utilisent généralement le signe égal pour lier explicitement la valeur à l'indicateur spécifique. Dans la plupart des cas, les options longues peuvent également être spécifiées en utilisant un espace (par exemple, --project-path value). L'option --config est une exception et ne prend en charge que la syntaxe du signe égal (par exemple, --config=value).
• La sortie par défaut de la commande upgrade est un rapport .upgrade Le projet migré est enregistré dans le chemin de sortie.

Fichier de configuration

Utilisez un fichier de configuration pour définir des valeurs constantes pour les propriétés d'activité qui nécessitent une saisie manuelle lors de la migration, ou pour remplacer le comportement de migration par défaut.

Transmettez le chemin du fichier au migrateur à l'aide de l'option --config avec l'opérateur d'affectation =, comme dans cet exemple : --config=C:\to-migrate\connection.json.

Le fichier de configuration doit suivre ce format :

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

Remarque :

• Actuellement, le seul {property-name} qui peut être attribué est Connection Id.
• {reserved-configuration-key} représente des changements de comportement spécifiques à une activité :
  • SaveOutlookMailMessage_IgnoreSaveAsType: si le paramètre est défini sur true, l’option désactivera la vérification Save as type des types non pris en charge. L'activité peut ainsi être migrée indépendamment de Save as type option.
• * fait office de caractère générique et fait correspondre n'importe quelle valeur dans {path-to-workflow} et {activity-display-name}.
• Lorsque plusieurs entrées correspondent au même workflow et à la même activité, seule la dernière correspondance est appliquée.

Obtenir l'ID de connexion à partir d'Orchestrator

Depuis mars 2026, les connexions sont transférées d'Integration Service vers Orchestrator. Vous pouvez récupérer le ConnectionId directement à partir de l'URL de connexion dans Orchestrator :

1. Accéder à votre connexion dans Orchestrator : accédez au dossier Orchestrator où se trouve votre connexion Microsoft Outlook 365.
2. Ouvrir la connexion : cliquez sur la connexion pour afficher ses détails.
3. Vérifiez l'URL : ConnectionId est visible dans l'URL du navigateur au format suivant : https://cloud.uipath.com/{OrganizationName}/{TenantName}/orchestrator_/connections/{ConnectionId}/edit/tid={TId}

Définition des ID de connexion pour les activités de productivité

La propriété ConnectionId n’est pas renseignée automatiquement lors de la migration. Vous devez le définir manuellement par workflow/activité à l'aide d'un fichier de configuration. Le fichier de configuration peut être transmis au migrateur d’activité à l’aide de l’argument de ligne de commande --config <config> .

L'exemple suivant attribue différents ID de connexion à des activités de productivité spécifiques (Microsoft Office 365, GSuite), à l'aide d'un caractère générique de secours :

{
    "* > *": {
        "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"
    }
}

Dans cet exemple :

• * > * correspond à toutes les activités et sert de solution de secours lorsqu’il n’y a pas d’entrées correspondantes ci-dessous.
• *\\Projects\\MailMigration\\Main.xaml > Get * correspond à toute activité dont le nom complet commence par Get dans Main.xaml.
• *\\Projects\\MailMigration\\* > Send Mail correspond à l'activité Send Mail sur tous les workflows du dossier MailMigration .

Comportement de l’étendue de l’application UI Automation après la migration

La plupart des activités UI Automation modernes nécessitent une étendue d'application . Lors de la migration, deux types d'étendues sont créés :

Étendues créées de façon organisationnelle

Ces étendues sont générées automatiquement lors de la migration d’activités classiques telles que Ouvrir le navigateur et Joindre le navigateur. Ces étendues ne sont pas optimisées pour éviter de modifier l’intention et le flux d’origine du workflow migré.

Étendues générées de manière synthétique

Ces étendues sont générées pour garantir que le workflow se compile et s'exécute correctement après la migration. Lorsque deux étendues consécutives ont des propriétés identiques (par exemple, le même sélecteur ou moteur OCR), elles sont fusionnées en une seule étendue tout en préservant l’ordre d’activité d’origine.

Limitations

Activités UIAutomation

• La version cible minimale prise en charge de UiPath.UIAutomation.Activities est 25.10.21.
• Certaines propriétés d'activité présentent des limitations de migration. Consultez les listes d'activités prises en charge :
  • Activités prises en charge par UI Automation
  • Activités UI Automation non prises en charge
• Les workflows migrés utilisant les activités UI Automation modernes peuvent s’exécuter plus lentement que les workflows d’origine utilisant les activités UI Automation classiques.

Activités de productivité

• La version cible minimale prise en charge de UiPath.MicrosoftOffice365.Activities est 3.6.10.
• Consultez les listes d'activités prises en charge :
  • Activités de messagerie prises en charge
  • Activités de messagerie non prises en charge

Limitations des outils

• Par défaut, l'outil Activity Migrator utilise les flux NuGet configurés dans NuGet.config: Officiel, Local et Marketplace. Pour inclure les flux de bibliothèque Orchestrator, utilisez les options des commandes analyze, upgrade et bulk : --orchestrator-url, --orchestrator-tenant, --orchestrator-pat, --orchestrator-application-id et --orchestrator-application-secret.
• Les activités qui utilisent des types ou des assemblies générés dynamiquement (par exemple, certaines activités Excel peuvent avoir des noms de colonnes en tant que propriétés dans un type généré dynamiquement) peuvent provoquer une erreur Type introuvable dans les fichiers .xaml après la migration.

Règle de l’analyseur de workflow Studio

• La règle de l’analyseur de workflow ST-AMG-001 est disponible à partir de Studio 2025.10.8 LTS et Studio 2026.0.189 STS.

Meilleures pratiques de migration

Avant la migration

1. Sauvegardez vos projets: créez toujours une sauvegarde complète avant d’exécuter des commandes de migration.
2. Mettre à jour Studio et les packages d'activités: utilisez la dernière version d' UiPath Studio et assurez-vous que les versions du package cible répondent aux exigences minimales (UiPath.UIAutomation.Activities >= 25.10.21 et UiPath.MicrosoftOffice365.Activities >= 3.6.10).
3. Analyser avant la mise à niveau: exécutez d’abord la commande analyze . Utilisez UiPath.Upgrade.exe analyze -p -v pour générer un rapport SARIF et identifier les problèmes potentiels sans modifier le projet.
4. Vérifiez les dépendances et les flux NuGet: confirmez que les flux Officiel, Local et Marketplace sont correctement configurés dans NuGet.config.
5. Migrez d'abord les bibliothèques lorsqu'un projet dépend de projets de bibliothèque: migrez ensuite uniquement les projets qui les utilisent.

Pendant la migration

5. Commencer par un seul projet: testez la migration sur un projet à l'aide de UiPath.Upgrade.exe upgrade -p -v avant d'exécuter une opération groupée.
6. Utiliser la migration en bloc pour plusieurs projets: Une fois validé, exécutez UiPath.Upgrade.exe bulk -p -v. Assurez-vous que la structure des dossiers est claire et cohérente.
7. Fournissez un fichier de configuration pour les ID de connexion: Pour les activités Microsoft 365 ou GSuite, créez un fichier de configuration avec les valeurs ConnectionId requises et transmettez-le avec --config:

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

Après la migration

8. Examiner le rapport SARIF: vérifiez le dossier .upgrade dans le répertoire du projet et résolvez les problèmes signalés.
9. Ouvrez le projet migré dans Studio et exécutez Analyser le projet: examinez les résultats de la règle de l'analyseur de workflow ST-AMG-001 LTS / Studio 2026.0.189 STS ou versions ultérieures) pour identifier les activités qui nécessitent des actions post-migration.
10. Valider les étendues d'application: confirmez que les étendues fusionnées se comportent comme prévu. Testez les workflows avec les activités Use Application/Browser.
11. Exécuter les tests de bout en bout: exécutez les workflows migrés dans un environnement contrôlé avant de les déployer en production.

Performances et maintenance

12. Optimiser les sélecteurs UI Automation: après la migration, vérifiez la précision et la stabilité des sélecteurs.
13. Surveiller le temps d’exécution: les activités modernes peuvent initialement s’exécuter plus lent. Optimiser là où est nécessaire.
14. Documenter vos modifications: conservez un enregistrement des projets migrés, des versions cibles et des configurations appliquées à des fins d’audit et de restauration.