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

But du Migrateur d'activités

Migrateur d'activités est un outil d'interface de ligne de commande (CLI) essentiel pour les organisations faisant la transition de projets d'automatisation hérités vers la UiPath Platform moderne, permettant l'accès aux dernières fonctionnalités et capacités :

• Automatisez le processus de migration en simplifiant et en rationalisant le transfert de la configuration et des dépendances du processus.
• Réduisez l'effort manuel 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 de l'infrastructure du projet

La migration d'un projet Windows - Héritage 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 en raison d'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 versions plus récentes des bibliothèques et des dépendances, ce qui facilite l'intégration à des systèmes externes.

Accès aux capacités UI Automation modernes

De nombreuses nouvelles fonctionnalités d'UI Automation, telles que Cible unifiée 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 s'appuient sur l'API Outlook classique) vers UiPath.MicrosoftOffice365.Activities basée sur UiPath Integration Service.

Migrateur des activités vs. convertisseur Studio Windows - Héritage

Utilisez le convertisseur Studio Windows - Héritage lorsque :

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

Utilisez le Migrateur d'activités lorsque :

• Vous souhaitez convertir plusieurs projets Windows - Héritage vers Windows (conversion en bloc prise en charge).
• La migration des activités UI Automation ou Mail est nécessaire.
• Toute combinaison des scénarios ci-dessus s'applique.

Où obtenir le Migrateur d'activités

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

1. Naviguez vers UiPath Automation Cloud.
2. Sélectionnez le bouton Aide dans le coin supérieur droit.
3. Sous Ressources, sélectionnez Téléchargements.
4. Sous la liste Téléchargement de fonctionnalités, sélectionnez Outil Migrateur d'activités.
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 Migrateur d'activités

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 d'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 du projet à analyser ou à mettre à niveau. Le dossier fourni sous la forme <project-path> doit contenir le fichier project.json du projet.
-o, --output-path	Chemin de sortie pour le projet mis à niveau (facultatif). S'il n'est pas spécifié, un nouveau dossier avec le suffixe _Upgraded est créé.
-v, --verbose	Activez la journalisation Verbose.
-f, --output-format	Format de sortie : console (par défaut) ou sarif.
-e, --extension-directory	Répertoire pour rechercher des extensions. Pour une utilisation avancée uniquement.
--ignore-missing-dependencies	Ignorez les dépendances manquantes pendant la mise à niveau. Les dépendances manquantes apparaissent sous forme d'avertissements. Les workflows affectés peuvent signaler des types manquants, ne pas parvenir à compiler ou ne pas parvenir à 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. Lorsqu'elle est spécifié, vous devez également fournir des identifiants via un jeton d'accès personnel (PAT) à l'aide de --orchestrator-pat ou l'ID d'application externe et le secret à l'aide de --orchestrator-application-id et --orchestrator-application-secret.
--orchestrator-tenant	Le nom du locataire d'Orchestrator. Si aucune valeur n'est indiquée, la valeur par défaut est DefaultTenant.
--orchestrator-pat	Jeton d'accès personnel (PAT) pour l'authentification d'Orchestrator, utilisé pour accéder aux flux de la bibliothèque d'Orchestrator. Créez un jeton d'accès personnel et ajoutez l'étendue d'accès à l'API OrchestratorOR.Execution.Read. Reportez-vous à Jetons d'accès personnels. Vous pouvez également configurer un ID d'application et un secret à l'aide de --orchestrator-application-id et --orchestrator-application-secret.
--orchestrator-application-id	ID d'application OAuth pour l'authentification d'Orchestrator (alternative à PAT). Utiliser avec --orchestrator-application-secret. Reportez-vous à Gestion des applications OAuth externes.
--orchestrator-application-secret	Secret d'application OAuth pour l'authentification d'Orchestrator (alternative à PAT). Utiliser avec --orchestrator-application-id. Reportez-vous à Gestion des applications OAuth externes.
--enabled-extensions	Liste des 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 des extensions à désactiver, séparées par des virgules. Les extensions disponibles sont remplies dynamiquement en fonction des extensions découvertes.
--disable-all-extensions	Désactivez toutes les extensions. Cette option est mutuellement exclusive avec --enabled-extensions et --disabled-extensions.
--uia-package-version	La version du package d'activités UI Automation à utiliser pour la migration. Si aucune valeur n'est indiquée, la valeur par défaut est 25.10.21. 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'elle est définie sur true, corrige l'ambiguïté de l'énumération SelectorStrategy dans les expressions préexistantes après la migration. S'applique à la version 25.10.29 d'UIAutomation ou ultérieure. Par défaut : false. L'ambiguïté résulte de l'énumération SelectorStrategy existante à la fois dans les espaces de noms UiPath.Core et UiPath.UIAutomationNext.Enums.L'utilisation du nom entièrement qualifié résout ce problème.
--mail-o365-package-version	La version du package d'activités Microsoft Office 365 à utiliser pour la migration. La version par défaut est 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 affecter des valeurs constantes à des propriétés qui nécessitent une entrée de l'utilisateur pendant la migration. Reportez-vous à Fichier de configuration.

