Freigeben über

UpdateOrchestrator-API

  • Artikel

UpdateOrchestrator plant Ihre automatischen Softwareupdates unter Berücksichtigung der Auswirkungen auf den Benutzer. Mit dieser API können Sie Aktionen (z. B. Herunterladen oder Installieren) sowie deren Anforderungen angeben, damit Updates zu einem optimalen Zeitpunkt ausgeführt werden, um die Benutzer*innen so wenig wie möglich zu beeinträchtigen. Diese Features profitieren insbesondere von geringeren Leistungssystemen mit begrenzten oder langsameren Computerressourcen.

Windows 20H1 enthält eine Lösung der ersten Generation für automatische Softwareupdate-Anwendungsfälle, die von Betriebssystemupdates und Store-App-Updates übernommen wurden, und stellt eine anfängliche Version des eingeschränkten Zugriffs dieser API für einen ausgewählten Satz von Updatern von "Benutzermodus"-Apps bereit, wie unten beschrieben.

Features

  • Registriert Softwareupdater dynamisch

  • Ruft registrierte Softwareupdater in optimalen Zeiten auf, z. B. während der Abwesenheit des Benutzers, um "Benutzermodus-Apps" zu aktualisieren.

  • Bietet die Möglichkeit, das System bei einem Netzanschluss aktiviert zu halten, um die Auswirkungen auf die Benutzer*innen noch weiter zu reduzieren.

Entwicklerpublikum

Wichtig

Die UpdateOrchestrator-API ist Teil eines Features für eingeschränkten Zugriff (siehe LimitedAccessFeatures-Klasse). Für weitere Informationen oder zur Anforderung eines Entsperrtokens verwenden Sie bitte das LAF-Zugriffstoken-Anforderungsformular.

Verwenden Sie die UpdateOrchestrator-API, wenn Sie bereits über Hintergrundaktualisierer für Win32-Anwendungen im Benutzermodus verfügen, wie Adobes Updater für Acrobat Reader oder Valves Plattform Steam. Diese Schnittstelle ist für UWP/Store-Anwendungen nicht erforderlich, da der Microsoft Store diese Funktionalität bereits für Softwareupdates nutzt.

Um die beste Kundenerfahrung zu bieten, ist diese anfängliche API-Version auf einen ausgewählten Satz registrierter Updater festgelegt, die die folgenden Kriterien erfüllen:

  • Nur Updates für "Benutzermodus"-Anwendungen
  • Keine BIOS-, Firmware-, Geräte- oder Softwaretreiber
    • Das Aktualisieren von BIOS-, Firmware- oder Geräte-/Softwaretreibern, die keine allgemeinen Qualitätskriterien bestanden haben, stellen ein erhebliches Risiko dar, insbesondere, wenn ein Benutzer nicht vorhanden ist.
  • Die Teilnahme an der Nutzung dieser API beinhaltet, dass alle Inhalte, die von Ihren Hintergrundsoftwareupdatern heruntergeladen und installiert werden, über Audits auf Benutzersystemen übertragen und installiert werden können.

Die erste Version der UpdateOrchestrator-API als Feature für eingeschränkten Zugriff ist nur für Updater vorgesehen, die zu diesem Zeitpunkt die oben genannten Kriterien erfüllen.

Unser Ziel ist es, die Funktionalität dieser API zu verbessern und die Auswirkungen von mehreren automatischen Softwareupdateern auf Windows zu verringern. Teilen Sie uns über diese kurze Umfrage Ihre Erfahrungen mit, damit wir verstehen können, wie die UpdateOrchestrator-API Ihre Entwickleranforderungen besser erfüllen kann.

Beschleunigung von OEM-Anwendungen über das Universal Orchestrator-Framework

Wichtig

Universal Orchestrator stellt OEMs die Möglichkeit zur Verfügung, während des Imageerstellungsprozesses eine Anwendung zu registrieren, um eine einmalige beschleunigte Installation oder Aktualisierung durchzuführen. Diese Installation erfolgt innerhalb von 30 Minuten, nachdem sich ein Benutzer bei einem neuen Gerät angemeldet hat. Beachten Sie, dass sich die Beschleunigung einer Anwendung bei neuen Geräten negativ auf die Leistung auswirken kann. Diese Funktionalität ist nur für Windows-Versionen verfügbar, die das kumulative nicht sicherheitsrelevante Vorschauupdate vom November 2024 ausführen.

