Résolution des problèmes d'interface en ligne de commande UiPath

Si vous rencontrez des problèmes lors de votre utilisation de la CLI UiPath, envisagez les scénarios de résolution de problèmes suivants.

Problèmes liés à la version .NET

Description:

Vous pouvez rencontrer des problèmes avec les tâches CLI UiPath et les opérations de pipeline si la bonne version de l'infrastructure .NET n'est pas installée (ou est manquante) sur votre système.

Lorsque ce problème se produit, vous pouvez rencontrer des messages d’erreur tels que :

  You must install or update .NET to run this application.
  App: C:\Program Files (x86)\UiPath CLI\UiPath.CLI.Windows.23.10.8894.39673\tools\uipcli.exe
  Architecture: x64
  Framework: 'Microsoft.NETCore.App', version '6.0.0' (x64)
  .NET location: C:\Program Files\dotnet
  The following frameworks were found:
  8.0.5 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  8.0.8 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

ou

  An error occurred trying to start process 'dotnet' with working directory 'C:\Users\Public\UiPathDevOpsScripts\uipathcli-23.10\tools'. The system cannot find the file specified. Failed to run the command. UiPath.CommandLine.Exceptions.CommandException: Packaging failed due to one or more errors.
  Message: An error occurred trying to start process 'dotnet' with working directory 'C:\Users\Public\UiPathDevOpsScripts\uipathcli-23.10\tools'. The system cannot find the file specified.
  Error at: System.Diagnostics.Process.StartWithCreateProcess(ProcessStartInfo startInfo)

Remedy:

Vous devez vous assurer que la bonne version .NET est installée.

Pour la matrice de compatibilité des versions CLI et .NET , reportez-vous à la section Prérequis .

Problèmes liés au caractère spécial dans les mots de passe de la chaîne de connexion

