프레임워크 종속 비 MSIX 패키지 앱의 Windows 앱 SDK 배포 가이드

이 문서에서는 Windows 앱 SDK 사용하는 프레임워크 종속 비 MSIX 패키지 앱을 배포하기 위한 지침을 제공합니다. MSIX 패키지가 아닌 앱에는 스파스 패키지 및 패키지되지 않은 앱이 포함됩니다.

개요

MSIX 패키지가 아닌 앱 개발자는 최종 사용자에게 필요한 Windows 앱 SDK 런타임 패키지를 배포해야 합니다. 이 작업은 설치 관리자를 실행하거나 MSIX 패키지를 직접 설치하여 수행할 수 있습니다. 이러한 옵션은 아래 Windows 앱 SDK 런타임 배포 섹션에서 자세히 설명합니다.

MSIX 패키지가 아닌 앱에는 추가 런타임 요구 사항도 있습니다. 부트스트래퍼 API를 사용하여 Windows 앱 SDK 런타임에 대한 액세스를 초기화해야 합니다. 또한 앱에서 Windows 앱 SDK 제외한 다른 프레임워크 패키지를 사용하는 경우 동적 종속성 API를 사용할 수 있습니다. 이러한 요구 사항은 아래 의 비 MSIX 패키지 앱에 대한 런타임 요구 사항 섹션에서 자세히 설명합니다.

필수 구성 요소

추가 필수 조건

  • Windows App SDK Experimental미리 보기 버전을 사용하려면 테스트용 로드를 사용하도록 설정하여 런타임을 설치해야 합니다.
    • Windows 10 버전 2004 이상에서는 테스트용 로드가 자동으로 사용됩니다.

    • 개발 컴퓨터 또는 배포 컴퓨터에서 Windows 11을 실행 중인 경우 테스트용 로드를 사용하도록 설정했는지 확인합니다.

      • > 설정개발자를 위한Privacy & 보안>입니다. 개발자 모드 설정이 켜져 있는지 확인합니다.
    • 개발 컴퓨터 또는 배포 컴퓨터에서 Windows 10 버전 1909 이하를 실행 중인 경우 테스트용 로드를 사용하도록 설정했는지 확인합니다.

      • > 설정 개발자 & 용 보안> 업데이트>개발자 기능을 사용합니다. 테스트용 로드 앱 또는 개발자 모드가 선택되어 있는지 확인합니다.
    • 개발자 모드 설정에는 사이드로드뿐만 아니라 다른 기능이 포함됩니다.

      참고

      컴퓨터가 엔터프라이즈 환경에서 관리되는 경우 이러한 설정이 변경되지 않도록 하는 정책이 있을 수 있습니다. 이 경우 사용자 또는 앱이 Windows 앱 SDK 런타임을 설치하려고 할 때 오류가 발생하면 IT Professional 문의하여 사이드로드 또는 개발자 모드를 사용하도록 설정합니다.

Windows 앱 SDK 런타임 배포

MSIX 패키지가 아닌 앱에는 Windows 앱 SDK 런타임을 배포하는 두 가지 옵션이 있습니다.

옵션 1: 설치 관리자 사용

설치 관리자를 실행하여 모든 Windows 앱 SDK 런타임 패키지를 배포할 수 있습니다. 설치 관리자는 Windows 앱 SDK 다운로드에서 사용할 수 있습니다. 설치 관리자(.exe)를 실행할 때 다음과 유사한 출력이 표시됩니다.

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.1.0_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0

Deploying package: MicrosoftCorporationII.WindowsAppRuntime.Main.1.0_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WindowsAppRuntime.Singleton_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x6_0.318.928.0_x64__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

Deploying package: Microsoft.WinAppRuntime.DDLM.0.318.928.0-x8_0.318.928.0_x86__8wekyb3d8bbwe
Package deployment result : 0x0
Provisioning result : 0x0

All install operations successful.

사용자 상호 작용 없이 설치 관리자를 실행하고 옵션으로 모든 텍스트 출력을 --quiet 표시하지 않을 수 있습니다.

WindowsAppRuntimeInstall.exe --quiet

MSIX 패키지를 강제로 업데이트하고 이 옵션을 사용하여 --force 현재 실행 중인 Windows 앱 SDK 프로세스를 종료하도록 선택할 수도 있습니다. 이 기능은 1.1에서 도입되었습니다.

WindowsAppRuntimeInstall.exe --force

모든 설치 관리자 명령줄 옵션을 보려면 다음을 실행합니다 WindowsAppRuntimeInstall --h.

설치가 완료되면 MSIX 패키지가 아닌 앱을 실행할 수 있습니다. Windows 앱 SDK 사용하는 비 MSIX 패키지 앱을 빌드하고 실행하는 방법에 대한 예제는 자습서 - Windows 앱 SDK 사용하는 비 MSIX 패키지 앱에서 부트스트래퍼 API 사용 자습서를 참조하세요.

