Agent-Cmdlets (PowerShell)

Für Administratoren. Stand September 2026 (Agent 1.0.36). Verwandte Anleitungen: Client-Agent: Betrieb, Rollout und Gruppenrichtlinien, Quick-Admin-Guide, Geräte ohne Domäne (API-Key), Bekannte Fehlerbilder.

1. Modul und Voraussetzungen

Das Modul ZeroPortalAgent wird mit dem Agenten installiert und lädt automatisch, sobald Sie eines der Cmdlets aufrufen; ein Import-Module ist nicht nötig. Es setzt Windows PowerShell 5.1 voraus, die auf jedem Windows enthalten ist.

Lesen (Get-…) geht mit normalen Benutzerrechten.
Schreiben (Set-…, Add-…, Enable-…, Disable-…) ändert computerweite Werte und braucht eine administrative PowerShell. Ausnahme: Set-ZPAgentDisplayName ohne -Scope Machine schreibt in das Benutzerprofil.
Gruppenrichtlinie gewinnt. Ist eine Einstellung per GPO gesetzt, wird der lokale Wert zwar geschrieben, bleibt aber wirkungslos. Get-ZPAgentSync und die Spalte SetByGroupPolicy von Get-ZPAgentConfiguration zeigen, woher der geltende Wert stammt.

2. Publishing-Server verwalten

Die lokale Serverliste. Eine per Gruppenrichtlinie verteilte Liste ersetzt sie vollständig.

Cmdlet	Parameter	Zweck
`Add-ZPAgentPublishingServer`	`-Name <Text>` (Pos. 0), `-Url <Text>` (Pos. 1)	Server anhängen. Die Reihenfolge ist die Priorität
`Get-ZPAgentPublishingServer`	—	Alle Server mit `ServerId`, `Name`, `BaseUrl`, `GlobalRefreshEnabled`, `UserRefreshEnabled`, `RequestTimeoutSec`
`Set-ZPAgentPublishingServer`	`-ServerId <Zahl>` (Pos. 0, Pflicht), `-Name`, `-Url`, `-GlobalRefreshEnabled <bool>`, `-UserRefreshEnabled <bool>`, `-RequestTimeoutSec <Zahl>`	Einen Eintrag ändern
`Remove-ZPAgentPublishingServer`	`-ServerId <Zahl>` oder `-Name <Text>`	Einträge löschen

Add-ZPAgentPublishingServer -Name 'ZeroPortal' -Url 'https://zeroportalserver:8888'
Get-ZPAgentPublishingServer
Set-ZPAgentPublishingServer -ServerId 1 -UserRefreshEnabled $false

3. Konfiguration lesen und schreiben

Die Einstellungen liegen in vier Bereichen: MSIX, AppV, Agent und Policy. Jede Einstellung ist ein eigener Parameter; die Bereichsschalter grenzen die Ausgabe ein.

Cmdlet	Parameter	Zweck
`Get-ZPAgentConfiguration`	`-MSIX`, `-AppV`, `-Agent`, `-Policy`, dazu je Einstellung ein Schalter	Geltende Werte als Liste: `Name`, `Value`, `SetByGroupPolicy`, `Area`
`Set-ZPAgentConfiguration`	je Einstellung ein typisierter Parameter, alternativ `-MSIX @{…}`, `-AppV @{…}`, `-Agent @{…}`, `-Policy @{…}`	Werte computerweit schreiben (HKLM)
`Set-ZPAgentDisplayName`	`-Name <Text>` (Pos. 0, Pflicht), `-Scope User\\|Machine`	Anzeigename im Portal. `User` (Standard) ohne Adminrechte, `Machine` benennt das Gerät

Get-ZPAgentConfiguration -Policy
Get-ZPAgentConfiguration -SyncIntervalMinutes
Set-ZPAgentConfiguration -SyncIntervalMinutes 30
Set-ZPAgentConfiguration -Agent @{ LogLevel = 'Debug'; SyncJitterMinutes = 5 }
Set-ZPAgentDisplayName -Name 'Kasse 3' -Scope Machine