Dans la plupart des cas, les mots de passe de connexion sont encapsulés par un guillemet unique ('). Cependant, lorsque le mot de passe inclut des caractères spéciaux tels que ` ou $, il est nécessaire de procéder différemment.

Dans ces cas, le mot de passe doit être formaté en tant que \`"<password>\`", en remplaçant <password> par le mot de passe réel. De plus, vous devez également respecter les règles d’échappement comme détaillé dans la table suivante :

Format d’origine dans ADuC	Format échappé dans la chaîne PowerShell
cn=James $ Smith	"cn=James `$ Smith"
cn=Sally Wilson + Jones	"cn=Sally Wilson \+ Jones"
cn=William O'Brian	"cn=William O'Brian"
cn=William O`Brian	"cn=William O``Brian"
cn=Richard #West	"cn=Richard #West"
cn=Roy Johnson$	"cn=Roy Johnson$"

Exemple :

Supposons que le mot de passe d’origine est 7'8:<=XMe$y[@vC?_4ZeY8c-~y'W!1dU4gnczuf'/p>j<I. En respectant les règles d’échappement des caractères spéciaux, elle devient : Password=\`"7'8:<=XMe`$y[@vC?_4ZeY8c-~y'W!1dU4```gnczuf'/p>```j<I\`".

Problèmes liés à des performances lentes du pipeline

Description:

Vous pouvez enregistrer des performances lentes lors du packaging des opérations de packaging dans les pipelines CI/CD. Ce retard se produit généralement pendant la phase de restauration NuGet, où la CLI UiPath résout les dépendances d’activité directes et transitiques.

Ce problème affecte couramment les agents CI hébergés (GitHub Actions, Azure DevOps, GitLab, Jenkins) qui partent d’un environnement propre. Le cache du package global NuGet n’est pas conservé entre les exécutions, sauf s’il est explicitement configuré, ce qui nécessite un téléchargement complet de toutes les dépendances de chaque tâche.

Emplacements du cache NuGet :

• Linux/macOS : ~/.nuget/packages
• Windows : %UserProfile%\.nuget\packages

Facteurs contributeurs :

Lorsqu’aucun nuget.config personnalisé n’est fourni, NuGet interroge toutes les sources par défaut dans la séquence :

https://api.nuget.org/v3/index.json
https://pkgs.dev.azure.com/uipath/Public.Feeds/_packaging/UiPath-Official/nuget/v3/index.json
https://gallery.uipath.com/api/v3/index.json
https://uipath.pkgs.visualstudio.com/Public.Feeds/_packaging/UiPath-Internal/nuget/v3/index.json

NuGet n'ignore pas les flux lents ou inaccessibles. Il attend une réponse ou un délai d'expiration avant de passer à la source suivante. Pour chaque paquet manquant, NuGet effectue les opérations suivantes :

1. Une recherche de cache (vide pour les nouveaux agents).
2. Une sonde de chaque flux configuré dans l'ordre.
3. Une attente ou un délai d'attente si un flux ne répond pas.
4. Un téléchargement après une source accessible est trouvé.

Le délai varie avec le nombre de dépendances. Sans cache, ce processus se répète pour chaque package de chaque exécution de pipeline.

Solution :

Pour améliorer les performances de restauration :

1. Utilisez un fichier nuget.config rogné qui n’inclut que les flux accessibles depuis l’agent de développement. Reportez-vous à la section Gestion des flux NuGet pour plus de détails sur la configuration.

2. Configurez la persistance du cache pour le cache global du paquet NuGet entre les exécutions de pipeline.

   Exemple pour Azure DevOps (agent Windows) :

   - task: Cache@2
     displayName: "NuGet Cache"
     inputs:
       key: 'nuget | "$(Agent.OS)" | packages'
       restoreKeys: |
         nuget | "$(Agent.OS)"
       path: '$(UserProfile)\.nuget\packages'
   

3. Utilisez des exécuteurs auto-hébergés avec un stockage persistant si l’environnement l’exige.

Problèmes liés à la disponibilité du runtime .NET

Description:

Vous pouvez rencontrer des problèmes où la CLI UiPath ne peut pas localiser le runtime .NET sur les agents de développement, ce qui entraîne des erreurs telles que :

dotnet is not recognized

Ce problème se produit lorsque le compte de service exécutant l’agent de développement n’hérite pas de la variable d’environnement PATH de la machine, même si .NET est correctement installé sur le système.

Solution :

Vous devez définir explicitement le chemin d’installation .NET au niveau du pipeline, de la tâche ou de l’agent avant d’exécuter des commandes CLI.

Exemple pour Windows :

env:
  PATH: 'C:\Program Files\dotnet;$(PATH)'

Remarque :

Les modifications apportées au script en ligne sur la variable PATH ne se propagent pas dans les processus enfants. Le chemin doit être configuré au niveau du pipeline, de la tâche ou de l'agent pour garantir que la CLI UiPath peut localiser le runtime .NET dans les scénarios d'installation par défaut et personnalisés.

Problèmes liés à la validation du proxy et du certificat SSL

Description:

Vous pouvez rencontrer des erreurs de validation de certificat SSL lorsque vous exécutez la CLI UiPath dans des environnements d'entreprise avec des proxys d'inspection SSL. Les messages d’erreur courants incluent les éléments suivants :

self-signed certificate in certificate chain
The SSL connection could not be established, see inner exception

Ce problème se produit car les outils basés sur le nœud, y compris les tâches UiPath CLI et NuGet, ne lisent pas le magasin de certificats du système Windows ou Linux, même lorsque le système d'exploitation fait confiance au certificat du proxy.

Solution :

Pour résoudre les problèmes de validation de certificat dans les environnements d’entreprise :

1. Configurez les variables d’environnement de proxy. Définissez les variables suivantes au niveau du pipeline, de la tâche ou de l'agent avant que toute tâche CLI ou Nœud s'exécute :

   HTTP_PROXY
   HTTPS_PROXY
   

   Cela garantit que l'agent de développement et tous les processus enfants héritent de la configuration du proxy.

2. Configurez l'approbation du certificat pour Node.js. Si le proxy utilise une autorité de certification (CA) privée ou auto-signée, vous devez exporter le certificat CA au format .pem et configurer Node.js pour l'approuver :

   NODE_EXTRA_CA_CERTS=<path-to-pem>
   

   Exemple pour Windows :

   NODE_EXTRA_CA_CERTS=C:\agent\certs\myCA.pem
   

   Node.js chargera ce fichier de certificat au démarrage, permettant aux appels HTTPS de réussir sans erreur de certificat.

Important :

Vous devez déclarer ces variables d'environnement au niveau du pipeline, de la tâche ou de l'agent. Les définir dans des étapes individuelles de script PowerShell ou Bash ne propage pas les valeurs dans les sous-processus Node.js.

Problèmes liés à la gestion des paramètres PowerShell

Caractères spéciaux dans le paramètre ApplicationSecret

Description:

Lors de l'utilisation du paramètre --applicationSecret dans les scripts PowerShell, des caractères spéciaux tels que $, `, !, et d'autres peuvent entraîner des échecs d'authentification ou un comportement inattendu. Cela se produit parce que PowerShell interprète ces caractères comme des opérateurs spéciaux lorsqu'ils sont placés entre guillemets doubles.

Par exemple, PowerShell traite $ comme un opérateur d'expansion de variable, de sorte qu'une clé secrète telle que mySecret$123 entre guillemets doubles devient mySecret123 (si $123 n'est pas défini) ou est remplacée par une valeur involontaire.

Symptômes courants :

• Échec de l'authentification avec des informations d'identification valides
• Erreur : « Non autorisé » ou « Informations d’identification non valides »
• Comportement incohérent lorsque la même commande fonctionne dans d’autres shells

Solution :

Utilisez des guillemets simples ('') au lieu de guillemets doubles ("") lorsque vous passez le paramètre --applicationSecret . Les guillemets uniques empêchent PowerShell d'interpréter les caractères spéciaux :

# Correct - single quotes treat the string literally
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S 'mySecret$123!@#' `
  -o "MyFolder"

# Incorrect - double quotes allow variable expansion
uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
  -A "myOrg" `
  -I "app-id" `
  -S "mySecret$123!@#" `
  -o "MyFolder"

Approches alternatives :

1. Stockez les clés secrètes dans les variables d'environnement :

   $env:APP_SECRET = 'mySecret$123!@#'
   uipcli package deploy "C:\packages\MyPackage.nupkg" "https://cloud.uipath.com/" "default" `
     -A "myOrg" `
     -I "app-id" `
     -S $env:APP_SECRET `
     -o "MyFolder"
   

2. Utiliser la gestion des clés secrètes de la plate-forme CI/CD :

   • Azure DevOps : Variables secrètes de pipeline
   • Actions GitHub : clés secrètes
   • Jenkins : Plug-in d’identifiants

Astuce :

Ce problème est spécifique à PowerShell. Dans Bash, CMD ou d'autres shells, les règles de guillemets standard s'appliquent.

Problèmes liés à l'authentification

Erreur : "Unauthorized" ou "403 Forbidden"

Description:

Vous pouvez recevoir des erreurs d'authentification lorsque vous exécutez des commandes CLI UiPath qui interagissent avec Orchestrator.

Causes possibles :

• L’ID ou le secret de l’application externe est incorrect(e)
• Les étendues requises ne sont pas affectées à l'application externe
• Le nom d’organisation spécifié avec le paramètre -A ne correspond pas à votre organisation Orchestrator

Solution :

• Vérifiez les informations d’identification de l’application externe dans Orchestrator sous Admin → Applications externes.
• Confirmez que toutes les étendues requises sont affectées à l’application externe. Reportez-vous à la section Authentification et étendues pour obtenir la liste complète des étendues requises.
• Assurez-vous que le nom de l'organisation correspond exactement (sensible à la casse).

Erreur : « Étendue non valide »

Description:

Vous pouvez rencontrer des erreurs indiquant que l'étendue d'application spécifiée n'est pas valide ou n'est pas reconnue.

Causes possibles :

• Des noms d'étendue incorrects sont utilisés.
• Les étendues Orchestrator et les étendues Solutions sont mixtes dans le même paramètre.

Solution :

• Pour les opérations Solutions, utilisez les étendues suivantes : AutomationSolutions, Solutions.Deployments, Solutions.Packages, ainsi que leurs sous-étendues respectives.
• Ne combinez pas d'étendues Orchestrator ( telles que OR.Jobs) avec des étendues Solutions dans le même paramètre --applicationScope .

Erreur : « Échec de la validation du certificat »

Description:

Des erreurs de validation de certificat SSL peuvent se produire lors de l'exécution de commandes CLI dans des environnements avec des serveurs proxy.

Solution :

• Configurez la variable d'environnement NODE_EXTRA_CA_CERTS comme décrit dans Problèmes liés à la validation du proxy et du certificat SSL
• Assurez-vous que les variables de proxy (HTTP_PROXY, HTTPS_PROXY) sont configurées au niveau du pipeline ou de l’agent

Problèmes liés au packaging et au déploiement

Erreur : « La version est requise »

Description:

Vous pouvez rencontrer cette erreur lorsque vous tentez de compresser une solution sans spécifier de numéro de version. Contrairement aux projets autonomes, les solutions n’incrémentent pas automatiquement leur version.

Solution :

Vous devez fournir le paramètre --version lors de l'exécution de la commande pack :

uipcli solution pack <solution-path> --version 1.2.3 --output <output-folder>

Erreur : « Format de version non valide »

Description:

Cette erreur se produit lorsque le numéro de version ne suit pas le format de contrôle de version sémantique requis.

Solution :

1.0.0 le format 2.3.45: MAJOR.MINOR.PATCH

Les formats suivants ne sont pas valides:

• 1.0 (composant de correctif manquant)
• 1.0.0.0 (trop de composants)
• v1.0.0 (contient un préfixe non numérique)
• 1.0-beta (contient le suffixe)

Erreur : « Impossible de résoudre les dépendances »

Description:

Cette erreur indique que les dépendances de la solution n’ont pas été restaurées avant le packaging.

Solution :

Exécutez la commande restore avant d’essayer d’compresser :

uipcli solution restore <solution-path> --restoreFolder <output-folder>
uipcli solution pack <solution-path> --version 1.2.3 --output <output-folder>

Erreur : « Chemin introuvable »

Description:

Le chemin de solution spécifié est introuvable.

Solution :

Vérifiez que le paramètre <solution-path> désigne un dossier de solution ou un fichier .uipx valide.

Erreur : « Package introuvable »

Description:

Cette erreur se produit lorsque vous tentez de référencer un package de solution qui n’existe pas dans Solutions.

Causes possibles :

• Le package n’a pas été chargé avec succès.
• Le nom ou la version du package est incorrect(e).
• La commande cible le mauvais locataire ou la mauvaise organisation.

Solution :

• Vérifiez que le package a été téléchargé à l'aide de uipcli solution upload-package.
• Confirmez que le nom et la version du package sont corrects (notez que ces valeurs sont sensibles à la casse).
• Assurez-vous que le paramètre -T spécifie le locataire correct.

Erreur : « Dossier introuvable »

Description:

Le dossier spécifié n’existe pas dans Orchestrator ou n’est pas accessible.

Causes possibles :

• Le nom du dossier n’existe pas dans Orchestrator.
• Autorisations insuffisantes pour accéder au dossier.
• Le dossier existe dans un autre locataire.

Solution :

• Vérifiez que le nom du dossier spécifié avec le paramètre -f existe dans Orchestrator.
• Confirmez que vous disposez des autorisations nécessaires au déploiement dans ce dossier.
• Assurez-vous que le dossier est situé dans le bon locataire.

Erreur : « Le déploiement existe déjà »

Description:

Un déploiement portant le nom spécifié existe déjà dans le dossier cible.

Solution :

• Utilisez un nom de déploiement unique pour chaque déploiement (par exemple, incluez le numéro de version ou l'horodatage dans le nom).
• Désinstallez le déploiement existant avant d’en créer un nouveau. Consultez la section Désinstallation des déploiements pour plus de détails.

Erreur : « Déploiement introuvable » (lors de l'activation)

Description:

Cette erreur se produit lorsque vous tentez d’activer un déploiement qui n’existe pas.

Causes possibles :

• La commande deploy n'a pas été exécutée avant l'exécution de deploy-activate.
• Le nom du déploiement est incorrect.
• L’opération de déploiement a échoué.

Solution :

• Vérifiez que vous avez exécuté uipcli solution deploy avant d’exécuter uipcli solution deploy-activate.
• Confirmez que le nom du déploiement correspond exactement (notez que les noms de déploiement sont sensibles à la casse).
• Examinez les journaux d'exécution de la commande pour vous assurer que l'opération de déploiement s'est terminée avec succès.