프레임워크 종속 패키지 앱에 대한 Windows 앱 SDK 배포 가이드

이 문서에서는 Windows 앱 SDK 사용하는 프레임워크 종속 패키지 앱( MSIX?이란? 참조)을 배포하는 방법에 대한 지침을 제공합니다. 다른 프레임워크 종속 패키징 옵션에 해당하는 항목은 외부 위치와 함께 패키지되었거나 패키지되지 않은 프레임워크 종속 앱에 대한 Windows 앱 SDK 배포 가이드입니다.

Overview

기본적으로 Visual Studio WinUI 3 템플릿 중 하나를 사용하여 프로젝트를 만들 때 프로젝트는 단일 프로젝트 MSIX(단일 프로젝트 MSIX를 사용하여 앱 패키지 참조) 또는 Windows 애플리케이션 패키징 프로젝트를 사용하여 MSIX 패키지로 앱을 빌드하도록 구성됩니다(Visual Studio MSIX 패키징에 대한 데스크톱 애플리케이션 설정 참조). 그런 다음 Visual Studio 데스크톱 또는 UWP 앱 패키지의 지침을 사용하여 앱에 대한 MSIX 패키지를 빌드할 수 있습니다. 앱용 MSIX 패키지를 빌드한 후 MSIX 배포 관리하기몇 가지 옵션이 있습니다.

패키지된 앱이 Windows 앱 SDK 사용할 때 필요할 수 있는 패키지에 대한 자세한 내용은 Windows 앱 SDK 대한 배포 아키텍처를 참조하세요. 여기에는 프레임워크, Main 및 Singleton 패키지가 포함됩니다. 모두 Microsoft에서 서명하고 게시합니다. 패키지된 앱을 배포하기 위한 두 가지 주요 요구 사항이 있습니다.

  1. Windows 앱 SDK 프레임워크 패키지 배포합니다.
  2. 배포 API호출합니다.

Prerequisites

  • 패키지된 앱의 경우 VCLibs 프레임워크 패키지 종속성이 요구 사항입니다. 자세한 내용은 데스크톱 브리지 대한C++ 런타임 프레임워크 패키지를 참조하세요.
  • C#. .NET 6 이상이 필요합니다. 자세한 내용은 .NET 다운로드 참조하세요.

Windows 앱 SDK 프레임워크 패키지 배포

Windows 앱 SDK 프레임워크 패키지에는 런타임에 사용되는 Windows 앱 SDK 이진 파일이 포함되어 있으며 애플리케이션과 함께 설치됩니다. 프레임워크에는 Windows 앱 SDK 여러 채널에 대해 서로 다른 배포 요구 사항이 있습니다.

안정적인 버전

개발 컴퓨터에 Windows 앱 SDK NuGet 패키지의 안정적인 릴리스 버전을 설치하고 제공된 WinUI 프로젝트 템플릿 중 하나를 사용하여 프로젝트를 만드는 경우 생성된 패키지 매니페스트에는 프레임워크 패키지에 대한 종속성을 지정하는 PackageDependency 요소가 포함됩니다.

그러나 별도의 Windows 애플리케이션 패키징 프로젝트를 사용하여 앱 패키지를 수동으로 빌드하는 경우 다음과 같이 파일에서 Application (package).wapproj 선언해야 합니다.

<ItemGroup>
   <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.8.260209005">
       <IncludeAssets>build</IncludeAssets>
   </PackageReference>
</ItemGroup>

해당 패키지 종속성은 앱이 다른 컴퓨터에 배포될 때 프레임워크 패키지가 설치되도록 합니다.

미리 보기 버전

개발 컴퓨터에 Windows 앱 SDK NuGet 패키지의 미리 보기 릴리스 버전을 설치하면 빌드 시간 동안 Windows 앱 SDK 프레임워크 패키지의 미리 보기 버전이 NuGet 패키지 종속성으로 배포됩니다.

배포 API 호출

또한 Windows 앱 SDK 초기화를 참조하세요.

배포 API는 Windows 앱 SDK 프레임워크 패키지에서 제공되며 Microsoft.Windows.ApplicationModel.WindowsAppRuntime 네임스페이스에서 사용할 수 있습니다. Windows 애플리케이션 모델은 Main 및 Singleton 패키지에 대한 종속성 선언을 지원하지 않습니다. 따라서 다음과 같은 이유로 배포 API가 필요합니다.

  1. 프레임워크 패키지에 없는 기능에 대해 Singleton 패키지를 배포하려면(예: 푸시 알림)
  2. 기본 패키지를 배포하려면 Microsoft Store에서 프레임워크 패키지에 대한 자동 업데이트를 사용하도록 설정합니다.

스토어를 통해 배포 되지 않은 패키지된 앱의 경우 개발자는 프레임워크 패키지를 배포할 책임이 있습니다. 중요한 서비스 업데이트가 배달되도록 배포 API를 호출하는 것이 좋습니다. 프레임워크 패키지 외부의 기능(예: 푸시 알림)을 사용하려면 Singleton 패키지를 배포해야 합니다(배포 API를 사용하거나 고유한 설치 방법을 사용하여 MSIX 패키지를 재배포하여 수행할 수 있음).

