Mendaftarkan aplikasi OEM selama proses pencitraan

Penting

Universal Orchestrator menyediakan fungsionalitas bagi OEM untuk mendaftarkan aplikasi selama proses pencitraan untuk melakukan penginstalan atau pembaruan yang dipercepat satu kali. Penginstalan ini terjadi dalam waktu 30 menit setelah pengguna masuk ke perangkat baru. Mempercepat pemrosesan aplikasi dapat berdampak negatif pada performa pengalaman bawaan untuk perangkat baru.

Fungsionalitas ini tersedia di:

• Windows 11 23H2 - KB5046732 (Build OS 22631.4541)
• Windows 11 24H2 - KB5046740 (OS Build 26100.2454)
• Windows 11 25H2 dan versi Windows yang lebih baru

Persyaratan

Untuk menyambungkan ke kerangka kerja aplikasi yang dipercepat, aplikasi harus memenuhi persyaratan berikut:

• Ini harus berupa aplikasi terpaket Store dalam format MSIX
• Ini harus memiliki Nama Keluarga Produk (PFN) yang valid

Pendaftaran

File pendaftaran adalah file JSON ASCII yang berisi metadata dengan informasi tentang alur yang dipercepat yang diinginkan dan penargetan sisi klien kustom apa pun yang perlu dilakukan.

Aplikasi yang dipercepat mendukung dua mekanisme untuk memperbarui / memperoleh aplikasi:

1. Dari Microsoft Store menggunakan ProductId (Disarankan)
2. Dari URL yang berisi paket atau bundel MSIX. Paket ini harus berisi aplikasi paket Store dengan Nama Keluarga Paket (PFN) yang valid. OEM atau Pemilik Aplikasi bertanggung jawab untuk mempertahankan URL ini.

Setiap file pendaftaran harus berisi properti JSON yang diperlukan berikut:

Kunci	Jenis	Deskripsi
PFN	String	Nama Keluarga Paket aplikasi (Contoh: Microsoft.WindowsStore_8wekyb3d8bbwe)
OEMName	String	String untuk mewakili OEM yang membuat pendaftaran ini. Hanya boleh berisi karakter alfanumerik, garis bawah, dan tanda hubung.
UpdaterName	String	Nama unik untuk melacak pendaftaran yang dipercepat ini. Hanya boleh berisi karakter alfanumerik, garis bawah, dan tanda hubung.
Versi Pendaftaran	Angka	Versi pendaftaran aplikasi ini
Sumber	String	Nilai yang diizinkan: Toko | CustomURL Store - mencari aplikasi langsung dari Microsoft Store CustomURL - mencari aplikasi dari URL yang ditentukan dalam nilai "Titik Akhir" pendaftaran aplikasi
Skenario	String	Nilai yang diizinkan: Pembaruan | Akuisisi | StubAcquisition Pembaruan - (Tidak didukung untuk alur CustomURL) mencoba memperbarui aplikasi yang ada ke versi terbaru yang tersedia. Tidak ada pekerjaan yang dilakukan jika aplikasi tidak ada Akuisisi - mencoba memperoleh versi terbaru aplikasi. StubAcquisition - mencoba mendapatkan "stub" dari aplikasi (jika tersedia). Memperoleh aplikasi lengkap jika stub tidak tersedia.
ProductId	String	(Hanya diperlukan untuk skenario Store) ProductId dari aplikasi Store yang diinginkan
Titik Akhir	String	(Hanya diperlukan untuk skenario CustomURL) URI string menunjuk ke lokasi yang menghosting paket MSIX. Harus URI SSL yang dimulai dengan 'https'.

Selain itu, properti opsional berikut dapat ditentukan untuk memodifikasi perilaku penginstalan aplikasi yang dipercepat, atau untuk menargetkan alur yang dipercepat hanya terjadi dalam kondisi tertentu.

