이미징 프로세스 중에 OEM 애플리케이션 등록

2025-03-28

중요합니다

유니버설 오케스트레이터는 일회성 신속한 설치/업데이트를 수행하기 위해 이미징 프로세스 중에 애플리케이션을 등록하는 OEM에 기능을 제공합니다. 이 설치는 사용자가 새 디바이스에 로그인한 후 30분 이내에 발생합니다. 애플리케이션을 신속화하면 새 디바이스의 기본 환경에 부정적인 성능 영향을 줄 수 있습니다. 이 기능은 2024년 11월 누적 비보안 미리 보기 업데이트를 실행하는 Windows 버전에서만 사용할 수 있습니다.

Windows 11 23H2 - KB5046732(OS 빌드 22631.4541)
Windows 11 24H2 - KB5046740(OS 빌드 26100.2454)

요구 사항

신속한 앱 프레임워크에 연결하려면 앱이 다음 요구 사항을 충족해야 합니다.

MSIX 형식의 스토어 패키지 앱이어야 합니다.
유효한 PFN(제품군 이름)이 있어야 합니다.

등록

등록 파일은 원하는 신속한 흐름 및 수행해야 하는 사용자 지정 클라이언트 쪽 대상 지정에 대한 정보가 포함된 메타데이터를 포함하는 ASCII JSON 파일입니다.

신속한 앱은 앱을 업데이트/획득하는 두 가지 메커니즘을 지원합니다.

Microsoft Store에서 ProductId 을(를) 사용하여 (권장)
MSIX 패키지 또는 번들을 포함하는 URL에서 이 패키지에는 유효한 PFN(패키지 패밀리 이름)이 있는 Store 패키지 앱이 포함되어야 합니다. OEM 또는 앱 소유자는 이 URL을 유지 관리할 책임이 있습니다.

각 등록 파일에는 다음과 같은 필수 JSON 속성이 포함되어야 합니다.

열쇠	유형	설명
PFN	문자열	앱의 패키지 패밀리 이름(예: Microsoft.WindowsStore_8wekyb3d8bbwe)
OEMName	문자열	이 등록을 만드는 OEM을 나타내는 문자열
UpdaterName	문자열	이 신속한 등록을 추적하는 고유 이름
등록 버전	숫자	이 앱 등록의 버전
출처	문자열	허용되는 값: 스토어 \| CustomURL 스토어 - Microsoft Store에서 직접 앱 검색 CustomURL - 앱 등록의 "엔드포인트" 값에 지정된 URL에서 앱을 검색합니다.
시나리오	문자열	허용되는 값: 업데이트 \| 취득 \| StubAcquisition 업데이트 - (CustomURL 흐름에 지원되지 않음) 기존 앱을 사용 가능한 최신 버전으로 업데이트하려고 시도합니다. 앱이 없는 경우 작업이 수행되지 않습니다. 취득 - 앱의 최신 버전을 획득하려고 시도합니다. StubAcquisition - 앱의 "스텁"을 획득하려고 시도합니다(사용 가능한 경우). 스텁을 사용할 수 없는 경우 전체 앱을 가져옵니다.
ProductId	문자열	(Store 시나리오에만 필요) 원하는 스토어 앱의 ProductId
엔드포인트	문자열	(CustomURL 시나리오에만 필요) MSIX 패키지를 호스트하는 위치를 가리키는 문자열 URI입니다. 'https'로 시작하는 SSL URI여야 합니다.

또한 다음 선택적 속성을 지정하여 신속한 앱 설치의 동작을 수정하거나 특정 조건에서만 발생하는 신속한 흐름을 대상으로 지정할 수 있습니다.

