Registrera ett OEM-program under avbildningsprocessen

Artikel
02/22/2025

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. Att påskynda 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äkerhetsuppdateringen förhandsversionen 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 önskad accelererad process och eventuell anpassad målinriktning på klientsidan som behöver utföras.

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

Från Microsoft Store med hjälp av ett produkt-ID (rekommenderas)
Från en URL som innehåller ett MSIX-paket eller -bunt. 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 (exempel: 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.
Produkt-ID	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 påskyndade appen ska köras under användar-OOBE. Obs! Var försiktig när du anger sant, eftersom detta kan skapa resursbegränsningar på en enhet under out of box-flödet och påverka användarnas upplevda prestanda negativt.
MaximaltAntalFörsök	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.
Minsta tillåtna byggversion	Nummer	Ingen begränsning	Lägsta Windows-versionsversioner där det påskyndade arbetet tillåts. Om det till exempel är inställt på 22631 tillåts snabbt 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 avinstallerades, ska du inte försöka att skaffa 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.
ExkluderadeRegioner	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 i den önskade regionen. Exempel: `["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 med IncludedRegions.
InkluderadeRegioner	Array (String)	Inga begränsningar	En JSON-matris med strängar som anger en lista över regioner där den här appen ska påskyndas. Varje post i matrisen motsvarar landskoden ISO 3166-1 i den önskade regionen. Exempel: `["US", "MX"]` endast tillåter det här flödet på enheter där regionen är USA eller Mexiko. Obs! Det här värdet kan inte användas med ExcludedRegions.
Inkluderade Utgåvor	Array (nummer)	Inga begränsningar	En JSON-matris med tal som anger en tillåten lista över utgåvor där den här appen ska påskyndas. Varje post i matrisen motsvarar versionskoden som hämtas av GetProductInfo API. Exempel: `[121, 122]` att endast inkludera Education- och EducationN-utgåvor Obs! Det här värdet kan inte användas med ExcludedEditions.
ExkluderadeUtgåvor	Array (nummer)	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. Exempel: `[121, 122]` för att exkludera Education- och EducationN-utgåvor. Obs! Det här värdet kan inte användas med IncludedEditions.

Prover

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

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

URL-baserad appanskaffning på amd64-enheter, exklusive Education- och EducationN-utgåvor, endast på Windows 11 23H2 (not Windows 11 22H2)

{  
    "OEMName": "Contoso",
    "UpdaterName": "OEMApp1",
    "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 integrera i Universal Orchestrator-baserade uppdateringsflöden

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

Så här använder du skripten:

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

Not

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 fyra huvud-cmdletar som används för registreringsflödet:

Test-UpdaterRegistration <PathToRegistrationFile>
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 lägga i ordning innehållet i en registreringsfil på rätt plats för att underlätta det snabbare appflödet.

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

Remove-UpdaterRegistration <OEMName><UpdaterName>
Syfte: Avaktivering av 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
Det överskrider det maximala antalet 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 debiterat nätverk.
Enheten är på batteri och batterisparfunktionen är aktiverad.
Enheten är konfigurerad med en policy för begränsad nätverkstrafik för Windows Update.
Enheten har konfigurerats med en CTA-policy som inte har angetts för AutoApprove.

I vart och ett av dessa fall håller Universal Orchestrator-ramverket registreringarna på plats 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 (till exempel på grund av versionstyp) anser Universal Orchestrator-ramverket att denna 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.

Dela via