> 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 Variablen ermöglichen die globale Definition von Variablen, die innerhalb von Skripten verfügbar sind. Sie können auch Secrets importieren, die ebenfalls innerhalb von Skripten oder als Run-as-Anmeldeinformationen verfügbar sind. {% hint style="info" %} Variablen werden in der Konfigurationsdatei `variables.ps1` gespeichert. {% endhint %} ## Erstellen einer Variable Um eine Variable zu erstellen, navigieren Sie zur Seite Platform \ Variables. Klicken Sie auf Create Variable, um eine neue Variable zu definieren.

Dialog Create Variable

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. In diesem Dialog können Sie Zeichenfolgen und PSCredentials im angegebenen Tresor definieren.

Dialog Secret Variable

### Format der Anmeldeinformationen In einigen 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 unter diesem Benutzerkonto zu starten. ### Group Managed Service Accounts Bei der 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 [dem Leitfaden 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 Management und wählen Sie die Option Password Not Required. Geben Sie das GSMA-Konto ein (z. B. domain\user$). Solange das hostende Konto die erforderlichen Berechtigungen besitzt, können Sie Jobs unter dem 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" %} Wenn Sie Rollen auf ein Secret anwenden, verhindert dies, 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 beschränken, wer das Secret in seinen Skripten und als Run-as-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 folgende gehören: * Geplante Jobs * Nicht authentifizierte APIs oder Apps * Terminals ## Tresore ### Datenbank Der Datenbank-Tresor speichert Secrets innerhalb der PowerShell Universal-Datenbank. Diese Secrets werden mit AES-Verschlüsselung unter Verwendung eines anpassbaren Schlüssels 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. ```json "Secrets": { "Database": { "EncryptionKey": "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" } } ``` #### Umgebungsvariable Sie können diese Einstellung mit einer Umgebungsvariable konfigurieren. ```powershell $Env:Secrets__Database__EncryptionKey = "=b0ywQA@VOSdr&R7an5g&XK6NVO%s4Tf" ``` ### 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 Credential Manager-Instanz des Sicherheitsprinzipals gespeichert, der PSU ausführt. Zum Beispiel im 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 `PSUSecretStore`-Tresor 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" %} Erwägen Sie die Verwendung von [prozessexterner Secret Management](/powershell-universal/de/config/settings.md#Secrets), wenn Sie den `Az.KeyVault`-Tresor verwenden, um Assembly-Konflikte mit PowerShell Universal selbst zu vermeiden. {% endhint %} Standardmäßig ist die Azure Key Vault-Erweiterung nicht direkt in PowerShell Universal enthalten. Ein Container mit den erforderlichen Az.Accounts- und Az.KeyVault-Modulen ist verfügbar, damit Sie KeyVault sofort verwenden können. Dieser ist auf [Docker Hub](https://hub.docker.com/r/devolutions/powershell-universal) zu finden. Nachfolgend finden Sie die Konfigurationsanleitung. 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 zwingend erforderlich, wenn Sie außerhalb von Azure arbeiten. Sie können die verwaltete Identität auf der Seite Identity Ihrer Web-App aktivieren. ![](/files/d3W27QQxpo4hA98Ec7de) Als Nächstes müssen Sie Ihrer verwalteten Identität den Zugriff auf Ihren Key Vault und das Lesen Ihres Abonnements erlauben. Sie können die verwaltete Identität zur integrierten Reader-Gruppe hinzufügen, um Zugriff auf das Abonnement zu ermöglichen. ![](/files/DrLt60Uutsro4EEu6T6L) Anschließend habe ich meiner verwalteten Identität in meiner Key Vault-Ressource alle Berechtigungen für die Secret- und Schlüsselverwaltung erteilt. ![](/files/LDtTvEcw4dum1UjMzh6s) 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. ![](/files/IPG40je1awcapZn0cdOf) 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. ```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 ``` Wenn Sie nun Secrets erstellen, sehen Sie den verfügbaren AzureKeyVault.

