Migration: Durchschlagende Änderungen

Semantische Änderungen, die Pipelines auf eine Weise unterbrechen, die ein Flag-für-Flag-Port nicht erkennen würde. Lesen Sie diese Seite vor dem Port; Die Befehlszuordnung und Flag-Umbenennungen verarbeiten die maschinelle Umbenennung.

Jede Änderung unten hat die gleiche Struktur: was sich geändert hat, warum es geändert wurde, was zu tun ist. Überspringen Sie die fettgedruckten ersten Zeilen und gehen Sie darauf ein, wo Ihre Pipeline betroffen ist.

Authentifizierungsmodi entfernt

Was sich geändert hat. Legacy uipcli akzeptierte drei Authentifizierungsmodi pro Befehl: Benutzer/Kennwort (-u/-p), Aktualisierungstoken (-t/-a) und Externe Anwendung (-A/-I/-S/--applicationScope). Die neue CLI akzeptiert nur Client-Anmeldeinformationen für externe Anwendungen (für CI), interaktive OAuth2 (für Entwickler) und Zugriffstoken mit Umgebungsvariablen (für Container). Benutzer/Kennwort- und Aktualisierungstoken-Authentifizierung sind weg – die Flag-Buchstaben -u, -p, -t, -a sind entweder nicht zugewiesen (-u, -p, -a) oder werden umfunktioniert (-t ist jetzt --tenant).

Warum. In Automation Cloud sind die Benutzer-/Kennwort- und Aktualisierungsflows für neue Workloads veraltet. Anmeldeinformationen für externe Anwendungen sind der einzige Flow, der sauber über CI-Ausführungen hinweg skaliert werden kann, die Prüfung auf Organisationsebene unterstützt und ohne Rotieren eines menschlichen Kontos widerrufen werden kann.

Was zu tun ist. Erstellen Sie eine externe Anwendung in UiPath mit denselben Scopes, die Ihre Pipeline derzeit unter --applicationScope auflistet, und ersetzen Sie dann jeden Befehls-Authentifizierungsblock durch einen einzelnen uip login -Aufruf:

# Legacy — auth on every command
uipcli job run "MyProcess" "https://cloud.uipath.com/" "Tenant" \
    -u "[e-mail]" -p "$PASSWORD" -o "Shared"

# uip — auth once, use many
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"
uip or jobs start "$PROCESS_KEY"

Den vollständigen Flow-Katalog finden Sie unter Authentifizierung . Im Abschnitt „Authentifizierung“ von Flag-Umbenennungen wird jedes entfernte Flag aufgelistet.

Implizites Lesen der env-var-Authentifizierung entfernt

Was sich geändert hat. Legacy uipcli hat UIPATH_CLIENT_ID und UIPATH_CLIENT_SECRET implizit aus der Umgebung gelesen, wenn entsprechende Flags fehlten. Die neue CLI tut dies nicht – Umgebungsvariablen werden nur gelesen, wenn Sie explizit über das Präfix env.VAR_NAME auf --client-id / --client-secret oder über den Flow für das Zugriffstoken UIPATH_CLI_ENABLE_ENV_AUTH=true auf sie verweisen.

Warum. Implizite Lesevorgänge machten es unmöglich, aus einem Pipelineschritt allein zu erkennen, von welchen Geheimnissen der Befehl abhing. Das explizite Präfix-Formular env. zeigt die Abhängigkeit im Aufruf selbst an, was die Prüfung, Rotation und Überprüfung von Geheimnissen zuverlässig macht.

Was zu tun ist. Ersetzen Sie jede implizite Abhängigkeit von den env-Variablen durch explizite env. -Verweise:

# Before — relied on implicit reading
UIPATH_CLIENT_ID="..." UIPATH_CLIENT_SECRET="..." uipcli job run ...

# After — explicit reference
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"

