使用 Winapp CLI 搭配 .NET

備註

本指南適用於大多數.NET project類型。 這些步驟已經在主控台和 UI 專案（如 WPF）中測試過。

本指南示範如何使用 winapp CLI 搭配 .NET 應用程式，進行套件識別除錯，並將應用程式打包為 MSIX。

套件身份是 Windows app 模型中的核心概念。 它讓你的應用程式能access特定的Windows介面（例如通知、安全、AI API等）、乾淨安裝/卸載體驗，還有更多功能。

先決條件

  1. .NET SDK：安裝 .NET SDK：

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

  2. winapp CLI：透過 winget 安裝工具 winapp ：

    winget install Microsoft.winappcli --source winget

1. 建立一個新的 .NET 應用程式

先建立一個簡單的 .NET 主控台應用程式：

dotnet new console -n dotnet-app
cd dotnet-app

執行它以確保一切正常：

dotnet run

2. 更新代碼以驗證身份

首先，更新你的 project 檔案，針對特定的 Windows SDK 版本。 打開dotnet-app.csproj，並更改TargetFramework：

<TargetFramework>net10.0-windows10.0.26100.0</TargetFramework>

現在替換以下 Program.cs內容：

using Windows.ApplicationModel;

try
{
    var package = Package.Current;
    var familyName = package.Id.FamilyName;
    Console.WriteLine($"Package Family Name: {familyName}");
}
catch (InvalidOperationException)
{
    Console.WriteLine("Not packaged");
}

3. 匿名運行

dotnet run

你應該看到「未包裝」這個字樣。

4. 使用 Winapp CLI 初始化專案

winapp init 指令會自動偵測 .csproj 檔案，並執行針對 .NET 的設定：

winapp init

出現提示時：

  • 套件名稱：按 Enter 接受預設
  • Publisher name：按 Enter 接受預設或輸入你的名字
  • 說明：按 Enter 接受預設或輸入描述
  • 版本：按下 "Enter" 以接受 1.0.0.0
  • 入口點：按 Enter 接受預設（dotnet-app.exe）
  • Windows App SDK setup：選擇穩定、預覽或實驗

此命令：

  • 在你的.csproj中將TargetFramework更新為支援的 Windows TFM（若需要）。
  • Adds Microsoft.WindowsAppSDK 與 Microsoft.Windows.SDK.BuildTools NuGet 套件參考
  • 為你的應用程式身份建立 appxmanifest.xml 與 Assets 資料夾

備註

與原生/C++ 專案不同，.NET 流程不會產生一個 winapp.yaml 檔案。 NuGet 套件是直接透過你的.csproj 進行管理。 用 dotnet restore 來還原複製後的套件。

使用身份進行除錯

  1. 建立執行檔：

    dotnet build -c Debug

  2. 套用除錯身份：

    winapp create-debug-identity .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

  3. 執行執行檔 （不要使用 dotnet run ，因為可能會重建）：

    .\bin\Debug\net10.0-windows10.0.26100.0\dotnet-app.exe

您應該看到：

Package Family Name: dotnet-app_12345abcde

自動化偵錯識別（可選）

將此目標加入你的 .csproj 檔案：

<Target Name="ApplyDebugIdentity" AfterTargets="Build" Condition="'$(Configuration)' == 'Debug'">
    <Exec Command="winapp create-debug-identity &quot;$(TargetDir)$(TargetName).exe&quot;"
          WorkingDirectory="$(ProjectDir)"
          IgnoreExitCode="false" />
</Target>

6. 使用 Windows App SDK

如果你執行了 winapp init，Microsoft.WindowsAppSDK 已經被加入為 NuGet 套件參考。 更新 Program.cs 以使用 Windows 應用程式執行階段 API:

using Windows.ApplicationModel;

class Program
{
    static void Main(string[] args)
    {
        try
        {
            var package = Package.Current;
            var familyName = package.Id.FamilyName;
            Console.WriteLine($"Package Family Name: {familyName}");

            var runtimeVersion = Microsoft.Windows.ApplicationModel.WindowsAppRuntime.RuntimeInfo.AsString;
            Console.WriteLine($"Windows App Runtime Version: {runtimeVersion}");
        }
        catch (InvalidOperationException)
        {
            Console.WriteLine("Not packaged");
        }
    }
}

7. MSIX 封裝

  1. 為發佈建置：

    dotnet build -c Release

  2. 產生開發證書：

    winapp cert generate --if-exists skip

  3. 包裝與標誌：

    winapp pack .\bin\Release\net10.0-windows10.0.26100.0 --manifest .\appxmanifest.xml --cert .\devcert.pfx

  4. 安裝憑證 （以管理員身份執行）：

    winapp cert install .\devcert.pfx

  5. 雙擊生成的.msix以進行安裝。

小提示

  • Microsoft Store 會幫你簽署 MSIX，提交前不需要先簽。
  • 你可能需要為每個架構分別安裝 MSIX 套件： dotnet build -c Release -r win-x64 或 dotnet build -c Release -r win-arm64。

自動化 MSIX 封裝（選用）

將此目標新增到您的 .csproj：

<Target Name="PackageMsix" AfterTargets="Build" Condition="'$(Configuration)' == 'Release'">
    <Exec Command="winapp pack &quot;$(TargetDir.TrimEnd('\'))&quot; --cert &quot;$(ProjectDir)devcert.pfx&quot;"
          WorkingDirectory="$(ProjectDir)"
          IgnoreExitCode="false" />
</Target>
  • Last updated on