Windows App SDK 설치 관리자를 앱의 설치 프로그램에 연결

앱에 대한 사용자 지정 설치 프로그램이 있는 경우 앱의 설치 프로세스에서 Windows 앱 SDK 설치 프로세스를 연결할 수 있습니다. Windows App SDK 설치 관리자는 현재 기본 UI를 제공하지 않으므로 설치 프로그램의 사용자 지정 UI를 사용하여 연결해야 합니다.

ShellExecute를 사용하여 설치 진행률에 대한 자체 보기를 표시하면서 Windows App SDK 설치를 자동으로 시작하고 추적할 수 있습니다. Windows 앱 SDK 설치 관리자는 Windows App MSIX 번들의 압축을 자동으로 풀고 PackageManager.AddPackageAsync 메서드를 호출하여 설치를 완료합니다. .NET, Visual C++, DirectX 등 이전에 사용한 다른 런타임 설치 관리자와 매우 비슷합니다.

설치 프로그램에서 Windows 앱 SDK 설치 관리자를 실행하는 방법을 보여 주는 코드 예제는 설치 관리자 기능 테스트RunInstaller 함수를 참조하세요.

설치 관리자 샘플

설치하는 동안 콘솔 창을 표시하지 않고 Win32 설치 프로그램에서 설치 관리자를 시작하는 방법을 보려면 아래 샘플을 참조하세요.

문제 해결

반환 코드

다음 표에는 Windows App SDK .exe 설치 관리자의 가장 일반적인 반환 코드가 정리되어 있습니다. 반환 코드는 설치 관리자 버전에 관계없이 모두 동일합니다.

반환 코드 설명
0x0 패키지 설치 또는 프로비전이 완료되었습니다.
0x80073d06 하나 이상의 패키지를 설치하지 못했습니다.
0x80070005 앱이 관리자 권한으로 실행되고 있지 않거나 설치를 수행하는 사용자에게 관리자 권한이 없기 때문에 시스템 수준 설치 또는 프로비전을 수행할 수 없습니다.

설치 오류

Windows App SDK 설치 관리자는 설치 중에 오류를 반환하는 경우 문제를 설명하는 오류 코드를 반환합니다.

옵션 2: Windows 앱 SDK 런타임 패키지 직접 배포

Windows App SDK 설치 관리자를 사용하여 최종 사용자에게 배포하는 대신, 앱의 프로그램 또는 MSI를 통해 MSIX 패키지를 수동으로 배포할 수 있습니다. 이 옵션은 더 많은 제어를 원하는 개발자에게 가장 적합한 옵션일 수 있습니다.

설치 프로그램에서 MSIX 패키지를 설치하는 방법을 보여주는 예제는 Windows App SDK 설치 관리자 코드의 install.cpp를 참조하세요.

배포 시나리오

  • Windows 앱 SDK 런타임 시스템 전체 설치: 시스템 전체 설치는 나중에 추가되는 새 사용자를 포함하여 모든 사용자에 대한 머신을 변경합니다. 앱이 관리자 권한으로 실행되고 설치를 수행하는 사용자에게 관리자 권한이 있는 경우 설치 관리자는 ProvisionPackageForAllUsersAsync를 호출하여 시스템 전체에서 MSIX 패키지를 등록합니다. 시스템 수준 등록이 실패하는 경우 설치를 수행하는 현재 사용자에 대한 설치만 수행됩니다. 관리형 엔터프라이즈 환경의 IT 관리자는 평소처럼 모든 사용자를 프로비저닝할 수 있습니다.

  • Windows App SDK 설치 관리자에서 재배포하는 아키텍처: Windows App SDK 설치 관리자는 x86, x64Arm64 아키텍처에 제공됩니다. 설치 관리자의 각 버전에는 해당 특정 아키텍처에 대한 MSIX 패키지가 포함됩니다. 예를 들어 x64 또는 Arm64 디바이스에서 x86 WindowsAppRuntimeInstall.exe 실행하는 경우 설치 관리자는 해당 디바이스 아키텍처에 대한 패키지를 배포합니다.

  • 모든 Windows App SDK MSIX 패키지가 컴퓨터에 이미 설치되어 있음: MSIX 패키지는 시스템 수준 위치에 설치되고 디스크에 복사본이 하나만 있습니다. 모든 MSIX 패키지 종속 요소가 머신에 이미 설치되어 있는 경우 앱이 Windows App SDK를 설치하려고 하면 설치가 수행되지 않습니다.

  • 컴퓨터에 Windows App SDK MSIX 패키지가 하나도 설치되어 있지 않음: Windows App SDK를 배포할 때에는 모든 종속 요소가 설치되고 최종 사용자 환경이 중단되지 않도록 항상 모든 MSIX 패키지(프레임워크, 기본, singleton, DDLM)를 설치하려고 노력해야 합니다.