Das Formular env. liest die Variable zur Laufzeit, ohne sie in der Befehlszeile zu erweitern, sodass das Geheimnis nicht im Shell-Verlauf oder in ps -Ausgabe erscheint – ein sichereres Muster als das implizite Lesemuster der Legacy-Version. Siehe Authentifizierung – das Präfix env.VAR_NAME .

Versionen mit Kalenderversion sind nicht mehr verfügbar

Was sich geändert hat. Legacy wurde als Kalenderversion (2023.10, 2024.10, 2025.10) auf NuGet (UiPath.CLI, UiPath.CLI.Windows) mit Ordnerlayouts wie .../UiPath.CLI.25.10.xxxx/tools/uipcli.dll ausgeliefert. Die neue CLI wird auf npm als @uipath/cli mit semantischer Versionierung (1.0.0, 1.0.1, 1.1.0, 2.0.0) verteilt.

Warum. Die Kalenderversionierung kommuniziert das Veröffentlichungsdatum, aber nicht die Kompatibilität. Semver kommuniziert Kompatibilität: 1.0.x → 1.1.x ist zusätzlich, 1.x → 2.x ist unterbrechend und von einem Veraltungszyklus vorausgegangen. Host- und Toolpakete werden auch automatisch an die MAJOR.MINOR -Zeile der CLI angeheftet.

Was zu tun ist. Entfernen Sie jeden Verweis auf NuGet-Pakete mit Kalenderversion, uipcli.dll -Pfade und jährliche Ordnernamen aus Pipelines. Mit npm installieren, mit @x.y.z anheften:

# Before — Azure DevOps example
curl -L -O https://www.nuget.org/api/v2/package/UiPath.CLI.Windows/25.10.xxxx
unzip UiPath.CLI.Windows.25.10.xxxx -d ./cli
./cli/tools/uipcli.exe ...

# After
npm install -g @uipath/cli@1.0.0
uip tools install or solution tm   # pre-install tools (optional but deterministic)
uip ...

Den vollständigen Serververtrag finden Sie unter Installieren der UiPath CLI und Versionierung und Stabilität .

Runtime-Änderung: Node.js 18+ ersetzt .NET als CLI-Runtime; Das RPA-Tool behält eine.NET-Abhängigkeit bei

Was sich geändert hat. Legacy uipcli wurde vollständig mit .NET ausgeführt (UiPath.CLI erforderte plattformübergreifend.NET 6; UiPath.CLI.Windows verwendete.NET Framework). Der neue uip -Host ist ein Node.js-Programm – jeder Aufruf erfordert Node.js 18 oder höher auf dem Runtime, unabhängig davon, welche Tools verwendet werden. Der Host selbst hat keine.NET-Abhängigkeit und die meisten Tools (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI) senden nur HTTPS-Aufrufe und fügen nichts weiter hinzu.

Das RPA-Tool (@uipath/rpa-tool, aufgerufen als uip rpa pack / analyze / restore) ist die Ausnahme. Es umschließt den Studio-Paketer und den Workflow-Compiler, die beide.NET-unterstützt sind. Pipelines, die uip rpa … -Befehle ausführen, benötigen zusätzlich zu Node.js eine.NET-Runtime, nicht anstelle dieser. Die aktuellen Voraussetzungen finden Sie in der UIP-RPA-Referenz .

Warum. Die Kern-CLI wurde zu Node verschoben, um eine kleinere, portierbarere Runtime zu ermöglichen, eine einfachere plattformübergreifende Verteilung und eine Single-Registry-Story (npm). Die RPA-spezifische Oberfläche behielt ihr.NET-Backend bei, da der Studio Paketer und die Analyse native .NET sind – das Neuschreiben war für 1.0 außerhalb des Scopes.

Was zu tun ist.

1. Stellen Sie immer Node.js 18+ auf dem Runtime bereit . Dies ist für uip selbst erforderlich; Ohne Knoten wird kein uip -Befehl ausgeführt.

   # GitHub Actions example
   - uses: actions/setup-node@v4
     with:
       node-version: '20'
   

