외부 위치로 패키지되거나 패키지되지 않은 앱에 Windows 앱 SDK 런타임 사용

  • 아티클

참고 항목

MSIX 기술을 사용하여 앱을 설치하는 경우 프레임워크 종속 패키지 앱에 대한 Windows 앱 SDK 배포 가이드를 참조하세요.

앱이 MSIX를 사용하여 설치되지 않은 경우(즉, 외부 위치로 패키지되거나 패키지되지 않음) WinUI 3, 앱 수명 주기, MRT Core 및 DWriteCore와 같은 Windows 앱 SDK 기능을 호출하려면 먼저 사용할 Windows 앱 SDK 초기화해야 합니다. 앱은 Windows 앱 SDK 다른 기능을 사용하기 전에 Windows 앱 SDK 런타임을 초기화해야 합니다.

  • Windows 앱 SDK 1.0부터 앱이 자동 초기화(프로젝트 속성 <WindowsPackageType>None</WindowsPackageType>설정)를 통해 시작될 때 자동으로 수행할 수 있습니다. 데모는 첫 번째 WinUI 3 프로젝트 만들기를 참조하세요.
  • 그러나 사용자 고유의 사용자 지정 UI 또는 로깅을 표시하여 오류 처리 또는 빌드한 버전과 다른 Windows 앱 SDK 버전을 로드해야 하는 경우와 같은 고급 요구 사항이 있는 경우 이 항목을 계속 읽어보세요. 이러한 시나리오에서는 자동 초기화 대신 부트스트래퍼 API를 명시적으로 호출할 수 있습니다.

위의 두 가지 기술 중 하나를 사용하면 MSIX를 사용하지 않는 앱이 런타임에 Windows 앱 SDK 동적 종속성을 사용할 수 있습니다.

동적 종속성에 대한 배경 정보는 MSIX 프레임워크 패키지 및 동적 종속성를 참조하십시오.

백그라운드에서 자동 모듈 초기화 옵트아웃

위에서 언급한 속성에서 WindowsPackageType 생성된 코드는 모듈 이니셜라이저를 활용하여 부트스트래퍼 API를 호출합니다. 부트스트래퍼는 Windows 앱 SDK를 찾고 현재 프로세스에서 사용할 수 있도록 하기 위해 많은 작업을 수행합니다. 생성된 코드는 초기화와 종료를 모두 처리합니다. 다음 프로젝트 속성을 사용하여 초기화의 동작을 제어할 수 있습니다.

  • <WindowsAppSDKBootstrapAutoInitializeOptions_Default>true</WindowsAppSDKBootstrapAutoInitializeOptions_Default>
    • 기본 옵션 사용하기
  • <WindowsAppSDKBootstrapAutoInitializeOptions_None>true</WindowsAppSDKBootstrapAutoInitializeOptions_None>
    • 옵션을 사용하지 않습니다.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak>
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_DebugBreak_IfDebuggerAttached>
    • 디버거가 프로세스에 연결된 경우에만 오류가 발생하는 경우 DebugBreak()를 호출합니다.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnError_FailFast>
    • 오류가 발생하면 장애 조치(fail-fast)를 수행합니다.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnNoMatch_ShowUI>
    • 일치하는 런타임을 찾을 수 없는 경우 사용자에게 Windows 앱 SDK 런타임을 획득하라는 메시지를 표시합니다.
  • <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
    • 패키지 ID가 있는 프로세스에서 호출된 경우 오류가 발생합니다(그렇지 않으면 실패하고 오류가 반환됨).

앱이 명시적 제어를 갖도록 하려면 애플리케이션 시작 초기에 boostrapper API를 직접 호출할 수 있습니다. 이 경우 프로젝트 파일에 필요하지 WindowsPackageType 않습니다.

참고 항목