MSIX 패키지가 아닌 앱에 대한 런타임 요구 사항

MSIX 패키지가 아닌 앱에는 Windows 앱 SDK 런타임을 사용하기 위한 추가 런타임 요구 사항이 있습니다. 여기에는 런타임에 Windows 앱 SDK Framework 패키지를 참조하고 초기화하는 작업이 포함됩니다. 또한 동적 종속성 API를 사용하여 Windows 앱 SDK 외부에서 다른 프레임워크 패키지를 참조할 수 있습니다.

Windows 앱 SDK 런타임 사용

MSIX 패키지가 아닌 앱은 런타임에 Windows 앱 SDK 사용하려면 부트스트래퍼 API를 호출해야 합니다. 이 작업은 앱이 WinUI, 앱 수명 주기, MRT Core 및 DWriteCore와 같은 Windows 앱 SDK 기능을 사용하기 전에 필요합니다. 부트스트래퍼 구성 요소를 사용하면 MSIX 패키지가 아닌 앱이 다음과 같은 중요한 작업을 수행할 수 있습니다.

  • Windows 앱 SDK 프레임워크 패키지를 찾아 앱의 패키지 그래프에 로드합니다.
  • Windows 앱 SDK 프레임워크 패키지용 DDLM(동적 종속성 수명 관리자)을 초기화합니다. DDLM의 목적은 MSIX 패키지가 아닌 앱에서 사용하는 동안 Windows 앱 SDK 프레임워크 패키지의 서비스를 방지하는 것입니다.

MSIX 패키지가 아닌 앱에 대한 Windows 앱 SDK 런타임을 로드하는 가장 간단한 방법은 프로젝트 파일(.csproj 또는 .vcxproj)에서 속성을 설정하는 <WindowsPackageType>None</WindowsPackageType> 것입니다. 초기화를 보다 자세히 제어하기 위해 앱의 시작 코드에서 직접 부트스트래퍼 API를 호출할 수도 있습니다. 자세한 내용은 Windows 앱 SDK 런타임 및 자습서 사용을 참조하세요. Windows 앱 SDK 사용하는 MSIX 패키지가 아닌 앱에서 부트스트래퍼 API를 사용합니다.

동적 종속성 지원을 통해 MSIX 패키지가 아닌 애플리케이션은 MSI 또는 설치 관리자와 같은 기존 배포 메커니즘을 유지하고 애플리케이션에서 Windows 앱 SDK 활용할 수 있습니다. 동적 종속성은 패키지된 앱과 비 MSIX 패키지 앱에서 모두 사용할 수 있지만, 주로 MSIX 패키지가 아닌 앱에서 사용됩니다.

Windows 앱 SDK 프레임워크 패키지의 각 버전 및 아키텍처에 대해 하나의 DDLM이 있습니다. 즉, x64 컴퓨터에서 두 아키텍처의 앱을 지원하기 위해 DDLM의 x86x64 버전이 모두 있을 수 있습니다.

동적 종속성 API를 사용하여 다른 프레임워크 패키지 참조

Windows 앱 SDK 외부의 다른 프레임워크 패키지(예: DirectX)에서 기능을 사용하려는 경우 MSIX 패키지가 아닌 앱은 동적 종속성 API를 호출할 수 있습니다. 부트스트래퍼 구성 요소 외에도 Windows 앱 SDK 동적 종속성 API를 구현하는 광범위한 C/C++ 함수 및 WinRT 클래스 집합을 제공합니다. 이 API는 런타임에 동적으로 프레임워크 패키지를 참조하는 데 사용하도록 설계되었습니다.

자세한 내용은 데스크톱 앱 및 동적 종속성 샘플에서 동적으로 MSIX 프레임워크 패키지 사용을 참조하세요.

대상 컴퓨터에 .winmd 파일 배포

앱과 함께 진행하여 Windows 메타데이터(.winmd) 파일을 배포하는 것이 좋습니다. 메타데이터는 런타임에 다양한 API 및 동작에서 사용할 수 있으며, 메타데이터가 없으므로 기능이 제한되거나 중단될 수 있습니다. 예를 들어 메타데이터를 사용하여 아파트 경계를 넘어 개체를 마샬링할 수 있습니다. 마샬링할 필요성은 컴퓨터 성능의 기능일 수 있습니다. 메타데이터가 필요한지 여부를 확인할 수 있는 결정적인 방법은 없으므로 크기에 대해 크게 걱정하지 않는 한 배포 .winmd해야 합니다.