2. Wenn Ihre Pipeline uip rpa pack, uip rpa analyze oder uip rpa restore aufruft, halten Sie auch eine.NET-Runtime für den Runtime verfügbar . Sie installieren die Legacy- uipcli nicht mehr über dotnet tool install, aber die.NET-Laufzeit selbst muss weiterhin vorhanden sein, damit rpa-tool den Studio-Paketer aufrufen kann.

3. Wenn Ihre Pipeline uip rpa … nicht aufruft, entfernen Sie den Setup-Schritt für.NET/ dotnet-sdk . Die verbleibenden Tools (Orchestrator, Lösung, Agent, Flow, Maestro, Test Manager usw.) benötigen es nicht.

Siehe Installieren von UiPath CLI – CI/CD.

Exit-Code-Vertrag verfeinert

Was sich geändert hat. Legacy uipcli gab eine größere Auswahl an Exitcodes aus und gemischte häufig .NET-Codes auf Prozessebene (1–3 Stellen, Framework-spezifisch) mit Codes auf Befehlsebene. Die neue CLI gibt genau fünf kanonische Codes (0, 1, 2, 3, 4) plus 130 für den Benutzerabbruch aus und die Zuordnung von Ergebnis zu Code ist innerhalb einer MaJOR-Version stabil .

Code beenden	Bedeutung
0	Erfolg.
1	Generischer Fehler oder Konfigurationsfehler.
2	Authentifizierungsfehler (401 / 403).
3	Validierungsfehler (false Flags, unbekannte Option, sich gegenseitig ausschließende Flags).
4	Timeout-Fehler. Reserviert; kein Befehl gibt es in 1.x aus.
130	Benutzer abgebrochen (Strg+C).

Eine domänenspezifische Wiederverwendung: uip tm wait gibt 2 beim Timeout zurück (damit Skripte Timeout und Authentifizierungsslot unterscheiden können). Andernfalls ist der Vertrag einheitlich.

Warum. Ein kleiner, stabiler Satz von Codes macht die Logik der CI-Wiederholung/Eskalation einfach: 2 bedeutet „erneut authentifizieren, dann wiederholen“; 3 bedeutet „ nie wiederholen, Befehl korrigieren“; 1 bedeutet „einmal wiederholen, wenn vorübergehend“. Die großen Legacy-Pipelines mussten die Codes jedes Befehls einzeln verarbeiten.

Was zu tun ist. Ersetzen Sie codespezifische Verzweigungen durch die neuen fünf. Wenn Ihre Pipeline eine Logik wie „Wiederholen bei jedem Code ungleich Null“ hat, verkürzen Sie sie, um es nur bei 1 zu wiederholen:

# Before — broad retry
if ! uipcli job run ...; then sleep 30; uipcli job run ...; fi

# After — targeted branching
if ! uip or jobs start "$KEY" --wait-for-completion; then
    case $? in
        2)   uip login ...; uip or jobs start "$KEY" --wait-for-completion ;;
        3)   exit 3 ;;   # don't retry bad input
        *)   exit 1 ;;
    esac
fi

Hinweis: uip tm testsets run beendet 0immer , sobald der Test Manager die Ausführungsanforderung akzeptiert. Fehler treten durch uip tm wait + uip tm report get mit Data.Failed auf, nicht mit dem Exitcode von run. Siehe Exitcodes. Die Seite uip tm wait dokumentiert die Semantik des Exit-Codes.

Stdout ist standardmäßig JSON

Was sich geändert hat. Legacy uipcli hat lesbaren Protokolltext in Standardausgabe geschrieben; der Exit-Code und alle erzeugten Dateien waren die einzigen maschinenlesbaren Ausgaben. Die neue CLI schreibt standardmäßig bei jedem Befehl einen JSON-Umschlag in standardout:

{
  "Result": "Success",
  "Code": "JobCompleted",
  "Data": { "Key": "...", "State": "Successful", "...": "..." }
}