Windows 11 23H2 - KB5046732 (OS Build 22631.4541)
Windows 11 24H2 – KB5046740 (Betriebssystembuild 26100.2454)

Anforderungen

Um in das Framework für beschleunigte Anwendungen aufgenommen zu werden, muss die Anwendung die folgenden Anforderungen erfüllen:

  • Es muss sich um eine im Store verpackte App im MSIX-Format handeln.
  • Er muss über einen gültigen Produktfamiliennamen (PFN) verfügen.

Registrierung

Registrierungsdateien sind ASCII-JSON-Dateien, die Metadaten mit Informationen zum gewünschten beschleunigten Ablauf sowie allen benutzerdefinierten clientseitigen Targeting-Vorgaben enthalten, die durchgeführt werden müssen.

Beschleunigte Apps unterstützen zwei Mechanismen zum Aktualisieren/Erwerben einer App:

  1. Direkt aus dem Microsoft Store mit einer ProductId (Empfohlen)
  2. Von einer URL, die ein MSIX-Paket oder -Bundle enthält. Dieses Paket muss eine im Store gepackte App mit einem gültigen Paketfamiliennamen (PFN) enthalten. Der OEM- oder App-Besitzer ist für die Aufrechterhaltung dieser URL verantwortlich.

Jede Registrierungsdatei muss die folgenden erforderlichen JSON-Eigenschaften enthalten:

Schlüssel type Beschreibung
PFN String Der Paketfamilienname der App (z. B. Microsoft.WindowsStore_8wekyb3d8bbwe)
OEMName String Zeichenfolge, die den OEM darstellt, der diese Registrierung erstellt
UpdaterName String Eindeutiger Name, um diese beschleunigte Registrierung zu verfolgen
RegistrationVersion Anzahl Die Version dieser App-Registrierung
Quelle String Zulässige Werte:
Speichern | BenutzerdefinierteURL

Store – sucht direkt nach der App im Microsoft Store.

CustomURL – sucht nach der App über eine URL, die im „Endpoint“-Wert der App-Registrierung angegeben ist
Szenario String Zulässige Werte:
Aktualisieren | Erwerb | StubAcquisition

Update – (Für CustomURL-Flüsse nicht unterstützt) versucht, eine vorhandene App auf die neueste verfügbare Version zu aktualisieren. Es wird keine Arbeit ausgeführt, wenn die App nicht vorhanden ist.

Erwerb – Der Versuch, die neueste Version einer App zu erhalten.

StubAcquisition – versucht, einen „Stub“ der App abzurufen (sofern verfügbar). Erhält die vollständige App, wenn der Stub nicht verfügbar ist.
ProductId String (Nur für Store-Szenarien erforderlich)

Die ProductId der gewünschten Store-App
Endpunkt String (Nur für CustomURL-Szenarien erforderlich)

Ein URI-String, der auf einen Ort verweist, an dem ein MSIX-Paket gehostet wird. Muss ein SSL-URI sein, der mit „https“ beginnt.

Darüber hinaus können die folgenden optionalen Eigenschaften angegeben werden, um das Verhalten der beschleunigten App-Installation zu ändern oder den beschleunigten Prozess nur bei bestimmten Bedingungen eintreten zu lassen.
Schlüssel type Standard Beschreibung
AllowedInOobe Boolean False Ob diese beschleunigte App während der Benutzer-OOBE ausgeführt werden soll.

Hinweis: Verwenden Sie Vorsicht, wenn Sie dies auf "true" festlegen, da dadurch Ressourceneinschränkungen auf einem Gerät während des Out of Box Experience-Flusses entstehen können und sich negativ auf die vom Benutzer wahrgenommene Leistung auswirken.
MaxRetryCount Anzahl 1 Die Anzahl der Versuche, die der Updater nach einem Fehler wiederholen darf.

Maximal zulässiger Wert ist: 5
TimeoutDurationInMinutes Anzahl 15 Die Wartezeit in Minuten, bis dieser Updater seine Arbeit abgeschlossen hat.

Maximal zulässiger Wert: 30
Architektur String Keine Einschränkung Zulässige Werte:
"amd64" | "arm64".

Gibt an, ob die beschleunigte Arbeit nur für eine bestimmte Architektur erfolgen soll.
MinimumAllowedBuildVersion Anzahl Keine Einschränkung Mindestversionen von Windows-Builds, bei denen die beschleunigte Arbeit zulässig ist.