Migrer un projet

Cette option effectue la migration réelle d'un projet ou de 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 pour le projet mis à niveau (facultatif). S'il n'est pas spécifié, un nouveau dossier avec le suffixe _Upgraded est créé.
-v, --verbose	Activez la journalisation Verbose.
-f, --output-format	Format de sortie : console (par défaut) ou sarif.
-e, --extension-directory	Répertoire pour rechercher des extensions. Pour une utilisation avancée uniquement.
--ignore-missing-dependencies	Ignorez les dépendances manquantes pendant la mise à niveau. Les dépendances manquantes apparaissent sous forme d'avertissements. Les workflows affectés peuvent signaler des types manquants, ne pas parvenir à compiler ou ne pas parvenir à effectuer d'autres migrations nécessaires.
--orchestrator-url	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'ils sont spécifiés, les identifiants sont requis.
--orchestrator-tenant	Le nom du locataire d'Orchestrator. Si aucune valeur n'est indiquée, la valeur par défaut est DefaultTenant.
--orchestrator-pat	Jeton d'accès personnel (PAT) pour l'authentification d'Orchestrator. Nécessite l'étendue OR.Execution.Read.
--orchestrator-application-id	ID d'application OAuth pour l'authentification d'Orchestrator (alternative à PAT).
--orchestrator-application-secret	Secret d'application OAuth (alternative à PAT).
--enabled-extensions	Liste des extensions à activer, séparées par des virgules. Extensions disponibles : UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemple : --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Liste des extensions à désactiver, séparées par des virgules. Les extensions disponibles sont remplies dynamiquement en fonction des extensions découvertes.
--disable-all-extensions	Désactivez toutes les extensions. Mutuellement exclusifs avec --enabled-extensions et --disabled-extensions.
--uia-package-version	Version du package UiPath.UIAutomation.Activities cible. Par défaut, il s'agit de 25.10.21.
--uia-fix-selector-strategy	Lorsqu'elle est définie sur true, corrige l'ambiguïté de l'énumération SelectorStrategy dans les expressions préexistantes après la migration. S'applique à la version 25.10.29 d'UIAutomation ou ultérieure. Par défaut : false. L'ambiguïté résulte de l'énumération SelectorStrategy existante à la fois dans les espaces de noms UiPath.Core et UiPath.UIAutomationNext.Enums.L'utilisation du nom entièrement qualifié résout ce problème.
--mail-o365-package-version	La version du package d'activités Microsoft Office 365 à utiliser pour la migration. La version par défaut est 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 affecter des valeurs constantes à des propriétés qui nécessitent une entrée de l'utilisateur pendant la migration. Reportez-vous à Fichier de configuration.

Migration en bloc du référentiel

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 au dossier. La migration est effectuée sur tous les sous-dossiers qui contiennent un fichier project.json.
-c, --command (requis)	Commande à exécuter : analyze ou upgrade.
-v, --verbose	Activez la journalisation Verbose.
-o, --output-path	Chemin 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	L'URL complète d'Orchestrator, y compris le nom de l'organisation.
--orchestrator-tenant	Le nom du locataire d'Orchestrator. Si aucune valeur n'est indiquée, la valeur par défaut est DefaultTenant.
--orchestrator-pat	Jeton d'accès personnel (PAT) pour l'authentification d'Orchestrator. Nécessite l'étendue OR.Execution.Read.
--orchestrator-application-id	ID d'application OAuth pour l'authentification d'Orchestrator (alternative à PAT).
--orchestrator-application-secret	Secret d'application OAuth (alternative à PAT).
--enabled-extensions	Liste des extensions à activer, séparées par des virgules. Extensions disponibles : UiAutomationActivities, MailActivities, MicrosoftActivitiesExtension. Exemple : --enabled-extensions MailActivities,MicrosoftActivitiesExtension
--disabled-extensions	Liste des extensions à désactiver, séparées par des virgules. Les extensions disponibles sont remplies dynamiquement en fonction des extensions découvertes.
--disable-all-extensions	Désactivez toutes les extensions. Mutuellement exclusifs avec --enabled-extensions et --disabled-extensions.

Exemples