열쇠	유형	기본값	설명
OOBE에서 허용됨	불리언 (Boolean)	거짓	이 신속한 앱이 사용자 OOBE 중에 실행되어야 하는지 여부입니다. 참고: true로 설정할 때는 기본 제공 환경 흐름 중에 디바이스에 리소스 제약 조건이 생성되고 사용자 인식 성능에 부정적인 영향을 미칠 수 있으므로 주의해야 합니다.
최대 재시도 횟수	숫자	1	이 업데이트 관리자가 실패 후 다시 시도할 수 있는 횟수입니다. 허용되는 최대 값은 5입니다.
타임아웃 시간(분 단위)	숫자	15	이 업데이트 관리자가 작업을 완료할 때까지 대기하는 기간(분)입니다. 허용되는 최대 값은 30입니다.
건축학	문자열	제한 없음	허용되는 값: "amd64" \| "arm64" 특정 아키텍처에 대해서만 신속한 작업이 수행되어야 하는지 여부를 지정합니다.
허용되는 최소 빌드 버전	숫자	제한 없음	신속한 작업이 허용되는 최소 Windows 빌드 버전입니다. 예를 들어 22631로 설정하면 Windows 11 23H2(10.0.22631.x)에 대해 신속한 작업이 허용되지만 Windows 11 22H2(10.0.22621.x)에 대해서는 차단됩니다.
HonorDeprovisioning	불리언 (Boolean)	거짓	(취득 시나리오에만 적용) 앱이 이전에 프로비전 해제된 경우 다시 획득하지 마세요.
존재할 경우 건너뜀	불리언 (Boolean)	거짓	(취득 시나리오에만 적용) 앱 버전이 이미 있는 경우 신속한 작업을 수행하지 마세요.
우선권	숫자	100	이 애플리케이션 업데이트의 상대적 우선 순위를 나타내는 1에서 100까지의 숫자 값입니다. 값이 낮을수록 다른 빠른 앱에 대한 상대적 우선 순위가 높음을 나타냅니다.
제외 지역	배열(문자열)	제한 없음	이 앱을 신속하게 처리해서는 안 되는 지역에 대한 문자열의 JSON 배열입니다. 배열의 각 항목은 원하는 지역의 두 문자 ISO 3166-1 국가 코드에 해당합니다. 예: `["US", "MX"]` 지역이 미국 또는 멕시코인 디바이스에서 이 흐름을 방지합니다. 참고: 이 값은 IncludedRegions와 함께 사용할 수 없습니다.
포함된 지역	배열(문자열)	제한 없음	이 앱을 신속하게 처리해야 하는 지역의 허용 목록을 나타내는 문자열의 JSON 배열입니다. 배열의 각 항목은 원하는 지역의 두 문자 ISO 3166-1 국가 코드에 해당합니다. 예: `["US", "MX"]` 지역이 미국 또는 멕시코인 디바이스에서만 이 흐름을 허용합니다. 참고: 이 값은 ExcludedRegions와 함께 사용할 수 없습니다.
포함된 에디션	배열(숫자)	제한 없음	이 앱이 우선적으로 처리되어야 하는 에디션의 허용 목록을 나타내는 숫자 JSON 배열입니다. 배열의 각 항목은 GetProductInfo API검색된 Edition 코드에 해당합니다. 예: Education 및 EducationN 에디션만을 포함하도록 `[121, 122]` 참고: 이 값은 ExcludedEditions와 함께 사용할 수 없습니다.
제외된 에디션	배열(숫자)	제한 없음	이 앱을 신속하게 처리해서는 안 되는 Edition에 대한 숫자의 JSON 배열입니다. 배열의 각 항목은 GetProductInfo API검색된 Edition 코드에 해당합니다. 예: `[121, 122]` Education 및 EducationN Edition을 제외합니다. 참고: 이 값은 IncludedEditions와 함께 사용할 수 없습니다.

샘플

OOBE 동안 미국과 멕시코에서만 스토어 기반 스텁 인수를 실행할 수 있습니다.

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

Windows 11 23H2 버전에서만, Education 및 EducationN 에디션을 제외하고, amd64 디바이스에서 URL을 통한 앱 설치 (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 
}

도구

등록 프로세스를 용이하게 하고 등록 메타데이터에 대한 실행 가능한 피드백을 제공하려면 OEM은 다음 위치에서 AppOrchestration PowerShell 스크립트를 사용해야 합니다.

microsoft/ms-update-universalorchestrator: 유니버설 오케스트레이터 기반 업데이트 흐름에 온보딩할 스크립트 및 도구