Ex. Wenn dies auf 22631 festgelegt ist, ist beschleunigte Arbeit für Windows 11 23H2 (10.0.22631.x) zulässig, jedoch für Windows 11 22H2 (10.0.22621.x) blockiert.
HonorDeprovisioning Boolean Falsch (Gilt nur für Kaufszenarien)

Wenn die Bereitstellung der App zuvor aufgehoben wurde, versuchen Sie nicht erneut, sie abzurufen.
SkipIfPresent Boolean Falsch (Gilt nur für Kaufszenarien)

Führen Sie die beschleunigte Arbeit nicht aus, wenn bereits eine Version der App vorhanden ist.
Priorität Anzahl 100 Ein numerischer Wert zwischen 1 und 100, der die relative Priorität dieses Anwendungsupdates angibt.

Niedrigere Werte geben eine höhere relative Priorität für andere beschleunigte Apps an.
Ausgeschlossene Regionen Array (String) Keine Einschränkungen Ein JSON-Array mit Zeichenfolgen für Regionen, in denen diese App NICHT beschleunigt werden soll.
Jeder Eintrag im Array entspricht dem 2 Buchstaben ISO 3166-1 Ländercode der gewünschten Region.

Beispiel: ["US", "MX"] würde diesen Fluss auf Geräten verhindern, auf denen die Region USA oder Mexiko ist.

Hinweis: Dieser Wert kann nicht in Verbindung mit IncludedRegions verwendet werden.
IncludedRegions Array (String) Keine Einschränkungen Ein JSON-Array von Zeichenfolgen, die eine Zulassungsliste von Regionen angeben, in denen diese App beschleunigt werden soll.
Jeder Eintrag im Array entspricht dem 2 Buchstaben ISO 3166-1 Ländercode der gewünschten Region.

Beispiel: ["US", "MX"] würde diesen Fluss nur auf Geräten zulassen, auf denen die Region USA oder Mexiko ist.

Hinweis: Dieser Wert kann nicht in Verbindung mit "Ausgeschlossene Regionen" verwendet werden.
IncludedEditions Array (Zahl) Keine Einschränkungen Ein JSON-Array aus Zahlen, das eine Zulassungsliste von Editionen angibt, für die diese App beschleunigt werden soll.
Jeder Eintrag im Array entspricht dem vom abgerufenen EditionscodeGetProductInfo-API.

Ex: [121, 122] um nur die Editionen „Education“ und „EducationN“ einzuschließen

Hinweis: Dieser Wert kann nicht in Verbindung mit ExcludedEditions verwendet werden.
ExcludedEditions Array (Zahl) Keine Einschränkungen Ein JSON-Array mit Zahlen für Editionen, bei denen diese App NICHT beschleunigt werden sollte.
Jeder Eintrag im Array entspricht dem vom abgerufenen EditionscodeGetProductInfo-API.

Ex: [121, 122] um Education und EducationN Editions auszuschließen.

Hinweis: Dieser Wert kann nicht in Verbindung mit IncludedEditions verwendet werden.

Beispiele

Filialbasierte Stub-Akquisition, nur in den USA und Mexiko, zur Ausführung während der OOBE

    {  
        "RegistrationVersion":1,  
        "Source": "Store",  
        "Scenario": "StubAcquisition",  
        "PFN": "FakePackageFamilyName",  
        "ProductId": "StoreProductId",  
        "HonorDeprovisioning": true,  
        "AllowedInOobe": true,  
        "IncludedRegions": ["US", "MX"],  
        "Priority": 50  
    }

URL-basierte App-Erfassung auf amd64-Geräten, ausgenommen Education- und EducationN-Editionen, nur unter Windows 11 23H2 (not Windows 11 22H2) 

    {  
        "RegistrationVersion":2,  
        "Source": "CustomURL",  
        "Scenario": "Acquisition",  
        "PFN": "FakePackageFamilyName",  
        "Endpoint": "https://<SSL_URI>",   
        "ExcludedEditions": [121, 122],   
        "Architecture": "amd64",   
        "MinimumAllowedBuildVersion": 22631,  
        "Priority": 60 
    }

Werkzeuge

Um den Registrierungsprozess zu erleichtern und umsetzbares Feedback zu den Registrierungsmetadaten zu geben, müssen OEMs das verwenden AppOrchestrierung Powershell-Skripte vom folgenden Speicherort:
microsoft/ms-update-universalorchestrator: Skripte und Tools für die Integration in Universal Orchestrator-basierte Update-Flows