Kunci	Jenis	Bawaan	Deskripsi
DiizinkanDalamOobe	Boolean	Palsu	Haruskah aplikasi yang diprioritaskan ini berjalan selama pengalaman pertama kali pengguna (OOBE)? Penting: Berhati-hatilah saat mengatur ke true, karena ini dapat membuat batasan sumber daya pada perangkat selama alur Pengalaman Di Luar Kotak dan berdampak negatif pada performa yang dirasakan pengguna.
JumlahPengulanganMaksimum	Angka	1	Berapa kali updater ini diizinkan untuk mencoba kembali setelah kegagalan. Nilai maksimum yang diizinkan adalah: 5
TimeoutDurationInMinutes	Angka	15	Lama waktu menunggu dalam menit agar updater ini selesai bekerja. Nilai maksimum yang diizinkan adalah: 30
Arsitektur	String	Tidak ada batasan	Nilai yang diizinkan: "amd64" | "arm64" Menentukan apakah pekerjaan yang dipercepat hanya boleh terjadi untuk arsitektur tertentu.
VersiBuildMinimalYangDiizinkan	Angka	Tidak ada batasan	Versi build Windows minimum di mana pekerjaan yang dipercepat diizinkan. Misalnya, jika diatur ke 22631, pekerjaan yang dipercepat diizinkan untuk Windows 11 23H2 (10.0.22631.x), tetapi diblokir untuk Windows 11 22H2 (10.0.22621.x)
HonorDeprovisioning	Boolean	Palsu	(Hanya berlaku untuk skenario Akuisisi) Jika aplikasi sebelumnya dinonaktifkan, jangan mencoba untuk memperolehnya lagi.
LewatiJikaAda	Boolean	Palsu	(Hanya berlaku untuk skenario Akuisisi) Jangan melakukan kerja cepat jika ada versi aplikasi yang sudah terinstal.
Prioritas	Angka	100	Nilai numerik dari 1 - 100 untuk menunjukkan prioritas relatif pembaruan aplikasi ini. Nilai yang lebih rendah menunjukkan prioritas relatif yang lebih tinggi untuk aplikasi lain yang dipercepat.
Wilayah yang Dikecualikan	Array (String)	Tidak ada batasan	Array JSON berisi string untuk wilayah di mana aplikasi ini TIDAK boleh dipercepat. Setiap entri dalam array sesuai dengan dua huruf KODE negara ISO 3166-1 dari wilayah yang diinginkan. Contoh: ["US", "MX"] akan mencegah alur ini pada perangkat di mana wilayah tersebut adalah Amerika Serikat atau Meksiko. Nilai ini tidak dapat digunakan dengan IncludedRegions.
WilayahTercakup	Array (String)	Tidak ada batasan	Array JSON dari string yang menunjukkan daftar wilayah yang diperbolehkan di mana aplikasi ini harus dipercepat. Setiap entri dalam array sesuai dengan dua huruf KODE negara ISO 3166-1 dari wilayah yang diinginkan. Contoh: ["US", "MX"] akan memungkinkan alur ini hanya pada perangkat di mana wilayah tersebut adalah Amerika Serikat atau Meksiko. Nilai ini tidak dapat digunakan dengan ExcludedRegions.
Edisi yang Disertakan	Array (Angka)	Tidak ada batasan	Array angka JSON yang menunjukkan daftar izin Edisi di mana aplikasi ini harus dipercepat. Setiap entri dalam array sesuai dengan kode Edisi yang diambil oleh GetProductInfo API. Contoh: [121, 122] hanya menyertakan Edisi Pendidikan dan EducationN Nilai ini tidak dapat digunakan dengan ExcludedEditions.
Edisi yang Dikecualikan	Array (Angka)	Tidak ada batasan	Array JSON berisi angka untuk Edisi yang aplikasi ini TIDAK boleh dipercepat. Setiap entri dalam array sesuai dengan kode Edisi yang diambil oleh GetProductInfo API. Contoh: [121, 122] untuk mengecualikan Edisi Pendidikan dan EducationN. Nilai ini tidak dapat digunakan dengan IncludedEditions.

Sampel

Akuisisi stub berbasis Store, hanya di AS dan Meksiko, untuk dijalankan selama OOBE

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

akuisisi aplikasi berbasis URL pada perangkat amd64, tidak termasuk edisi Education dan EducationN, hanya pada 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 
}

Perkakas

Untuk memfasilitasi proses pendaftaran dan memberikan umpan balik yang dapat ditindaklanjuti pada metadata pendaftaran, OEM perlu menggunakan AppOrchestration skrip PowerShell dari lokasi berikut:

microsoft/ms-update-universalorchestrator: Script dan alat untuk beralih ke alur pembaruan berbasis Universal Orchestrator