자동 초기화 및 부트스트래퍼 API 외에도 Windows 앱 SDK는 동적 종속성 API의 구현을 제공합니다. 패키지되지 않은 앱은 이 API를 사용하여 Windows 앱 SDK 프레임워크 패키지뿐만 아니라 모든 프레임워크 패키지에 대한 종속성을 가질 수 있으며 부트스트래퍼 API에서 내부적으로 사용됩니다. 동적 종속성 API에 대한 자세한 내용은 동적 종속성 API를 사용하여 런타임 에 MSIX 패키지 참조를 참조하세요.

자동 모듈 초기화 옵트아웃(또는 옵트인)

프로젝트 속성 <WindowsAppSdkBootstrapInitialize>false</WindowsAppSdkBootstrapInitialize> 은 위에서 설명한 자동 모듈 초기화를 사용하지 않도록 설정합니다(부트스트래퍼 API는 호출되지 않음). 이를 통해 앱은 책임을 지고 부트스트래퍼 API를 직접 호출할 수 있습니다.

Windows App SDK 버전 1.2(안정 채널에서)에서는 자동 모듈 초기화는 실행 파일을 생성하는 프로젝트에만 적용됩니다(즉, OutputType 프로젝트 속성이 Exe 또는 WinExe로 설정됨). 이는 클래스 라이브러리 DLL 및 기타 실행 불가능한 파일에 자동 초기화기를 기본적으로 추가하지 못하도록 방지하기 위한 것입니다. 실행 불가능한 파일(예를 들어 부트스트래퍼를 초기화하지 않는 호스트 프로세스 실행 파일에 의해 로드된 테스트 DLL)에 자동 초기화기가 정말 필요한 경우 <WindowsAppSdkBootstrapInitialize>true</WindowsAppSdkBootstrapInitialize>을 사용하여 프로젝트에서 자동 초기화기를 명시적으로 활성화할 수 있습니다.

부트스트래퍼 API 사용

Important

아래에 멘션 MddBootstrapInitialize2 함수는 버전 1.1부터 사용할 수 있습니다.

부트스트랩 API는 Windows App SDK의 mddbootstrap.h 헤더 파일에 선언된 세 가지 C/C++ 함수로 구성됩니다. MddbootstrapInitialize, MddbootstrapInitialize2, MddbootstrapShutdown. 이러한 함수는 Windows 앱 SDK 부트스트래퍼 라이브러리에서 제공합니다. 이 라이브러리는 앱과 함께 배포해야 하는 작은 DLL입니다. 프레임워크 패키지 자체의 일부가 아닙니다.

MddBootstrapInitialize2

이 함수는 함수 매개 변수에 전달하는 조건과 가장 일치하는 Windows 앱 SDK 프레임워크 패키지 버전을 사용하도록 호출 프로세스를 초기화합니다. 일반적으로 설치된 Windows 앱 SDK NuGet 패키지와 일치하는 프레임워크 패키지의 버전을 참조하게 됩니다. 여러 패키지가 기준을 충족하는 경우 가장 적합한 후보가 선택됩니다. 이 함수는 부트스트래퍼 구성 요소가 Windows 앱 SDK를 올바르게 초기화하고 런타임 참조를 프레임워크 패키지에 추가할 수 있도록 하기 위해 앱 시작의 첫 번째 호출 중 하나여야 합니다.

부트스트래퍼 API는 동적 종속성 API를 사용하여 Windows 앱 SDK 런타임의 프레임워크 패키지를 현재 프로세스의 패키지 그래프에 추가하고, 그렇지 않으면 패키지에 대한 액세스를 사용하도록 설정합니다.

이 함수는 또한 DDLM(동적 종속성 수명 관리자)을 초기화합니다. 이 구성 요소는 패키지되지 않은 앱에서 사용하는 동안 OS가 Windows 앱 SDK 프레임워크 패키지를 서비스하지 못하도록 하는 인프라를 제공합니다.

MddBootstrapShutdown

이 함수는 MddBootstrapInitialize 호출에 의해 수행된 현재 프로세스의 변경 내용을 제거합니다. 이 함수가 호출된 후에는 앱이 동적 종속성 API를 포함하여 Windows 앱 SDK API를 더 이상 호출할 수 없습니다.