Die Skripte führen eine grundlegende Validierung durch und stellen die Registrierung an der entsprechenden Stelle auf dem Gerät bereit. Bei Fehlern lösen die Skripts eine Ausnahme mit den spezifischen Fehlerdetails aus.

So verwenden Sie die Skripts:

  1. Laden Sie die Skripts auf Ihr Gerät herunter. Auf der GitHub-Repositoryseite können Sie auswählen, ob sie als ZIP-Datei heruntergeladen und auf Ihr Gerät extrahiert werden sollen.
  2. Führen Sie in einem PowerShell-Fenster "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1" aus.

Hinweis: Diese Skripts erfordern, dass der Benutzer über Administratorrechte auf dem Gerät verfügt und von einer Konsole mit erhöhten Rechten ausgeführt werden muss.

Es gibt vier Haupt-Cmdlets, die für den Registrierungsablauf verwendet werden.

Test-UpdaterRegistration <PathToRegistrationFile>
Zweck: Überprüfen des Inhalts einer vorgeschlagenen Registrierungsdatei (ohne Registrierung). Ermöglicht dem OEM, die Nutzlast der Registrierungsdatei zu iterieren, ohne das Gerät zu beeinträchtigen

Add-UpdaterRegistration <PathToRegistrationFile>
Zweck: Validieren und Bereitstellen des Inhalts einer Registrierungsdatei an der entsprechenden Stelle, um sie in den beschleunigten App-Flow einzubinden

Get-UpdaterRegistration <OEMName><UpdaterName>
Zweck: Wenn OEMName und UpdaterName angegeben werden, wird eine Zusammenfassung einer vorhandenen Registrierung zurückgegeben, die diesen Werten entspricht. Wenn diese Eingaben nicht angegeben werden, wird eine Zusammenfassung aller aktuellen Registrierungen zurückgegeben, die auf dem Gerät vorhanden sind.

Remove-UpdaterRegistration <OEMName><UpdaterName<
Zweck: Entfernt die Bereitstellung aller Registrierungen, die mit den Werten OEMName und UpdaterName übereinstimmen.

Ausführung

Das Universal Orchestrator-Framework ruft automatisch jede der registrierten Anwendungen in einer auf relativer Priorität basierenden Reihenfolge innerhalb der ersten 30 Minuten auf, wenn ein Benutzer den Desktop auf einem neuen Gerät erreicht (oder während der Benutzer-OOBE, wenn AllowedInOobe auf true gesetzt ist). Jede registrierte Anwendung, die durch den OEM-Registrierungsprozess hinzugefügt wird, wird so lange versucht, bis entweder:

  • Es wurde erfolgreich installiert.
  • Er überschreitet die maximale Anzahl von Fehlern, die in MaxRetryCount angegeben sind. Nach jedem Fehler wechselt die App in einen Cooldownzeitraum von 30 Minuten, bevor sie erneut versucht wird.

Das Universal Orchestrator-Framework führt keine beschleunigten Versuche aus, wenn eine der folgenden Bedingungen zutrifft:

  • Das Gerät hat keinen Internetzugang
  • Gerät befindet sich in einem gebührenpflichtigen Netz
  • Das Gerät befindet sich im Akku, und der Stromsparmodus ist aktiviert.
  • Gerät ist mit a konfiguriert Windows Update-Richtlinie für eingeschränkten Netzwerkverkehr
  • Gerät ist mit a konfiguriertCTA-Richtlinie das nicht für AutoApprove eingestellt ist

    In jedem dieser Fälle behält das Universal Orchestrator-Framework die Registrierungen bei, bis die Gerätekonfiguration beschleunigte Versuche ermöglicht, den Vorgang fortzusetzen.
    Wenn die App-Registrierung optionale Werte enthält, die den beschleunigten Fluss blockieren (z. B. aufgrund des Editionstyps), berücksichtigt das Universal Orchestrator-Framework diese Registrierungsanforderung als erfüllt und versucht sie nicht erneut, auch wenn sich diese Bedingungen später auf einem Gerät ändern können.

Wichtig

Seien Sie vorsichtig, wenn Sie sich dafür entscheiden, Anwendungen über dieses Framework zu beschleunigen, da die Aktualisierungsvorgänge durchgeführt werden, während das Gerät in Gebrauch ist, und die Leistung des Benutzers auf einem neuen Gerät beeinträchtigen können.