외부 위치로 패키징되거나 패키징되지 않은 프레임워크 종속 앱을 위한 Windows 앱 SDK 배포 가이드
이 항목에서는 외부 위치로 패키지되거나 패키지되지 않은 앱을 배포하고 Windows 앱 SDK 사용하는 앱을 배포하는 방법에 대한 지침을 제공합니다.
- 이러한 앱은 데스크톱 앱(UWP 앱 아님)입니다.
- C#과 같은 .NET 언어 또는 C++로 작성할 수 있습니다.
- 사용자 인터페이스의 경우 WinUI 3, WPF 또는 WinForms 또는 다른 UI 프레임워크를 사용할 수 있습니다.
개요
외부 위치 및 패키지되지 않은 앱으로 패키지된 개발자는 최종 사용자에게 필요한 Windows 앱 SDK 런타임 패키지를 배포해야 합니다. 설치 관리자를 실행하거나 MSIX 패키지를 직접 설치하여 이 작업을 수행할 수 있습니다. 이러한 옵션은 아래 Windows 앱 SDK 런타임 배포 섹션에서 자세히 설명합니다.
외부 위치와 패키지되지 않은 앱으로 패키지된 앱에도 추가 런타임 요구 사항이 있습니다. 부트스트래퍼 API를 사용하여 Windows 앱 SDK 런타임에 대한 액세스를 초기화해야 합니다. 또한 앱에서 Windows 앱 SDK 제외한 다른 프레임워크 패키지를 사용하는 경우 동적 종속성 API를 사용할 수 있습니다. 이러한 요구 사항은 외부 위치 또는 아래의 패키지되지 않은 섹션으로 패키지된 앱에 대한 런타임 요구 사항에 자세히 설명되어 있습니다.
필수 조건
- 최신 설치 프로그램 & MSIX 패키지 다운로드.
- 외부 위치로 패키지되거나 패키지되지 않은 앱의 경우 Visual C++ 재배포 가능 패키지 요구 사항입니다. 자세한 내용은 Microsoft Visual C++ 재배포 가능 패키지 최신 지원 다운로드를 참조하세요.
- C#. .NET 6 이상이 필요합니다. 자세한 내용은 .NET 다운로드를 참조하세요.
추가 필수 조건
- Windows App SDK Experimental 및 미리 보기 버전을 사용하려면 테스트용 로드를 사용하도록 설정하여 런타임을 설치해야 합니다.
Windows 10 버전 2004 이상에서는 테스트용 로드가 자동으로 사용됩니다.
개발 컴퓨터 또는 배포 컴퓨터에서 Windows 11을 실행 중인 경우 테스트용 로드를 사용하도록 설정했는지 확인합니다.
- 설정>프라이버시 & 보안>개발자용. 이 개발자 모드 설정이 켜져 있는지 확인하세요.
개발 컴퓨터 또는 배포 컴퓨터에서 Windows 10 버전 1909 이하를 실행 중인 경우 테스트용 로드를 사용하도록 설정했는지 확인합니다.
- 설정>, & 보안 업데이트>개발자용>개발자 기능 사용. 해당 테스트용 로드 앱 또는 개발자 모드가 선택되어 있는지 확인합니다.
이 개발자 모드 설정에는 사이드로드뿐만 아니라 다른 기능이 포함됩니다.
참고 항목
컴퓨터가 엔터프라이즈 환경에서 관리되는 경우 이러한 설정이 변경되지 않도록 하는 정책이 있을 수 있습니다. 이 경우 사용자 또는 앱이 Windows 앱 SDK 런타임을 설치하려고 할 때 오류가 발생하면 IT 전문가에게 문의하여 사이드로드 또는 개발자 모드를 사용하도록 설정합니다.
Windows 앱 SDK 런타임 배포
외부 위치와 패키지되지 않은 앱으로 패키지된 앱에는 Windows 앱 SDK 런타임을 배포하는 두 가지 옵션이 있습니다.
- 옵션 1: 설치 관리자 사용: 자동 설치 관리자는 모든 Windows 앱 SDK MSIX 패키지를 배포합니다. 각 및 아키텍처에 대해 별도의 설치 관리자를
X64
X86
Arm64
사용할 수 있습니다. - 옵션 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 이미 설치되어 있는지(그리고 있는 경우 어떤 버전인지) 확인하려면 PackageManager.FindPackagesForUserWithPackageTypes를 호출하여 특정 패키지 패밀리를 확인할 수 있습니다.
중간IL(완전 신뢰) 패키지되지 않은 프로세스(애플리케이션 요소 참조)에서 다음 코드를 사용하여 현재 사용자에게 등록된 패키지를 확인할 수 있습니다.
using Windows.Management.Deployment;
public class WindowsAppSDKRuntime
{
public static IsPackageRegisteredForCurrentUser(
string packageFamilyName,
PackageVersion minVersion,
Windows.System.ProcessorArchitecture architecture,
PackageTypes packageType)
{
ulong minPackageVersion = ToVersion(minVersion);
foreach (var p : PackageManager.FindPackagesForUserWithPackageTypes(
string.Empty, packageFamilyName, packageType)
{
// Is the package architecture compatible?
if (p.Id.Architecture != architecture)
{
continue;
}
// Is the package version sufficient for our needs?
ulong packageVersion = ToVersion(p.Id.Version);
if (packageVersion < minPackageVersion)
{
continue;
}
// Success.
return true;
}
// No qualifying package found.
return false;
}
private static ulong ToVersion(PackageVersion packageVersion)
{
return ((ulong)packageVersion.Major << 48) |
((ulong)packageVersion.Minor << 32) |
((ulong)packageVersion.Build << 16) |
((ulong)packageVersion.Revision);
}
}
위의 시나리오에서는 FindPackagesForUserWithPackageTypes를 호출하는 것이 FindPackagesForUser를 호출하는 것이 좋습니다. 이는 검색 범위를 프레임워크 또는 기본 패키지로 좁힐 수 있기 때문입니다. 이렇게 하면 이 예제에 관심이 없는 다른 유형의 패키지(예: 리소스, 선택 사항 또는 번들)와 일치하지 않습니다.
현재/호출 사용자 컨텍스트를 사용하려면 userSecurityId 매개 변수를 빈 문자열로 설정합니다.
그리고 이제 위의 코드 예제에서 함수를 호출하는 방법을 결정하는 데 도움이 되는 몇 가지 정보가 있습니다. 올바르게 설치된 런타임은 시스템의 CPU 아키텍처에 종속된 여러 패키지로 구성됩니다.
- x86 컴퓨터: Fwk=[x86], Main=[x86], Singleton=[x86], DDLM=[x86].
- x64 컴퓨터: Fwk=[x86, x64], Main=[x64], Singleton=[x64], DDLM=[x86, x64].
- arm64 컴퓨터: Fwk=[x86, x64, arm64], Main=[arm64], Singleton=[arm64], DDLM=[x86, x64, arm64].
Main 및 Singleton 패키지의 경우 해당 아키텍처는 시스템의 CPU 아키텍처(예: x64 시스템의 x64 패키지)와 일치해야 합니다. 프레임워크 패키지의 경우 x64 시스템은 x64 및 x86 앱을 모두 실행할 수 있으며, 마찬가지로 arm64 시스템은 arm64, x64 및 x86 앱을 실행할 수 있습니다. DDLM 패키지 검사는 프레임워크 검사PackageType=main
와 유사하며, packagefamilyname은 다르며 DDLM의 고유한 명명 체계로 인해 둘 이상의(다른) packagefamilyname을 적용할 수 있습니다. 자세한 내용은 MSIX 패키지 사양을 참조 하세요 . 따라서 검사는 다음과 같습니다.
public static bool IsRuntimeRegisteredForCurrentUser(PackageVersion minVersion)
{
ProcessorArchitecture systemArchitecture = DetectSystemArchitecture();
return IsFrameworkRegistered(systemArchitecture, minVersion) &&
IsMainRegistered(systemArchitecture, minVersion) &&
IsSingletonRegistered(systemArchitecture, minVersion) &&
IsDDLMRegistered(systemArchitecture, minVersion);
}
private static ProcecssorArchitecture DetectSystemArchitecture()
{
// ...see the call to IsWow64Process2(), and how the result is used...
// ...as per `IsPackageApplicable()` in
// [install.cpp](https://github.com/microsoft/WindowsAppSDK/blob/main/installer/dev/install.cpp)
// line 99-116...
// ...WARNING: Use IsWow64Process2 to detect the system architecture....
// ... Other similar APIs exist, but don't give reliably accurate results...
}
private static bool IsFrameworkRegistered(ProcessorArchitecture systemArchitecture,
PackageVersion minVersion)
{
// Check x86.
if (!IsPackageRegisteredForCurrentUser(
global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
minVersion, ProcessorArchitecture.X86,
PackageTypes.Framework))
{
return false;
}
// Check x64 (if necessary).
if ((systemArchitecture == ProcessorArchitecture.X64) ||
(systemArchitecture == ProcessorArchitcture.Arm64))
{
if (!IsPackageRegisteredForCurrentUser(
global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
minVersion, ProcessorArchitecture.X64,
PackageTypes.Framework))
{
return false;
}
}
// Check arm64 (if necessary).
if (systemArchitecture == ProcessorArchitcture.Arm64)
{
if (!IsPackageRegisteredForCurrentUser(
global::Microsoft.WindowsAppSDK.Runtime.Packages.Framework.PackageFamilyName,
minVersion, ProcessorArchitecture.Arm64,
PackageTypes.Framework))
{
return false;
}
}
return true;
}
private static bool IsMainRegistered(ProcessorArchitecture systemArchitecture,
PackageVersion minVersion)
{
return IsPackageRegisteredForCurrentUser(
global::Microsoft.WindowsAppSDK.Runtime.Packages.Main.PackageFamilyName,
minVersion,
systemArchitecture,
PackageTypes.Main);
}
private static bool IsSingletonRegistered(ProcessorArchitecture systemArchitecture,
PackageVersion minVersion)
{
return IsPackageRegisteredForCurrentUser(
global::Microsoft.WindowsAppSDK.Runtime.Packages.Singleton.PackageFamilyName,
minVersion,
systemArchitecture,
PackageTypes.Main);
}
private static bool IsDDLMRegistered(ProcessorArchitecture systemArchitecture,
PackageVersion minVersion)
{
// ...similar to IsFrameworkRegistered, but the packageFamilyName is more complicated...
// ...and no predefined constant is currently available...
// ...for more details, see
// https://github.com/microsoft/WindowsAppSDK/blob/main/specs/Deployment/MSIXPackages.md.
}
위의 정보 및 코드는 기본 검색 시나리오를 다룹니다. 런타임이 모든 사용자에 대해 프로비전되는지 또는 앱 컨테이너에서 위의 작업을 수행하고 패키지된 mediumIL
프로세스에서 실행하려면 추가 논리가 필요합니다.
배포 시나리오
Windows 앱 SDK 런타임 시스템 전체 설치: 시스템 전체 설치는 나중에 추가되는 새 사용자를 포함하여 모든 사용자의 컴퓨터를 변경합니다. 앱이 관리자 권한으로 실행 중이고 설치를 수행하는 사용자에게 관리자 권한이 있는 경우 설치 관리자는 ProvisionPackageForAllUsersAsync 를 호출하여 시스템 전체에 MSIX 패키지를 등록합니다. 시스템 수준 등록이 실패하는 경우 설치를 수행하는 현재 사용자에 대한 설치만 수행됩니다. 관리형 엔터프라이즈 환경의 IT 관리자는 평소처럼 모든 사용자를 프로비저닝할 수 있습니다.
Windows 앱 SDK 설치 관리자가 재배포한 아키텍처: Windows 앱 SDK 설치 관리자는 및
x64
Arm64
아키텍처에서x86
사용할 수 있습니다. 설치 관리자의 각 버전에는 명명된 특정 아키텍처에 대한 MSIX 패키지가 포함되어 있습니다. 예를 들어 x64 또는 Arm64 디바이스에서 실행하는x86
WindowsAppRuntimeInstall.exe
경우 해당x86
설치 관리자는 해당 디바이스에 x86 아키텍처용 패키지만 배포합니다.모든 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
해야 합니다.
관련 항목
Windows developer