Skrip melakukan validasi dasar dan tahap pendaftaran ke lokasi yang sesuai pada perangkat. Pada kegagalan apa pun, skrip melemparkan pengecualian dengan detail kegagalan tertentu.

Untuk menggunakan skrip:

1. Unduh skrip ke perangkat Anda. Dari halaman repositori GitHub, Anda dapat memilih untuk mengunduh sebagai file ZIP dan mengekstrak ke perangkat Anda
2. Di jendela PowerShell, jalankan "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1"

Nota

Skrip ini mengharuskan pengguna untuk memiliki hak administratif pada perangkat, dan harus dijalankan dari konsol yang ditingkatkan.

Ada empat cmdlet utama yang digunakan untuk alur pendaftaran:

<Test-UpdaterRegistration PathToRegistrationFile>
Tujuan: Memvalidasi konten file pendaftaran yang diusulkan (tanpa melakukan pendaftaran). Memungkinkan OEM untuk melakukan iterasi pada payload file pendaftaran tanpa memengaruhi perangkat.

<Add-UpdaterRegistration PathToRegistrationFile>
Tujuan: Memvalidasi dan menempatkan konten file pendaftaran ke lokasi yang tepat, untuk memulai proses aplikasi cepat.

Get-UpdaterRegistration <OEMName><UpdaterName>
Tujuan: Jika OEMName dan UpdaterName disediakan, kembalikan ringkasan pendaftaran yang ada yang cocok dengan nilai tersebut. Jika input tersebut dihilangkan, kembalikan semua ringkasan pendaftaran saat ini yang ada di perangkat.

<Remove-UpdaterRegistration OEMName><UpdaterName>
Tujuan: Batalkan pendaftaran apa pun yang cocok dengan nilai OEMName dan UpdaterName.

Eksekusi

Kerangka kerja Universal Orchestrator secara otomatis mengaktifkan tiap aplikasi terdaftar sesuai urutan prioritas relatif, dalam 30 menit pertama saat pengguna tiba di Desktop pada perangkat baru (atau selama OOBE Pengguna jika AllowedInOobe disetel ke true). Setiap aplikasi terdaftar yang ditambahkan oleh proses pendaftaran OEM akan dicoba hingga:

• Ini berhasil diinstal
• Ini melampaui jumlah maksimum kegagalan yang ditentukan dalam MaxRetryCount. Setelah setiap kegagalan, aplikasi akan memasuki periode pendinginan 30 menit sebelum dicoba lagi.

Kerangka kerja Universal Orchestrator tidak akan melakukan upaya yang dipercepat jika salah satu kondisi berikut ini benar:

• Perangkat tidak memiliki akses internet.
• Perangkat terhubung ke jaringan dengan kuota terbatas.
• Perangkat menggunakan baterai, dan penghemat baterai diaktifkan.
• Perangkat dikonfigurasi dengan kebijakan Pembaruan Windows Lalu Lintas Jaringan Terbatas .
• Perangkat dikonfigurasi dengan kebijakan CTA yang tidak disetel untuk AutoApprove.

Dalam setiap kasus ini, kerangka Universal Orchestrator menjaga pendaftaran tetap ada hingga konfigurasi perangkat memungkinkan upaya yang dipercepat untuk dilanjutkan.

Jika pendaftaran aplikasi berisi nilai opsional yang memblokir alur yang dipercepat (misalnya, karena jenis edisi), kerangka kerja Universal Orchestrator mempertimbangkan permintaan pendaftaran ini terpenuhi dan tidak akan mencobanya lagi, bahkan jika kondisi tersebut nantinya mungkin berubah pada perangkat.

Penting

Berhati-hatilah saat memilih untuk mempercepat aplikasi melalui kerangka kerja ini, karena operasi pembaruan terjadi ketika perangkat mungkin digunakan dan dapat menyebabkan dampak performa negatif dari pengalaman pengguna pada perangkat baru.

Mempertahankan pendaftaran untuk pemulihan dan reset perangkat

Untuk memastikan penginstalan atau pembaruan aplikasi yang dipercepat masih terjadi setelah pemulihan perangkat atau skenario reset, migrasikan pendaftaran bertahap dengan menggunakan User State Migration Tool (USMT): ambil dengan ScanState.exe sebelum pemulihan atau reset, dan pulihkan dengan LoadState.exe setelah pemulihan atau reset. Untuk informasi selengkapnya, lihat dokumentasi USMT.