Protokolle, Fortschritt und von Menschen verursachte Fehler werden unabhängig vom --output -Wert in standardisiert. Die visuell lesbare Tabellenansicht ist mit --output table optional.

Warum. Eine JSON-First-Ausgabe bedeutet, dass jeder Befehl ohne Analysetipps skriptfähig ist und derselbe Aufruf in einem Terminal und einer Pipeline identisch funktioniert. Protokolle auf standardrr bedeutet, dass eine Pipeline sauber command > payload.json 2> log.txt werden kann.

Was zu tun ist. Jeder Shell-Schritt, der die grep-Textausgabe uipcli , muss zu einem der folgenden wechseln:

• --output-filter "<JMESPath>" --output plain – Extrahieren Sie ein einzelnes Feld als Nur-Text. Beispiel: --output-filter "Data.Key" --output plain.
• jq – den vollständigen Umschlag parsen.
• --output table – nur Anzeige; Tabellenausgabe nicht analysieren.

# Before
JOB_ID=$(uipcli job run ... | grep -oP 'JobId=\K[0-9a-f-]+')

# After
JOB_KEY=$(uip or jobs start "$KEY" \
    --output-filter "Data.Jobs[0].Key" \
    --output plain)

Siehe Ausgabeformate. Das Flag --output-filter selbst ist unter Globale Optionen dokumentiert.

Mandant- und Orchestrator-URL sind Sitzungsstatus, keine Flags pro Befehl

Was sich geändert hat. Legacy uipcli verwendete <orchestrator_url> und <orchestrator_tenant> als Positionargumente für jedes Verb (job run "<name>" "<url>" "<tenant>" ...). Die neue CLI löst beide aus der authentifizierten Sitzung auf, die von uip login geschrieben wurde; Es wird niemals eine Positions-URL benötigt, und der Mandant ist ein Sitzungsstandard, den jeder Befehl mit -t, --tenant <name> überschreiben kann.

Warum. Jeder Befehl in einer Pipeline zielt in der Regel auf denselben Orchestrator ab; Das Übergeben der URL und des Mandanten bei jedem Aufruf wiederholte sich und führte zu Fehlern beim Kopieren und Einfügen. Der Sitzungsstatus mit Überschreibung pro Aufruf ist das Standard-CLI-Muster (siehe az account set, gcloud config set, kubectl config use-context).

Was zu tun ist. Legen Sie die Positions-URL und den Mandanten aus jedem Befehl ab. Legen Sie den Mandanten bei der Anmeldung fest (oder überschreiben Sie ihn pro Aufruf mit -t):

# Before
uipcli package deploy "./pkg.nupkg" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"
uipcli job run "Process" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"

# After
uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant ProdTenant
uip or packages upload ./pkg.nupkg
uip or processes create --name Process --package-key Process --package-version 1.0.0 --folder-path Shared
uip or jobs start "$PROCESS_KEY"

Übergeben Sie bei Skripts mit mehreren Mandanten -t TENANT an jeden Befehl, der einen anderen Mandanten für diesen einen Aufruf benötigt. Siehe Authentifizierung – Verwalten von Mandanten während der Sitzung.

Konzepte klassischer Ordner sind auf der CLI-Oberfläche veraltet

Was sich geändert hat. Die Legacy-CLI enthielt mehrere Flags nur für klassische Ordner: -e, --environments <csv> auf package deploy, -r, --robots <csv> auf job run und ein zugehöriges umgebungsbasiertes Routing. Die neue CLI zielt auf das moderne Ordnermodell ausschließlich auf seine öffentlichen Verben ab. Klassische Ordner sind weiterhin in Orchestrator vorhanden, aber uip stellt keine klassischen Flags bereit.

Warum. Moderne Ordner sind seit 2020 der Standard. Wenn Sie nur klassische Flags auf der neuen CLI beibehalten würden, hätte dies bedeutet, dass veraltetes Verhalten in eine neue Version übertragen wird.

