.NET 파일 기반 앱과 함께 winapp CLI 사용

실제 예제는 dotnet-file-app 샘플을 참조하세요. 전체 참조 내용은 CLI 참조의 단일 파일 모드를 참조하세요.

.NET 10은 프로젝트 파일 없이 단일 .cs 파일을 실행할 수 있습니다. 이 가이드에서는 winapp run을 사용하여 해당 파일을 패키지 ID로 실행하는 방법을 보여 줍니다. 따라서 예: Windows.ApplicationModel.Package.Current, 앱 알림, 디바이스 내 AI와 같은 API가 작동합니다. 매니페스트나 이미지 자산을 직접 작성할 필요가 없습니다. winapp이 대신 생성합니다.

패키지 ID는 Windows app 모델의 핵심 개념입니다. 이를 통해 애플리케이션은 특정 Windows API에 액세스하고, 깨끗한 설치/제거 환경을 갖출 수 있습니다. dotnet run로 실행되는 파일 기반 앱에는 패키지 ID가 없습니다.

Prerequisites

1. .NET SDK 10.0.300 이상: .NET 10 SDK 설치(설치 후 다시 시작 필요):

   winget install Microsoft.DotNet.SDK.10 --source winget
   

2. winapp CLI: winget을 winapp 통해 도구를 설치합니다(또는 이미 설치된 경우 업데이트).

   winget install Microsoft.winappcli --source winget
   

1. 파일 기반 앱 만들기

다음과 같은 이름의 파일이 있는 폴더를 만듭니다 hello.cs:

#:property OutputType=Exe
#:property TargetFramework=net10.0-windows10.0.19041.0

using Windows.ApplicationModel;

try
{
    Console.WriteLine($"Package Family Name: {Package.Current.Id.FamilyName}");
}
catch (InvalidOperationException)
{
    // Thrown when the app doesn't have package identity
    Console.WriteLine("Not packaged");
}

이 #:property줄은 .csproj처럼 앱을 구성합니다. Windows TargetFramework는 코드에 다음과 같은 PackageWindows 런타임 API에 대한 액세스 권한을 부여합니다.

dotnet run로 실행하세요:

dotnet run hello.cs

Not packaged는 다음 출력입니다: 앱은 패키지 ID 없이 실행됩니다.

2. 패키지 ID를 사용하여 실행

winapp을 사용하여 동일한 파일을 실행합니다.

winapp run hello.cs

winapp은 앱을 빌드하고, 빌드 출력에서 매니페스트 및 기본 이미지 자산을 생성하고, 앱을 패키지로 등록하고, 앱을 실행합니다. 이제 출력에 패키지 ID가 표시됩니다.

Package Family Name: hello-<hash>_<publisher-hash>

원본 폴더에는 여전히 hello.cs만 포함되어 있습니다. 콘솔 앱(OutputType=Exe)이기 때문에 winapp은 실행 별칭을 통해 이를 시작하므로 출력이 터미널에 표시됩니다.

앱이 종료된 후에도 등록이 그대로 유지되므로 winapp run hello.cs을 다시 실행하면 동일한 ID가 다시 사용됩니다. 5단계에서 제거합니다.

3. 패키지 이름 지정

기본적으로 패키지 이름은 파일 이름에 파일 경로의 짧은 해시를 더한 것입니다. 자신만의 이름을 선택하려면 새 이름이 새 패키지를 등록하므로 현재 패키지 등록을 먼저 취소하세요.

winapp unregister hello.cs

그런 다음, #:property의 맨 위에 hello.cs 지시문을 추가합니다:

#:property WinAppPackageName=com.contoso.hello
#:property WinAppDisplayName=Contoso Hello
#:property Version=1.0.0

다시 실행하세요:

winapp run hello.cs

출력에는 새 이름(예: Package Family Name: com.contoso.hello_<publisher-hash>)이 표시됩니다. 앱은 시작 메뉴에도 Contoso Hello로 표시됩니다.

모든 identity 속성과 기본값은 매니페스트 속성을 참조하세요.

4. dotnet run로 실행

일반 dotnet run에서 동일한 패키지된 실행 방식을 얻으려면 Microsoft.Windows.SDK.BuildTools.WinApp 맨 위에 선언된 hello.cs 패키지를 참조하세요.

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*

dotnet run hello.cs

출력에는 winapp run와 동일한 패키지 ID가 표시됩니다. dotnet run가 다른 출력 폴더에 빌드되므로 다른 위치에서 설치된 기존 등록을 대체한다는 경고가 표시됩니다. 이는 예상되며 무시할 수 있습니다.

또한 패키지는 앱에 자리 표시자 창 아이콘을 제공하므로 창이 있는 앱은 제목 표시줄에 아이콘을 표시합니다. 자신의 파일을 사용하려면 ApplicationIcon를 ..ico 파일로 가리키세요:

#:property ApplicationIcon=Assets\MyApp.ico

이 실행을 제어하는 속성은 dotnet run로 실행을 참조하세요.

5. 정리

.cs 등록을 제거하려면 파일winapp unregister을 전달하세요:

winapp unregister hello.cs

기능 또는 사용자 지정 매니페스트 추가

일부 API에는 선언된 권한이 필요합니다. 예를 들어 Windows AI API에는 다음이 필요합니다systemAIModels.

#:property WinAppCapabilities=systemAIModels

winapp은 각 기능을 올바른 매니페스트 요소에 씁니다. 전체 목록 및 명명 규칙에 대한 Capabilities를 참조하세요.

프로토콜 처리기, 파일 연결 및 기타 셸 통합에는 작성된 매니페스트가 필요합니다. hello.appxmanifest 옆에 hello.cs을 두면 winapp은 하나를 생성하는 대신 그것을 사용합니다. 사용자 고유의 매니페스트 가져오기를 참조하세요.

다음 단계

• 배포용 패키지: winapp run 앱을 개발 전용으로만 등록합니다. 배송할 수 있는 MSIX를 생성하려면 코드를 프로젝트에 옮기고 .NET 가이드에서 Package with MSIX를 따릅니다.
• Explore Windows API들: 패키지 ID로, 이제 알림, 기기 내 AI 및 기타 ID에 의존하는 API을 사용할 수 있습니다.