Dela via

UpdateOrchestrator API

  • Artikel

UpdateOrchestrator schemalägger dina automatiska programuppdateringar med användarpåverkan i åtanke. Med det här API:et kan du ange åtgärder, till exempel nedladdning eller installation, tillsammans med deras krav för att köra uppdateringar vid en optimal tidpunkt som minimerar påverkan från användaren. Dessa funktioner gynnar särskilt system med lägre prestanda med begränsade eller långsammare beräkningsresurser.

Windows 20H1 innehåller en första generationens lösning för användningsfall för automatisk programuppdatering som har antagits av OS-uppdateringar och Store App-uppdateringar och exponerar en första version av det här API:et för en utvald uppsättning uppdateringsprogram för appar i användarläge enligt beskrivningen nedan.

Funktioner

  • Registrerar uppdaterare dynamiskt

  • Anropar registrerade programuppdateringsprogram under optimala tider, till exempel under användarfrånvaro, för att uppdatera "användarlägesappar".

  • Inkluderar möjligheten att "hålla sig vaken" vid nätström för att ytterligare minska påverkan av att användaren är borta.

Målgrupp för utvecklare

Viktig

API:et UpdateOrchestrator är en del av en funktion för begränsad åtkomst (se klassen LimitedAccessFeatures). För mer information eller om du vill begära en upplåsningstoken, använd LAF Access Token Request Form.

Använd UpdateOrchestrator API om du redan har bakgrundsprogramuppdateringar för Win32-program i användarläge, till exempel Adobes uppdateringsprogram för Acrobat Reader eller Valves Steam. Det här gränssnittet behövs inte för UWP/Store-program eftersom Microsoft Store redan använder den här funktionen för programuppdateringar.

För att ge den bästa kundupplevelsen begränsas den här första API-versionen till en utvald uppsättning registrerade uppdateringsprogram som uppfyller följande kriterier:

  • Uppdateringar endast för "användarläge"-program
  • Ta inte med BIOS/inbyggd programvara/enhets- eller programvarudrivrutiner
    • Att uppdatera BIOS, inbyggd programvara eller enhets-/programvarudrivrutiner som inte har klarat ett gemensamt kvalitetskriterier utgör en betydande risk, särskilt när en användare inte är närvarande.
  • Att delta i användningen av detta API innebär att du kan ansvara för allt innehåll som laddas ned och installeras av dina uppdateringsprogram på användarsystem genom granskningar.

Den första versionen av UpdateOrchestrator API som funktion för begränsad åtkomst är endast för updaters som uppfyller ovanstående kriterier just nu.

Vårt mål är att förbättra funktionerna i det här API:et och minska påverkan från flera automatiska programuppdateringsprogram i Windows. Vi skulle uppskatta dina indata genom den här korta undersökningen för att hjälpa oss att förstå hur UpdateOrchestrator API bättre kan tillgodose dina utvecklarbehov.

Påskynda OEM-appar via Universal Orchestrator Framework

Viktig

Universal Orchestrator tillhandahåller funktioner till OEM-tillverkare för att registrera ett program under avbildningsprocessen för att utföra en snabb installation/uppdatering en gång. Den här installationen sker inom 30 minuter efter att en användare har loggat in på en ny enhet. Tänk på att påskyndande av ett program kan ha en negativ prestandapåverkan på den färdiga upplevelsen för nya enheter. Den här funktionen är endast tillgänglig i Windows-versioner som kör den kumulativa icke-säkerhetsrelaterade förhandsuppdateringen av november 2024.

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

Krav

För att ansluta till det snabba appramverket måste appen uppfylla följande krav:

  • Det måste vara en Store-paketerad app i MSIX-format
  • Det måste ha ett giltigt produktfamiljenamn (PFN)

Registrering

Registreringsfiler är ASCII JSON-filer som innehåller metadata med information om det efterfrågade snabba flödet, samt eventuell riktad anpassning på klientsidan som behöver utföras.

Påskyndade appar stöder två mekanismer för att uppdatera/hämta en app:

  1. Direkt från Microsoft Store med ett ProductId-(rekommenderas)
  2. Från en URL som innehåller ett MSIX-paket eller paketbunt. Det här paketet måste innehålla en Store-paketerad app med ett giltigt paketfamiljenamn (PFN). OEM- eller appägaren ansvarar för att underhålla den här URL:en.

Varje registreringsfil måste innehålla följande obligatoriska JSON-egenskaper:

Nyckel Typ Beskrivning
PFN Sträng Appens paketfamiljenamn (till ex: Microsoft.WindowsStore_8wekyb3d8bbwe)
OEMName Sträng Sträng som representerar OEM-tillverkaren som skapar den här registreringen
UpdaterName Sträng Unikt namn för att spåra den här påskyndade registreringen
Registreringsversion Nummer Versionen av den här appregistreringen
Källa Sträng Tillåtna värden:
Butik | CustomURL

Store – söker efter appen direkt från Microsoft Store

CustomURL – söker efter appen från en URL som anges i appregistreringens slutpunktsvärde
Scenario Sträng Tillåtna värden:
Uppdatera | Förvärv | StubAcquisition

Update – (stöds inte för CustomURL-flöden) försöker uppdatera en befintlig app till den senaste tillgängliga versionen. Inget arbete görs om appen inte finns

Förvärv – försöker hämta den senaste versionen av en app.

StubAcquisition – försöker skaffa en "stub" av appen (om den är tillgänglig). Hämtar den fullständiga appen om stub inte är tillgänglig.
ProduktId Sträng (Krävs endast för Store-scenarier)

ProductId för önskad Store-app
Slutpunkt Sträng (Krävs endast för CustomURL-scenarier)

En sträng-URI som pekar på en plats som är värd för ett MSIX-paket. Måste vara en SSL-URI som börjar med "https".

Dessutom kan följande valfria egenskaper anges för att ändra beteendet för den påskyndade appinstallationen eller för att rikta det påskyndade flödet så att det endast sker under vissa förhållanden.
Nyckel Typ Standard Beskrivning
AllowedInOobe Boolesk Falsk Om den här snabba appen ska köras under användarens första startupplevelse.

Obs! Var försiktig när du ställer in detta på sant, eftersom detta kan skapa resursbegränsningar på en enhet under out of box-flödet och påverka användarnas upplevda prestanda negativt.
MaxRetryCount Nummer 1 Antalet gånger som den här uppdateraren tillåts försöka igen efter ett fel.

Högsta tillåtna värde är: 5
TimeoutDurationInMinutes Nummer 15 Varaktigheten i minuter för att vänta tills den här uppdateraren slutför arbetet.

Högsta tillåtna värde är: 30
Arkitektur Sträng Ingen begränsning Tillåtna värden:
"amd64" | "arm64".

Anger om det påskyndade arbetet endast ska utföras för en specifik arkitektur.
LägstaTillåtnaByggversion Nummer Ingen begränsning Lägsta Windows-versionsversioner där det påskyndade arbetet tillåts.

Ex. Om detta är inställt på 22631 tillåts påskyndat arbete för Windows 11 23H2 (10.0.22631.x), men blockeras för Windows 11 22H2 (10.0.22621.x)
HonorDeprovisioning Boolesk Falsk (Gäller endast för förvärvsscenarier)

Om appen tidigare har avaktiverats bör du inte försöka hämta den igen.
Hoppa över om närvarande Boolesk Falsk (Gäller endast för förvärvsscenarier)

Utför inte det påskyndade arbetet om någon version av appen redan finns.
Prioritering Nummer 100 Ett numeriskt värde mellan 1 och 100 för att ange relativ prioritet för den här programuppdateringen.

Lägre värden anger en högre relativ prioritet för andra snabbare appar.
Exkluderade regioner Array (sträng) Inga begränsningar En JSON-matris med strängar för regioner där den här appen INTE ska påskyndas.
Varje post i matrisen motsvarar landskoden iso 3166-1 med två bokstäver i önskad region.

Ex: ["US", "MX"] skulle förhindra det här flödet på enheter där regionen är USA eller Mexiko.

Obs! Det här värdet kan inte användas tillsammans med IncludedRegions.
InkluderadeRegioner Array (Sträng) Inga begränsningar En JSON-matris med strängar som anger en lista över tillåtna regioner där den här appen ska påskyndas.
Varje post i matrisen motsvarar landskoden iso 3166-1 med två bokstäver i önskad region.

T.ex. skulle ["US", "MX"] endast tillåta detta flöde på enheter där regionen är USA eller Mexiko.

Obs! Det här värdet kan inte användas tillsammans med ExcludedRegions.
Inkluderade Utgåvor Matris (tal) Inga begränsningar En JSON-matris med tal som anger en lista över tillåtna utgåvor där den här appen ska påskyndas.
Varje post i matrisen motsvarar versionskoden som hämtas av GetProductInfo API.