이 함수는 필요에 따라 Windows에서 프레임워크 패키지를 서비스할 수 있도록 DDLM(동적 종속성 수명 관리자)도 종료합니다.

부트스트래퍼 API용 .NET 래퍼

.NET 앱에서 직접 C/C++ 부트스트래퍼 API를 호출할 수 있지만 플랫폼 호출을 사용하여 함수를 호출해야 합니다. Windows 앱 SDK 1.0 이상 릴리스에서는 부트스트래퍼 API에 대한 .NET 래퍼를 어셈블리에서 Microsoft.WindowsAppRuntime.Bootstrap.Net.dll 사용할 수 있습니다. 이 어셈블리는 .NET 개발자가 부트스트래퍼의 기능에 액세스할 수 있는 보다 쉽고 자연스러운 API를 제공합니다. 이 부트스트랩 클래스는 대부분의 일반적인 시나리오에 대해 MddBootstrapInitialize 및 MddBootstrapShutdown 기능에 대한 호출을 랩하는 정적 Initialize, TryInitialize 및 Shutdown 기능을 제공합니다. 부트스트래퍼 API에 .NET 래퍼를 사용하는 방법을 보여 주는 예제는 자습서의 C# 지침을 참조하세요. 외부 위치로 패키지된 앱에서 부트스트래퍼 API를 사용하거나 Windows 앱 SDK 사용하는 패키지가 없는 앱에서 부트스트래퍼 API를 사용합니다.

부트스트래퍼 API용 .NET 래퍼에 대한 자세한 내용은 다음 리소스를 참조하세요.

부트스트래퍼 API에 대한 C++ 래퍼

부트스트래퍼 API에 대한 C++ 래퍼는 Windows 앱 SDK 1.1부터 사용할 수 있습니다.

부트스트래퍼 C++ API 참조하세요.

애플리케이션 매니페스트에서 OS 호환성 선언

운영 체제(OS) 호환성을 선언하고 windows 8 동작(및 잠재적 크래시)으로 기본 설정되는 Windows 앱 SDK 방지하기 위해 외부 위치 또는 패키지되지 않은 앱으로 패키지된 병렬 애플리케이션 매니페스트를 포함할 수 있습니다. 애플리케이션 매니페스트(DPI 인식과 같은 항목을 선언하고 빌드 중에 앱의 .exe에 포함되는 파일)를 참조하세요. Visual Studio 프로젝트 템플릿을 통해 새 앱을 만드는 대신 기존 앱에 Windows 앱 SDK 지원을 추가하는 경우 문제가 될 수 있습니다.

프로젝트에 side-by-side 응용 프로그램 매니페스트가 아직 없는 경우 프로젝트에 새 XML 파일을 추가하고 응용 프로그램 매니페스트 에서권장하는 대로 이름을 지정합니다. 다음 예제에 표시된 호환성 요소와 자식 요소를 파일에 추가합니다. 이러한 값은 앱 프로세스에서 실행되는 구성 요소의 단점 수준을 제어합니다.

maxversiontested 요소의 ID 특성을 대상으로 하는 Windows의 버전 번호로 바꿉니다(10.0.17763.0 이상 릴리스여야 함). 높은 값을 설정하면 모든 Windows 릴리스가 이전 버전만 알고 있으므로 이전 버전의 Windows(윈도우)가 앱을 제대로 실행하지 못합니다. 따라서 앱을 Windows 10, 1809 버전(10.0; Build 1773)에서 실행하려면 10.0.17763.0 값을 그대로 두거나 앱이 지원하는 다양한 값에 대해 여러 maxversion tested 요소를 추가해야 합니다.

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
        <application>
            <!-- Windows 10, version 1809 (10.0; Build 17763) -->
            <maxversiontested Id="10.0.17763.0"/>
            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />
        </application>
    </compatibility>
</assembly>