> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/de/plattform/variables.md). # Variablen Erstellen Sie globale und geheime Variablen in PowerShell Universal, verwalten Sie Secret-Tresore und referenzieren Sie integrierte Variablen, die in Skripten, APIs und Apps verfügbar sind. Variablen können in APIs, Skripten und Dashboards verwendet werden. Bei Verwendung der Standardumgebungen werden alle Variablen automatisch importiert. Dies wird erreicht, indem der Parameter `-Variable` von `New-PSUEnvironment` mit einem Platzhalter (\*) angegeben wird. Wenn Sie Ihre eigenen Umgebungen verwenden, müssen Sie konfigurieren, welche Variablen einbezogen werden sollen. Sie können eine Variable wie jede andere PowerShell-Variable referenzieren. Die Variable enthält den von Ihnen festgelegten Wert. Wenn Sie ein Secret verwenden, enthält sie den Wert des Secrets. {% hint style="info" %} Variablen werden in der Konfigurationsdatei `variables.ps1` gespeichert. {% endhint %} ## Erstellen einer Variable Um eine Variable zu erstellen, navigieren Sie zur Seite Manage > Variables & Secrets > Variables. Klicken Sie auf Create Variable, um eine neue Variable zu definieren. Variablen werden Ihren Skripten hinzugefügt, bevor diese ausgeführt werden. ## Erstellen einer geheimen Variable Geheime Variablen werden im ausgewählten Tresor gespeichert. Der Wert dieser Variablen wird niemals in Universal gespeichert. Um eine neue geheime Variable zu definieren, klicken Sie auf der Variablenseite auf Create Secret Variable und wählen Sie die Registerkarte Secret aus. In diesem Dialogfeld können Sie Zeichenfolgen und PSCredentials im angegebenen Tresor definieren. ### Format der Anmeldeinformationen In manchen Umgebungen kann es erforderlich sein, den Domänennamen im Feld für den Benutzernamen anzugeben. Sie können ihn entweder im Format `domain\user` oder `user@domain` angeben. Wenn Sie dies nicht tun, erhalten Sie Fehler beim Versuch, Prozesse wie Skripte oder Dashboards als dieses Benutzerkonto zu starten. ### Group Managed Service Accounts Bei Verwendung von Group Managed Service Accounts (GMSA) müssen Sie sicherstellen, dass der Computer und das Konto Zugriff auf das GSMA-Konto haben. Sie können [der Anleitung von Microsoft hier](https://techcommunity.microsoft.com/blog/itopstalkblog/step-by-step-how-to-work-with-group-managed-service-accounts-gmsa/329864) folgen. Sobald die Konfiguration abgeschlossen ist, erstellen Sie neue Anmeldeinformationen in der PowerShell Universal-Secret-Verwaltung und wählen Sie die Option Password Not Required aus. Geben Sie das GSMA-Konto ein (z. B. domain\user$). Solange das hostende Konto über die erforderlichen Berechtigungen verfügt, können Sie Jobs als GMSA-Konto ausführen. ### Validierung von Anmeldeinformationen Unter Windows können Sie Anmeldeinformationen validieren, bevor Sie deren Wert speichern. Klicken Sie im Passwortfeld auf die Schaltfläche Validate, um zu versuchen, den Benutzer lokal anzumelden. Diese Schaltfläche wird auf Nicht-Windows-Systemen nicht angezeigt. ### Rollen {% hint style="warning" %} Das Anwenden von Rollen auf ein Secret verhindert, dass das Secret in geplanten Jobs zugänglich ist, da im Scheduler keine Rollen angewendet werden. {% endhint %} Geheime Variablen können rollenbasierten Zugriff enthalten. Rollen schränken ein, wer das Secret in seinen Skripten und als Ausführungs-Anmeldeinformationen verwenden kann. Wenn für ein Secret eine Rolle definiert ist, ist es in Ressourcen, die diese Rolle nicht bereitstellen können, nicht zugänglich. Dazu können die folgenden gehören: * Geplante Jobs * Nicht authentifizierte APIs oder Apps * Terminals ## Tresore ### Datenbank Der Datenbank-Tresor speichert Secrets in der PowerShell Universal-Datenbank. Diese Secrets werden mittels AES-Verschlüsselung mit einem anpassbaren Schlüssel verschlüsselt. Sie können den Schlüssel anpassen, indem Sie Secrets \ Database \ EncryptionKey angeben. #### appsettings.json Sie können diese Einstellung in appsettings.json konfigurieren. {% code collapsedlinecount="10" %} ```json "Secrets": { "Database": { "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" } } ``` {% endcode %} #### Umgebungsvariable Sie können diese Einstellung mit einer Umgebungsvariable konfigurieren. {% code collapsedlinecount="10" %} ```powershell $Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" ``` {% endcode %} ### BuiltInLocalVault {% hint style="warning" %} Wenn PowerShell Universal als Group Managed Service Account ausgeführt wird, kann es den `BuiltInLocalVault` nicht verwenden. {% endhint %} Werte für Secrets mit dem `BuiltInLocalVault` werden in der Windows-Anmeldeinformationsverwaltungsinstanz des Sicherheitsprinzipals gespeichert, der PSU ausführt. Zum Beispiel das Dienstkonto des Benutzers, der den Universal-Dienst ausführt. Wenn Sie den Benutzer wechseln (z. B. bei Ausführung als Dienstkonto), hat das Konto keinen Zugriff auf die Secrets des vorherigen Benutzers und Sie müssen diese Secrets erneut hinzufügen. ### PSUSecretStore {% hint style="warning" %} Wenn PowerShell Universal als Group Managed Service Account ausgeführt wird, kann es den `PSUSecretStore` nicht verwenden. {% endhint %} Der Tresor `PSUSecretStore` ist mit dem Microsoft-Modul `SecretStore` integriert, um Secrets in einer plattformübergreifenden Datei zu speichern. Diese Datei ist an das aktuelle Benutzerkonto gebunden, das PowerShell Universal ausführt. Das Passwort für den Tresor wird in `appsettings.json` gespeichert. ### Az.KeyVault {% hint style="info" %} Verwenden Sie die Azure Key Vault-Tresorregistrierung, um Azure Key Vault für PowerShell Universal zu konfigurieren. {% endhint %} Standardmäßig ist die Azure Key Vault-Erweiterung nicht direkt in PowerShell Universal enthalten. Ein Container mit den erforderlichen Modulen Az.Accounts und Az.KeyVault steht zur Verfügung, damit Sie KeyVault sofort nutzen können. Diesen finden Sie auf [Docker Hub](https://hub.docker.com/r/devolutions/powershell-universal). Nachfolgend erfahren Sie, wie Sie es konfigurieren. Dieses Beispiel verwendet eine in Azure gehostete Web-App-Version von PowerShell Universal. In Azure müssen wir eine verwaltete Identität für unsere Web-App konfigurieren. Dieser Schritt ist nicht unbedingt erforderlich, wenn Sie außerhalb von Azure arbeiten. Sie können die verwaltete Identität auf der Seite Identity Ihrer Web-App aktivieren. Schließlich müssen wir den Key Vault registrieren und beim Start der Web-App eine Verbindung zu Azure herstellen. Dies kann mit den Modulen Az.Account und Az.KeyVault erreicht werden. Nach der Bereitstellung Ihrer Web-App müssen Sie zunächst die Module Az.Account und Az.KeyVault installieren. Dies können Sie auf der Modulseite tun. Sie werden im lokalen Repository innerhalb der Web-App installiert. Erstellen Sie als Nächstes ein Skript in PowerShell Universal, um eine Verbindung zu Azure herzustellen und den Tresor zu registrieren. Führen Sie das Skript aus, um zu überprüfen, ob es ordnungsgemäß funktioniert. {% code collapsedlinecount="10" %} ```powershell $sub = 'affdf0d4-eed5-48a6-889c-599d482xxxxx' Connect-AzAccount -Id -Scope CurrentUser -SubscriptionId $sub Register-SecretVault -ModuleName Az.KeyVault -Name AzureKeyVault -VaultParameters @{ AZKVaultName = 'psu-demo' SubscriptionId = $sub } -AllowClobber ``` {% endcode %} Wenn Sie nun Secrets erstellen, wird Ihnen AzureKeyVault zur Verfügung stehen. Um sicherzustellen, dass die Anwendung mit Azure verbunden und der Key Vault registriert ist, führen Sie das Skript in `vaults.ps1` aus. Wir empfehlen, das Skript in einem externen PowerShell-Prozess auszuführen, um Assembly-Konflikte mit PowerShell Universal-DLLs zu vermeiden. {% code collapsedlinecount="10" %} ```powershell $pwsh = (Get-Command pwsh).Path & $pwsh -File "$PSScriptRoot\registerVault.ps1" ``` {% endcode %} Dieses Skript wird ausgeführt, bevor Variablen registriert und Tresore gefunden werden. Sie können diese Datei direkt im Verzeichnis Repository.universal erstellen. Sie wird während des Systemstarts ausgeführt, bevor andere Konfigurationsskripte ausgeführt werden. ### vaults.ps1 Die Datei `vaults.ps1` enthält Befehle zur Tresorregistrierung. Während das obige Beispiel eine Azure KeyVault-Secret-Tresorregistrierung definiert, können Sie in dieser Datei tatsächlich jede benötigte Tresorregistrierung einfügen. Sie können Tresore bearbeiten, indem Sie auf Manage > Variables & Secrets > Vaults klicken und dann zur Registerkarte vaults.ps1 navigieren. ## Importieren geheimer Variablen Sie können auch bereits vorhandene Secrets als Variablen in Universal importieren. Die Variablenwerte werden nicht importiert, sondern während der Ausführung nachgeschlagen. Klicken Sie auf die Schaltfläche Import Secret, um Secrets zu importieren. ## Verwenden von Variablen Variablen können in APIs, Skripten und Dashboards verwendet werden. Bei Verwendung der Standardumgebungen werden alle Variablen automatisch importiert. Dies wird erreicht, indem der Parameter `-Variable` von `New-PSUEnvironment` mit einem Platzhalter (\*) angegeben wird. Wenn Sie Ihre eigenen Umgebungen verwenden, müssen Sie konfigurieren, [welche Variablen einbezogen werden sollen](https://docs.powershelluniversal.com/config/environments#variables). Sie können eine Variable wie jede andere PowerShell-Variable referenzieren. Die Variable enthält den von Ihnen festgelegten Wert. Wenn Sie ein Secret verwenden, enthält sie den Wert des Secrets. {% code collapsedlinecount="10" %} ``` $MyVariable ``` {% endcode %} Sie können anpassen, welche Variablen in einer Umgebung zulässig sind, indem Sie den Parameter `-Variable` der Umgebung anpassen. Weitere Informationen finden Sie unter Environments. ## Secret-Bereich Um auf Secrets zuzugreifen, die Sie zu PowerShell Universal hinzugefügt haben, können Sie den Bereich `$Secret` verwenden. Wenn Sie beispielsweise ein Secret mit dem Namen `Credential` definiert haben, könnten Sie überall mit dem Secret-Bereich darauf zugreifen. Sie können mit dem Secret-Bereich keine Secrets festlegen. {% code collapsedlinecount="10" %} ```powershell Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" } ``` {% endcode %} ### Zugriff auf Variablen nach Namen Sie können mit dem Präfix `$Secret:` nach Namen auf Variablen zugreifen. {% code collapsedlinecount="10" %} ```powershell # PSCredential $Secret:MyNewSecret.UserName $Secret:MyNewSecret.Password # String $Secret:DashboardSecret ``` {% endcode %} ### Dynamischer Zugriff auf Werte Sie können mit `Get-Item` dynamisch auf den Secret-Bereich zugreifen. Der Secret-Bereich ist als Provider implementiert. Dies ist hilfreich, wenn Sie keine statischen Variablennamen haben. {% code collapsedlinecount="10" %} ```powershell # PSCredential (Get-ChildItem "Secret:MyNewSecret").UserName (Get-ChildItem "Secret:MyNewSecret").Password # String (Get-ChildItem "Secret:DashboardSecret") ``` {% endcode %} ### ForEach-Object -Parallel Um Secrets bei der Verwendung von `ForEach-Object` mit dem Parameter `-Parallel` zu nutzen, müssen Sie das Schlüsselwort `$using` verwenden. {% code collapsedlinecount="10" %} ```powershell 1..5 | ForEach-Object -Parallel { $using:Secret:MySecret } ``` {% endcode %} ## Konfigurieren des `PSUSecretStore`-Passworts Standardmäßig wird das Passwort des Tresors `PSUSecretStore` in `appsettings.json` unter Secrets \ SecretStore \ Password gespeichert. ## Integrierte Variablen Die folgenden Variablen sind in allen Umgebungen innerhalb von PowerShell Universal verfügbar. Diese Referenz listet die PowerShell Universal-Variablen auf, die für die Verwendung in Ihrem Code vorgesehen sind. `Get-Variable` gibt außerdem standardmäßige automatische PowerShell-Variablen und interne Implementierungsvariablen zurück, sodass die Ausgabe nicht exakt diesen Tabellen entspricht. | Name | Typ | Beschreibung | | --------------- | ------ | --------------------------------------------------------------------------- | | $PSUEnvironment | string | Der Name der Umgebung, in der das Skript ausgeführt wird (z. B. Integrated) | | $Repository | string | Der absolute Pfad zum Repository-Ordner. | ### API Es gibt eine Reihe vordefinierter Variablen, die in API-Endpunkten verfügbar sind. Sie können diese Variablen in Ihren Skripten verwenden. | Variable | Beschreibung | Typ | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | $Url | URL, die der Client zum Aufrufen des Endpunkts verwendet hat | String | | $Method | Die HTTP-Methode, die zum Aufrufen des Endpunkts verwendet wurde | String | | $Headers | Vom Client zum Aufrufen des Endpunkts bereitgestellte Header | Hashtable | | $Body | Die UTF8-codierte Zeichenfolge des Inhalts der Anfrage | String | | $Data | Binäres Byte-Array für den Inhalt der Anfrage | Byte\[] | | $RemoteIpAddress | Die Remote-IP-Adresse des Clients, der die Anfrage stellt | String | | $LocalIpAddress | Die Remote-IP-Adresse des Dienstes, der die Anfrage verarbeitet | String | | $RemotePort | Der Remote-Port, der zum Stellen der Anfrage aufgerufen wurde | Integer | | $LocalPort | Der lokale Port, der zur Bearbeitung der Anfrage verwendet wurde | Integer | | $Identity | Der Identitätsname des Prinzipals, der auf die API zugreift. | String | | $UrlDefinition | Die Definition für die URL. | String | | $ConnectionId | Die [HTTP-Kontext-Verbindungs-ID](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.connectioninfo.id?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.ConnectionInfo.Id). | String | | $SessionId | Die [HTTP-Context-Sitzungs-ID.](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.isession.id?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.ISession.Id) | String | | $RequestId | Die [HTTP-Context-Anfrage-ID](https://docs.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.httpcontext.traceidentifier?view=aspnetcore-6.0#Microsoft.AspNetCore.Http.HttpContext.TraceIdentifier) | String | | $ClaimsPrincipal | Der Claims Principal des aktuellen Benutzers. Dies ist dasselbe Objekt, das rollenbasierten Zugriffsrichtlinien bereitgestellt wird. | ClaimPrincipal | ### Apps Nachfolgend finden Sie Variablen, die in Apps zusätzlich zu den globalen Variablen verfügbar sind. | Name | Beschreibung | Typ | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------- | | $User | Der Benutzername des angemeldeten Benutzers. $Null, wenn die Authentifizierung deaktiviert ist. | String | | $Roles | Die Rollen, die dem Benutzer zugewiesen wurden. $Null, wenn die Authentifizierung deaktiviert ist. | String\[] | | $RemoteIpAddress | Die Remote-IP-Adresse des verbundenen Benutzers. | String | | $RemotePort | Der Remote-Port des verbundenen Benutzers. | Int | | $ClaimsPrincipal | Der Claims Principal des aktuellen Benutzers. Dies ist dasselbe Objekt, das rollenbasierten Zugriffsrichtlinien bereitgestellt wird. | ClaimPrincipal | | $Headers | Die vom Browser bereitgestellten Header. | hashtable | | $Cookies | Die vom Browser bereitgestellten Anfrage-Cookies. | hashtable | | $PSUAppToken | Das App-Token des aktuellen Benutzers. Nur verfügbar, wenn -GrantAppToken aktiviert ist. | string | | $PSUURL | Die URL des PSU-Servers. Nur verfügbar, wenn -GrantAppToken aktiviert ist. | string | | $DashboardName | Der Name der aktuellen App | string | | $Query | Die Query-String-Parameter aus der URL der App | Hashtable | | $RefreshToken | Das Refresh-Token bei Verwendung von OpenID Connect | string | | $AccessToken | Das App-Token bei Verwendung von OpenID Connect | string | | $UDPage | Der Name der aktuellen Seite | string | ### Skripte Es gibt mehrere integrierte Variablen, die definiert werden, wenn ein Job ausgeführt wird. Sie können diese Variablen in Ihren Skripten verwenden, um Informationen über den aktuellen Job abzurufen. | Name | Beschreibung | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | $UAJob | Der aktuell ausgeführte Job. Dieser enthält Eigenschaften wie das Skript, den Benutzer, der den Job gestartet hat, und den Zeitpunkt, zu dem der Job gestartet wurde. | | $UAJobId | Die ID des laufenden Jobs. | | $UAScript | Das Skript, das ausgeführt wird. Dies enthält Eigenschaften wie den Namen des Skripts und den Pfad zum Skript. | | $UAScriptId | Die ID des laufenden Skripts. | | $UASchedule | Der Zeitplan, der zum Starten des Skripts verwendet wurde. | | $UAScheduleId | Die ID des Zeitplans, der das Skript gestartet hat. | | $AccessToken | Bei Verwendung der OIDC-Authentifizierung können Sie das Access-Token des aktuellen Benutzers abrufen, um in dessen Namen auf Ressourcen zuzugreifen. | | $Roles | Die Rollen des Aufrufers des Skripts. | #### Struktur des $UAJob-Objekts Beachten Sie, dass Eigenschaften null sein können. `DateTime`-Objekte werden in der UTC-Zeitzone zurückgegeben. {% code collapsedlinecount="10" %} ```csharp class Job { public long Id { get; set; } public DateTime CreatedTime { get; set; } public DateTime StartTime { get; set; } public DateTime EndTime { get; set; } public JobStatus Status { get; set; } public string Output { get; set; } public string ScriptFullPath { get; set; } public Identity Identity { get; set; } public Job ParentJob { get; set; } public int ParentLineNumber { get; set; } public string ComputerName { get; set; } public int ProcessId { get; set; } public long MemoryBytes { get; set; } public int RunspaceId { get; set; } public string Activity { get; set; } public string CurrentOperation { get; set; } public int PercentComplete { get; set; } public int SecondsRemaining { get; set; } public string StatusDescription { get; set; } public string Environment { get; set; } public Computer Computer { get; set; } public ActionPreference ErrorAction { get; set; } public IEnumerable Children { get; set; } public IEnumerable Parameters { get; set; } public string Credential { get; set; } public long ScheduleId { get; set; } public bool Triggered { get; set; } public string Trigger { get; set; } public int RetryCount { get; set; } public string Tags { get; set; } public string Schedule { get; set; } public bool Archived { get; set; } public bool Batch { get; set; } public Guid? RunId { get; set; } public string Roles { get; set; } } public enum JobStatus { Queued, Running, Completed, Failed, WaitingOnFeedback, Canceled, Canceling, Historical, Active, TimedOut, Warning, Error } ``` {% endcode %} #### Abrufen des Benutzers, der ein Skript gestartet hat Sie können den Namen des Benutzers, der ein Skript gestartet hat, mithilfe der Variable `UAJob` abrufen {% code collapsedlinecount="10" %} ``` $UAJob.Identity.Name ``` {% endcode %} #### Prüfen, ob ein Job manuell ausgeführt wurde Sie können mithilfe der Eigenschaften Schedule und Trigger prüfen, ob ein Job manuell ausgeführt wurde. {% code collapsedlinecount="10" %} ```powershell $Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null ``` {% endcode %} ## Präferenzvariablen Präferenzvariablen können für ein Skript, während der Ausführung eines Jobs und auf globaler Ebene konfiguriert werden. Dazu gehören: * DebugPreference * ErrorActionPreference * InformationPreference * ProgressPreference * VerbosePreference * WarningPreference Die Präferenzvariablen haben eine Vorrangfolge. Die folgende Liste ist nach Vorrang geordnet. Wenn ein Skript beispielsweise die Variable `$DebugPreference` manuell setzt, überschreibt dies den in den Eigenschaften des Skripts festgelegten Wert. * Skript * Ausführungsdialog oder Invoke-PSUScript * Skripteigenschaften * Globale Einstellungen ## API * New-PSUVariable * Get-PSUVariable * Remove-PSUVariable * Set-PSUVariable ### Siehe auch * [Devolutions Academy – Hinzufügen der Benutzerentsperrfunktion](https://academy.devolutions.net/student/activity/3546024-part-4-adding-user-unlock-feature) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/de/plattform/variables.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.