Important

완전 신뢰가 있거나 packageManagement 가 제한된 기능이 있는 패키지된 앱만 배포 API를 사용하여 Main 및 Singleton 패키지 종속성을 설치할 수 있는 권한이 있습니다.

앱의 프로세스가 초기화된 후에는 배포 API를 호출해야 하지만, 앱이 Singleton 패키지를 사용하는 Windows 앱 SDK 런타임 기능(예: 푸시 알림)을 사용하기 전에 호출해야 합니다. 배포 API의 주요 메서드는 DeploymentManager 클래스의 정적 GetStatus 및 Initialize 메서드입니다.

  • GetStatus 메서드는 현재 로드된 Windows 앱 SDK 런타임의 현재 배포 상태를 반환합니다. 이 메서드를 사용하여 현재 앱에서 Windows 앱 SDK 기능을 사용하기 전에 Windows 앱 SDK 런타임 패키지를 설치하는 데 필요한 작업이 있는지 여부를 식별합니다.
  • Initialize 메서드는 필요한 모든 패키지가 현재 로드된 Windows 앱 SDK 런타임에 필요한 최소 버전에 있는지 확인합니다. 패키지 종속성이 누락된 경우 메서드는 누락된 패키지를 등록하려고 시도합니다. Windows 앱 SDK 1.1부터 Initialize 메서드는 Windows 앱 SDK 런타임 패키지를 강제로 배포하는 옵션도 지원합니다. 이렇게 하면 Main 및 Singleton 런타임 패키지에 대한 모든 프로세스가 종료되므로 해당 서비스가 중단됩니다(예: 푸시 알림은 이 시간 동안 알림을 전달하지 않음). Initialize를 한 번만 호출해야 합니다. Visual Studio의 Start Without Debugging 및 Start Debugging 명령을 통해 배포된 앱의 경우 Initialize를 호출할 필요가 없습니다.

Important

Visual Studio 속성 <WindowsAppSdkDeploymentManagerInitialize> 기본값은 true. 따라서 DeploymentManager.Initialize를 명시적으로 호출하려는 경우 Visual Studio 프로젝트 파일에서 <WindowsAppSdkDeploymentManagerInitialize>false</WindowsAppSdkDeploymentManagerInitialize> 설정합니다.

배포 API 샘플 앱

DeploymentManager 클래스의 GetStatus 및 Initialize 메서드를 사용하는 방법에 대한 추가 지침은 사용 가능한 샘플 앱을 살펴보세요.

배포 API 샘플 앱을 탐색하십시오

설치 오류를 해결하다

Windows 앱 SDK 런타임 패키지를 설치하는 동안 배포 API에서 오류가 발생하면 문제를 설명하는 오류 코드를 반환합니다.

다음 표에서는 배포 API의 일반적인 오류 코드와 일반적인 원인을 나열합니다.

오류 코드 Name 일반적 원인
0x80070005 ACCESS_DENIED 앱이 완전 신뢰 상태가 아니거나 packageManagement 제한된 기능이 없습니다. 관리자 권한으로 실행하거나 필요한 권한을 추가하세요.
0x80073CF0 ERROR_INSTALL_OPEN_PACKAGE_FAILED MSIX 패키지가 손상되었거나 액세스할 수 없습니다. 패키지 파일이 그대로 유지되고 경로가 올바른지 확인합니다.
0x80073CF3 ERROR_INSTALL_PREREQUISITE_FAILED 필수 종속성 패키지가 없거나 호환되지 않습니다. VCLibs 프레임워크 패키지 및 기타 필수 구성 요소가 설치되어 있는지 확인합니다.
0x80073D06 ERROR_PACKAGES_IN_USE 하나 이상의 패키지가 사용 중이며 업데이트할 수 없습니다. Windows 앱 SDK 런타임을 사용하여 모든 앱을 닫은 다음 다시 시도합니다.
0x80073CFB ERROR_PACKAGE_ALREADY_EXISTS 패키지 버전이 이미 등록되어 있습니다. 이는 정보 제공입니다. 앱은 계속 진행할 수 있습니다.
0x80073CF9 ERROR_INSTALL_FAILED 일반적인 설치 실패입니다. 자세한 내용은 이벤트 로그를 확인합니다(아래 참조).

팁 (조언)

MSIX 패키지 설치 오류 코드의 전체 목록은 Windows 앱의 패키징, 배포 및 쿼리 문제 해결을 참조하세요.

오류 코드가 충분한 정보를 제공하지 않는 경우 자세한 이벤트 로그에서 자세한 진단 정보를 찾을 수 있습니다(진단 정보 가져오기참조). 이벤트 로그는 애플리케이션 및 서비스 로그>Microsoft Windows>AppxDeployment-Server의 > 있습니다.

진단할 수 없는 오류가 발생하면 문제를 조사할 수 있도록 오류 코드 및 이벤트 로그와 함께 WindowsAppSDK GitHub 리포지토리에 문제를 제출합니다.

  • Last updated on