Tresor-Auswahl für geheime Variablen

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. ```powershell $pwsh = (Get-Command pwsh).Path & $pwsh -File "$PSScriptRoot\registerVault.ps1" ``` 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 beim Systemstart ausgeführt, bevor andere Konfigurationsskripte ausgeführt werden. ### vaults.ps1 Die Datei `vaults.ps1` enthält Befehle zur Tresor-Registrierung. Während das obige Beispiel eine Registrierung eines Azure KeyVault-Secret-Tresors definiert, können Sie in dieser Datei tatsächlich jede benötigte Tresor-Registrierung aufnehmen. Sie können Tresore bearbeiten, indem Sie auf Platform \ Variables \ 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. ## Verwendung 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 eigene Umgebungen verwenden, müssen Sie konfigurieren, [welche Variablen einbezogen werden sollen](https://docs.powershelluniversal.com/config/environments#variables). Sie können auf eine Variable wie auf jede andere PowerShell-Variable verweisen. Die Variable enthält den von Ihnen festgelegten Wert. Wenn Sie ein Secret verwenden, enthält sie den Wert des Secrets. ``` $MyVariable ``` 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 [Umgebungen](/powershell-universal/de/config/environments.md#variables). ## Secret-Scope Um auf Secrets zuzugreifen, die Sie zu PowerShell Universal hinzugefügt haben, können Sie den Scope `$Secret` verwenden. Wenn Sie beispielsweise ein Secret mit dem Namen `Credential` definiert haben, können Sie überall mit dem Secret-Scope auf dieses Secret zugreifen. Sie können Secrets nicht über den Secret-Scope festlegen. ```powershell Invoke-Command -Credential $Secret:Credential { Write-Host "Hello" } ``` ### Zugriff auf Variablen über den Namen Sie können mit dem Präfix `$Secret:` über den Namen auf Variablen zugreifen. ```powershell # PSCredential $Secret:MyNewSecret.UserName $Secret:MyNewSecret.Password # String $Secret:DashboardSecret ``` ### Dynamischer Zugriff auf Werte Sie können mit `Get-Item` dynamisch auf den Secret-Scope zugreifen. Der Secret-Scope ist als Provider implementiert. Dies ist hilfreich, wenn Sie keine statischen Variablennamen haben. ```powershell # PSCredential (Get-ChildItem "Secret:MyNewSecret").UserName (Get-ChildItem "Secret:MyNewSecret").Password # String (Get-ChildItem "Secret:DashboardSecret") ``` ### 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. ```powershell 1..5 | ForEach-Object -Parallel { $using:Secret:MySecret } ``` ## Konfigurieren des `PSUSecretStore`-Passworts Standardmäßig wird das Passwort des `PSUSecretStore`-Tresors in `appsettings.json` unter Secrets \ SecretStore \ Password gespeichert. ## Integrierte Variablen Die folgenden Variablen sind in allen Umgebungen innerhalb von PowerShell Universal verfügbar. | 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, die für die Anfrage verwendet wurde. | String | | $LocalIpAddress | Die lokale IP-Adresse, die zur Bearbeitung der Anfrage verwendet wurde. | 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-Kontext-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-Kontext-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 den rollenbasierten Zugriffsrichtlinien bereitgestellt wird. | [ClaimPrincipal](/powershell-universal/de/apps/role-based-access.md) | ### 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 gewährt 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 den rollenbasierten Zugriffsrichtlinien bereitgestellt wird. | [ClaimPrincipal](/powershell-universal/de/apps/role-based-access.md) | | $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 | | $PSUComputerName | 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 laufende Skript. Dieses 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. | #### $UAJob-Objektstruktur Beachten Sie, dass Eigenschaften null sein können. `DateTime`-Objekte werden in der UTC-Zeitzone zurückgegeben. ```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 } ``` #### Den Benutzer abrufen, der ein Skript gestartet hat Sie können den Namen des Benutzers, der das Skript gestartet hat, mithilfe der Variable `UAJob` abrufen ``` $UAJob.Identity.Name ``` #### 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. ```powershell $Manual = $UAJob.Schedule -eq $null -and $UAJob.Trigger -eq $null ``` ## 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 Rangfolge. Die folgende Liste ist nach Rangfolge sortiert. Wenn ein Skript beispielsweise die Variable `$DebugPreference` manuell setzt, überschreibt dies den im Eigenschaftsdialog des Skripts festgelegten Wert. * Skript * Ausführungsdialog oder Invoke-PSUScript * Skripteigenschaften * Globale Einstellungen ## API * [New-PSUVariable](/powershell-universal/de/powershell-befehle/new-psuvariable.md) * [Get-PSUVariable](/powershell-universal/de/powershell-befehle/get-psuvariable.md) * [Remove-PSUVariable](/powershell-universal/de/powershell-befehle/remove-psuvariable.md) * [Set-PSUVariable](/powershell-universal/de/powershell-befehle/set-psuvariable.md) --- # 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.