Analyser un seul projet avec une sortie Verbose :

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

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

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 en bloc 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 à l'aide d'un espace (par exemple, --project-path value). L'option --config est une exception et uniquement prend en charge la syntaxe du signe égal (par exemple, --config=value).
• La sortie par défaut de la commande upgrade est un rapport SARIF stocké dans le projet d'origine sous un dossier .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 entrée manuelle pendant la migration, ou pour remplacer le comportement de migration par défaut.

Transmettez le chemin d'accès 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 affecté est Connection Id.
• {reserved-configuration-key} représente les modifications de comportement spécifiques à l'activité :
  • SaveOutlookMailMessage_IgnoreSaveAsType: Si définie sur true, l'option désactive 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.
• * agit comme un caractère générique et correspond à n'importe quelle valeur à la fois 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.

Obtention de l'ID de connexion à partir d'Orchestrator

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

1. Naviguez vers votre connexion dans Orchestrator : Accédez au dossier Orchestrator où se trouve votre connexion à Microsoft Outlook 365.
2. Ouvrez la connexion : cliquez sur la connexion pour afficher ses détails.
3. Vérifier l'URL : le ConnectionId est visible dans l'URL du navigateur avec le 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 remplie automatiquement pendant 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és à l'aide de l'argument de ligne de commande --config <config>.

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

{
    "* > *": {
        "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 agit comme une solution de secours lorsqu'il n'y a pas d'entrée correspondante ci-dessous.
• *\\Projects\\MailMigration\\Main.xaml > Get * correspond à toute activité dont le nom d'affichage commence par Get dans Main.xaml.
• *\\Projects\\MailMigration\\* > Send Mail correspond à l'activité Send Mail dans 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 (activité Utiliser l'application/le navigateur). Pendant la migration, deux types d'étendues sont créés :

Étendues créées organiquement

Ces étendues sont générées automatiquement lors de la migration d'activités classiques telles que Ouvrir le navigateur et Attacher 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 synthétiquement

Ces étendues sont générées pour s'assurer 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 le même moteur OCR), elles sont fusionnées en une seule étendue tout en préservant l'ordre d'origine de l'activité.

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é ont des limitations de migration. Voir les listes d'activités prises en charge :
  • Activités prises en charge par UI Automation
  • Activités non prises en charge par UI Automation
• Les workflows migrés à l'aide d'activités UI Automation modernes peuvent s'exécuter plus lentement que les workflows d'origine à l'aide d'activités UI Automation classiques.

Activités de productivité

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

Limitations de l'outil

• Par défaut, l'outil Migrateur d'activités utilise les flux NuGet configurés dans NuGet.config : Officiel, Local et Marketplace. Pour inclure les flux de bibliothèque Orchestrator, utilisez les options pour les 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 assemblages générés dynamiquement (par exemple, certaines activités Excel peuvent avoir des noms de colonne 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 de Studio

• La règle Analyseur de workflow ST-AMG-001 est disponible à partir de Studio 2025.10.8 assistance longue durée et Studio 2026.0.189 STS.

Meilleures pratiques de migration

Avant de migrer

1. Sauvegarder vos projets : créez toujours une sauvegarde complète avant d'exécuter des commandes de migration.
2. Mettre à jour les packages de Studio et d'activités : utilisez la dernière version d'UiPath Studio et assurez-vous que les versions de package cibles 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érifier les dépendances et les flux NuGet : confirmez que les flux Officiel, Local et Marketplace sont correctement configurés dans NuGet.config.
5. Migrer d'abord les bibliothèques lorsqu'un projet dépend de projets de bibliothèque : ce n'est qu'à ce moment là qu'il faut migrer les projets qui les utilisent.

Pendant la migration

5. Commencer par un seul projet : testez la migration sur un projet utilisant UiPath.Upgrade.exe upgrade -p -v avant d'exécuter une opération en masse.
6. Utiliser la migration en bloc pour plusieurs projets : une fois validés, exécutez UiPath.Upgrade.exe bulk -p -v. Assurez-vous que la structure du dossier est propre et cohérente.
7. Fournir 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 tous les problèmes signalés.
9. Ouvrir le projet migré dans Studio et exécuter Analyser le projet : examinez les résultats de la règle Analyseur de workflow ST-AMG-001 (disponible dans Studio 2025.10.8 assistance longue durée Studio 2026.0.189 STS ou version ultérieure) 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 Utiliser l'application/le navigateur.
11. Exécuter des tests de bout en bout : exécutez des 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, examinez les sélecteurs pour la précision et la stabilité.
13. Surveiller le temps d'exécution : les activités modernes peuvent s'exécuter plus lentement au départ. Optimisez si 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.