외부 위치로 패키지되거나 패키지되지 않은 프레임워크 종속 앱을 위한 Windows 앱 SDK 배포 가이드

  • 아티클

이 항목에서는 외부 위치로 패키지되거나 패키지되지 않은 앱을 배포하고 Windows 앱 SDK 사용하는 앱을 배포하는 방법에 대한 지침을 제공합니다.

개요

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

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

필수 조건

추가 필수 조건

  • Windows App SDK Experimental 및 미리 보기 버전을 사용하려면 테스트용 로드를 사용하도록 설정하여 런타임을 설치해야 합니다.

    • Windows 10 버전 2004 이상에서는 테스트용 로드가 자동으로 사용됩니다.

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

      • 설정>프라이버시 & 보안>개발자용. 이 개발자 모드 설정이 켜져 있는지 확인하세요.

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

      • 설정>, & 보안 업데이트>개발자용>개발자 기능 사용. 해당 테스트용 로드 앱 또는 개발자 모드가 선택되어 있는지 확인합니다.

    • 이 개발자 모드 설정에는 사이드로드뿐만 아니라 다른 기능이 포함됩니다.

      참고 항목

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

Windows 앱 SDK 런타임 배포

외부 위치와 패키지되지 않은 앱으로 패키지된 앱에는 Windows 앱 SDK 런타임을 배포하는 두 가지 옵션이 있습니다.

  • 옵션 1: 설치 관리자 사용: 자동 설치 관리자는 모든 Windows 앱 SDK MSIX 패키지를 배포합니다. 각 및 아키텍처에 대해 별도의 설치 관리자를 X64X86Arm64 사용할 수 있습니다.
  • 옵션 2: 패키지 직접 설치: 기존 설치 또는 MSI 도구가 Windows 앱 SDK MSIX 패키지를 전달하고 설치하도록 할 수 있습니다.

옵션 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.

설치가 완료되면 외부 위치로 패키지된 앱 또는 패키지되지 않은 앱을 실행할 수 있습니다. Windows App SDK를 사용하는 외부 위치 또는 Unpackaged 앱을 구축하고 실행하는 방법의 예는 자습서: Windows App SDK를 사용하는 외부 위치 또는 Unpackaged 앱에서 부트스트래퍼 API를 사용합니다.

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

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

ShellExecute를 사용하여 설치 진행률에 대한 자체 보기를 표시하면서 Windows App SDK 설치를 자동으로 시작하고 추적할 수 있습니다. Windows 앱 SDK 설치 관리자는 Windows 앱 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, x64 및 Arm64 아키텍처에 제공됩니다. 설치 관리자의 각 버전에는 해당 특정 아키텍처에 대한 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)를 설치하려고 노력해야 합니다.

외부 위치로 패키지된 앱 또는 패키지되지 않은 앱에 대한 런타임 요구 사항

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

Windows 앱 SDK 런타임 사용

외부 위치 및 패키지되지 않은 앱으로 패키지된 앱은 런타임에 Windows 앱 SDK 사용하려면 부트스트래퍼 API를 호출해야 합니다. 앱이 WinUI, 앱 수명 주기, MRT Core 및 DWriteCore와 같은 Windows 앱 SDK 기능을 사용하려면 먼저 이 작업이 필요합니다. 부트스트래퍼 구성 요소를 사용하면 외부 위치 및 패키지되지 않은 앱으로 패키지되어 다음과 같은 중요한 작업을 수행할 수 있습니다.

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

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

동적 종속성 지원을 통해 외부 위치 및 패키지되지 않은 앱과 함께 패키지된 앱은 MSI 또는 설치 관리자와 같은 기존 배포 메커니즘을 유지하고 애플리케이션에서 Windows 앱 SDK를 활용할 수 있습니다. 동적 종속성은 패키지된 앱, 외부 위치로 패키지된 앱 및 패키지되지 않은 앱에서 사용할 수 있습니다. 주로 외부 위치 및 패키지되지 않은 앱과 함께 패키지된 앱에서 사용하기 위한 것입니다.

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

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

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

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

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

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