Was zu tun ist. Wenn Ihre Pipeline auf einen klassischen Ordner abzielt, (a) migrieren Sie den Ordner entweder zu einem modernen Ordner (Orchestrator-Administratoroberfläche), oder (b) verwenden Sie weiterhin uipcli für diese spezifischen Aufrufe über den @uipath/rpa-legacy-tool -Wrapper. Siehe uip rpa – Legacy-Wrapper für nur Windows.

Sprach-/Gebietsschema-Flag entfernt

Was sich geändert hat. Legacy -l, --language <locale> hat die Protokollausgabe in das angegebene Gebietsschema übersetzt. Die neue CLI gibt Protokolle nur auf Englisch aus.

Warum. Protokollmeldungen sind für die Verwendung von Operatoren und Protokollversendensystemen gedacht, die beide Englisch standardisieren. Die Lokalisierung war ein Kostenaufwand ohne klaren Nutzen für die CLI-Ebene.

Was zu tun ist. Entfernen Sie -l / --language Flags aus der Pipeline. Es ist kein Ersatz erforderlich.

Capture-and-Replay (--captureCommandToJsonFile + uipcli-Ausführung) wurde entfernt

Was sich geändert hat. Legacy hatte ein ausgeblendetes --captureCommandToJsonFile <path> -Flag, das den aktuellen Aufruf in JSON serialisiert hat, und ein uipcli run <file> -Verb, das dieses JSON-Objekt verbraucht hat, um den Befehl wiederzugeben. Beide wurden entfernt.

Warum. Das Muster wurde hauptsächlich zum Debuggen der Zuordnung der GUI-Aufgabe in Azure DevOps zu CLI-Flags verwendet, nicht als Produktionsmechanismus. Der neue CLI-Standard JSON-stdout und die JMESPath-Filterung decken den Debugging-Anwendungsfall ohne separates Subsystem ab.

Was zu tun ist. Schreiben Sie jeden Pipelineschritt neu, der uipcli run <file> als direkten uip -Aufruf verwendet hat. Wenn Sie zum Debuggen von --captureCommandToJsonFile abhängig waren, lautet das neue Äquivalent uip <command> --log-level debug --log-file ./uip.log – die Protokolldatei enthält jeden HTTP-Aufruf, jede Authentifizierungsaktualisierung und jede Toolladung.

Umgebungsvariable für die Telemetrie-Opt-out wurde umbenannt

Was sich geändert hat. Beide Generationen werden standardmäßig mit einer anonymen Telemetrie ausgeliefert – die Telemetrie ist aktiviert, es sei denn, Sie deaktivieren sie explizit. Der env var-Name hat sich geändert:

Generation	Variable	Zu deaktivierender Wert
Legacy uipcli	UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED	False
Neu (New) uip	UIPATH_TELEMETRY_DISABLED	1 oder true

Warum. Der neue Name ist kürzer, folgt dem <SCOPE>_DISABLED -Muster, das an anderer Stelle in der CLI verwendet wird, und lässt das Präfix EXTENSIONS_ weg (die neue CLI ist keine Erweiterung von nichts).

Was zu tun ist. Aktualisieren Sie CI-Ausführungen und Entwicklungsmaschinen, die bereits UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED=False festgelegt haben, auf stattdessen UIPATH_TELEMETRY_DISABLED=1. Die Legacy-Variable wird von der neuen CLI ignoriert, sodass eine Maschine, die nur den alten Namen festlegt, erneut Telemetrie sendet, bis die neue hinzugefügt wird. Siehe Neuigkeiten – Andere sinnvolle Verschiebungen.

Siehe auch

• Befehlszuordnung – welches Verb aufgerufen werden soll.
• Flag-Umbenennungen – Flag-für-Flag-Zuordnung.
• Pipeline-Beispiele – vor/nach YAML für die gängigen CI-Plattformen.
• Austrittscodes – der fünfstufige Vertrag.
• Neuigkeiten – positive Zusammenfassung aller Neufassungen.