스크립트는 기본 유효성 검사를 수행하고 디바이스의 적절한 위치에 등록을 준비합니다. 모든 오류가 발생하면 스크립트는 특정 오류 세부 정보와 함께 예외를 발생시킵니다.

스크립트를 사용하려면 다음을 수행합니다.

디바이스에 스크립트를 다운로드합니다. GitHub 리포지토리 페이지에서 ZIP 파일로 다운로드하고 디바이스에 추출하도록 선택할 수 있습니다.
PowerShell 창에서 "Import-Module <PathToScripts>\scripts\AppOrchestration.psd1"을 실행합니다.

비고

이러한 스크립트를 사용하려면 사용자에게 디바이스에 대한 관리 권한이 있어야 하며 관리자 권한 콘솔에서 실행해야 합니다.

등록 흐름에 사용되는 네 가지 기본 cmdlet이 있습니다.

Test-UpdaterRegistration <PathToRegistrationFile>
목적: 등록을 수행하지 않고 제안된 등록 파일의 콘텐츠 유효성을 검사합니다. OEM에서 디바이스에 영향을 주지 않고 등록 파일 페이로드를 반복할 수 있습니다.

Add-UpdaterRegistration <PathToRegistrationFile>
목적: 신속한 앱 흐름에 온보딩하기 위해 등록 파일의 내용의 유효성을 검사하고 적절한 위치에 스테이징합니다.

Get-UpdaterRegistration <OEMName><UpdaterName>
목적: OEMName 및 UpdaterName이 제공되면 해당 값과 일치하는 기존 등록 요약을 반환합니다. 이러한 입력을 생략하면 디바이스에 있는 모든 현재 등록에 대한 요약을 반환합니다.

Remove-UpdaterRegistration <OEMName><UpdaterName>
목적: OEMName 및 UpdaterName 값과 일치하는 등록을 스테이징 해제합니다.

실행

유니버설 오케스트레이터 프레임워크는 사용자가 새 디바이스에서 Desktop에 도달한 후 처음 30분 이내에(또는 AllowedInOobe가 true로 설정된 경우 사용자 OOBE 동안) 상대적 우선 순위에 따라 등록된 각 앱을 순서대로 자동으로 호출합니다. OEM 등록 프로세스에 의해 추가된 등록된 각 애플리케이션은 다음 중 하나까지 시도됩니다.

성공적으로 설치되었습니다.
MaxRetryCount에 지정된 최대 오류 수를 초과합니다. 실패할 때마다 앱은 다시 시도하기 전에 30분의 냉각 기간을 입력합니다.

다음 조건이 충족되면 유니버설 오케스트레이터 프레임워크는 신속한 시도를 수행하지 않습니다.

디바이스에 인터넷에 액세스할 수 없습니다.
디바이스가 요금제 네트워크에 있습니다.
디바이스가 배터리에 있고 배터리 절약 장치가 사용하도록 설정되어 있습니다.
디바이스는 Windows 업데이트 제한 네트워크 트래픽 정책으로 구성됩니다.
디바이스가 자동 승인이 설정되지 않은 CTA 정책으로 설정되어 있습니다.

이러한 각 경우에서 유니버설 오케스트레이터 프레임워크는 디바이스 구성에서 신속한 시도를 진행할 수 있도록 할 때까지 등록을 유지합니다.

앱 등록에 신속한 흐름을 차단하는 선택적 값(예: 버전 유형)이 포함된 경우 유니버설 오케스트레이터 프레임워크는 이 등록 요청이 처리된 것으로 간주하고 나중에 디바이스에서 해당 조건이 변경될 수 있더라도 다시 시도하지 않습니다.

중요합니다

디바이스가 사용 중일 때 업데이트 작업이 발생하고 새 디바이스에서 사용자 환경의 성능에 부정적인 영향을 줄 수 있으므로 이 프레임워크를 통해 앱을 신속하게 처리하도록 선택할 때 주의해야 합니다.

다음을 통해 공유

이미징 프로세스 중에 OEM 애플리케이션 등록

요구 사항

등록

샘플

도구

실행

피드백

추가 리소스