Ein unbekannter Name bricht mit Fehler ab und listet die gültigen Namen. Die vollständige Liste der Einstellungen mit Standardwerten steht in Client-Agent: Betrieb, Rollout und Gruppenrichtlinien, Abschnitt 6.

4. Abgleich ein- und ausschalten

Nach der Installation sind alle drei Bereiche aus.

Cmdlet	Parameter	Zweck
`Enable-ZPAgentSync`	`-Msix`, `-AppV`, `-Policy`, `-All`	Bereiche einschalten
`Disable-ZPAgentSync`	`-Msix`, `-AppV`, `-Policy`, `-All`	Bereiche ausschalten
`Get-ZPAgentSync`	—	Je Bereich `Feature`, `Enabled` und `Source` (`GroupPolicy`, `Local`, `Default`)

Mindestens ein Schalter ist Pflicht; ohne Angabe bricht das Cmdlet ab. Überschreibt eine Gruppenrichtlinie den Bereich, weist eine Warnung darauf hin.

Enable-ZPAgentSync -Msix -Policy
Get-ZPAgentSync

Dasselbe erreichen Sie über die Einstellungen MSIXSyncEnabled, AppVSyncEnabled und PolicyProcessingEnabled:

Set-ZPAgentConfiguration -MSIXSyncEnabled $true
Set-ZPAgentConfiguration -PolicyProcessingEnabled $true

5. Abgleich auslösen und Status prüfen

Cmdlet	Parameter	Zweck
`Sync-ZPAgentPublishingServer` (Alias `Invoke-ZPAgentSync`)	`-Method All\\|Computer\\|User`, `-Machine` (Alias `-Global`)	Abgleich sofort starten
`Get-ZPAgentStatus`	—	`ModuleVersion`, `ServiceReachable`, `ServiceVersion`, `MachineSyncState`, `Servers`

Ohne -Method folgt das Cmdlet den Schaltern MachineSyncEnabled und UserSyncTaskEnabled, läuft also wie der geplante Abgleich. -Method Computer beauftragt den Dienst (keine Adminrechte nötig), -Method User läuft im aufrufenden Benutzerkontext. Für Automatisierung über WinRM immer -Method Computer verwenden: Eine Netzwerkanmeldung hat kein weiterreichbares Ticket, der Benutzerabgleich meldet sich sonst anonym am Portal.

Sync-ZPAgentPublishingServer -Method Computer
Get-ZPAgentStatus

6. Pakete ansehen

Cmdlet	Parameter	Zweck
`Get-ZPAgentPackage`	`-Machine`, `-User`	Vom Agenten verwaltete Pakete je Bereich, mit `FamilyName`, `Version`, `SourceServerUrl`, `PendingRemove`, `LastSeenUtc`
`Get-ZPAgentMountedPackage`	`-Family <Muster>` (Pos. 0)	App-Attach-Pakete: wo die Daten wirklich liegen, ob das Image eingehängt ist und ob Format und Einhängepunkt zusammenpassen (`Consistent`)

Get-ZPAgentPackage -Machine
Get-ZPAgentMountedPackage libre*

7. Wartung

Cmdlet	Parameter	Zweck
`Invoke-ZPAgentPendingRemoveSweep`	—	Aufgeschobene Entfernungen sofort abarbeiten lassen
`Clear-ZPAgentLog`	`-WhatIf`, `-Confirm`	Protokolldateien löschen: `%ProgramData%` (Adminrechte) und `%LocalAppData%` des aktuellen Benutzers. Die Datei des laufenden Tages bleibt gesperrt

8. Erstkonfiguration ohne Gruppenrichtlinie

Set-ZPAgentConfiguration -MSIXSyncEnabled $true
Set-ZPAgentConfiguration -PolicyProcessingEnabled $true
Add-ZPAgentPublishingServer -Name 'ZeroPortal' -Url 'https://zeroportalserver:8888'

Get-ZPAgentPublishingServer
Sync-ZPAgentPublishingServer -Method Computer
Get-ZPAgentStatus

App-V bleibt bewusst aus. Schalten Sie es nur ein, wenn der Microsoft-App-V-Client die Pakete nicht selbst vom Portal holt.