Ex: [121, 122] att endast inkludera Education- och EducationN-utgåvor

Obs! Det här värdet kan inte användas tillsammans med ExcludedEditions.
Uteslutna Utgåvor Matris (tal) Inga begränsningar En JSON-matris med tal för utgåvor där den här appen INTE ska påskyndas.
Varje post i matrisen motsvarar versionskoden som hämtas av GetProductInfo API.

Ex: [121, 122] för att exkludera Education- och EducationN-utgåvor.

Obs! Det här värdet kan inte användas tillsammans med IncludedEditions.

Prover

Butiksbaserat stub-förvärv, endast i USA och Mexiko, för att utföras under OOBE

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

URL-baserade applikationsförvärv på amd64-enheter, exklusive utgåvorna Education och EducationN, endast på 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 
    }

Arbetsredskap

För att underlätta registreringsprocessen och ge användbar feedback om registreringsmetadata måste OEM-tillverkare använda AppOrchestration powershell-skript från följande plats:
microsoft/ms-update-universalorchestrator: Skript och verktyg för att ansluta sig till Universal Orchestrator-baserade uppdateringsflöden

Skripten utför grundläggande validering och förbereder registreringen på rätt plats på enheten. Vid eventuella fel utlöser skripten ett undantag med den specifika felinformationen.

Så här använder du skripten:

  1. Ladda ned skripten till enheten. Från GitHub-lagringsplatsen kan du välja att ladda ned som en ZIP-fil och extrahera till enheten
  2. I ett PowerShell-fönster kör du "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1"

Obs! Dessa skript kräver att användaren har administratörsbehörighet på enheten och måste köras från en upphöjd konsol.

Det finns 4 huvudsakliga cmdletar som används för registreringsflödet

Test-UpdaterRegistration <SökvägTillRegistreringsfil>
Syfte: Verifiera innehållet i en föreslagen registreringsfil (utan att utföra registreringen). Gör att OEM kan iterera på registreringsfilens nyttolast utan att påverka enheten

Add-UpdaterRegistration <PathToRegistrationFile>
Syfte: Verifiera och mellanlagra innehållet i en registreringsfil till lämplig plats för att integrera det i det påskyndade appflödet

Get-UpdaterRegistration <OEMName><UpdaterName>
Syfte: Om OEMName och UpdaterName tillhandahålls returnerar en sammanfattning av en befintlig registrering som matchar dessa värden. Om dessa indata utelämnas returnerar en sammanfattning av alla aktuella registreringar som finns på enheten.

Remove-UpdaterRegistration <OEMName><UpdaterName<
Syfte: Avtagar alla registreringar som matchar värdena OEMName och UpdaterName.

Avrättning

Universal Orchestrator-ramverket anropar automatiskt var och en av de registrerade apparna, i sekvens baserat på relativ prioritet, inom de första 30 minuterna efter att en användare når skrivbordet på en ny enhet (eller under Användar-OOBE om AllowedInOobe är inställt på true). Varje registrerat program som läggs till av OEM-registreringsprocessen kommer att försökas tills antingen:

  • Det har installerats framgångsrikt
  • Den överskrider den maximala mängden fel som anges i MaxRetryCount. Efter varje fel går appen in i en nedkylningsperiod på 30 minuter innan den försöker igen.

Universal Orchestrator-ramverket utför inte snabba försök om något av följande villkor är sant:

  • Enheten har inte internetåtkomst
  • Enheten är ansluten till ett nätverk med mätning
  • Enheten är på batteri och batterisparfunktionen är aktiverad
  • Enheten har konfigurerats med en princip för begränsad nätverkstrafik i Windows Update
  • Enheten har konfigurerats med en CTA-policy som inte har ställts in för AutoApprove.

    I vart och ett av dessa fall behåller Universal Orchestrator-ramverket registreringarna tills enhetskonfigurationen tillåter snabba försök att fortsätta.
    Om appregistreringen innehåller valfria värden som blockerar det påskyndade flödet (t.ex. på grund av versionstyp) kommer Universal Orchestrator-ramverket att överväga att den här registreringsbegäran är uppfylld och inte försöker igen, även om dessa villkor senare kan ändras på en enhet.

Viktig

Var försiktig när du väljer att påskynda appar via det här ramverket, eftersom uppdateringsåtgärderna sker när enheten kan användas och kan orsaka en negativ prestandapåverkan av användarupplevelsen på en ny enhet.