通过

将 winapp CLI 与 .NET 配合使用

注释

本指南适用于大多数.NET project类型。 这些步骤已使用基于控制台和基于 UI 的项目（如 WPF）进行测试。

本指南演示如何将 winapp CLI 与.NET应用程序配合使用，以包标识进行调试，并将应用程序打包为 MSIX。

包标识是Windows app模型中的核心概念。 它允许应用程序access特定的 Windows API（例如通知、安全、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.更新代码以检查标识

首先，将项目文件更新为面向特定 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 接受默认值
  • 发布者名称：按 Enter 接受默认值或输入名称
  • 说明：按 Enter 接受默认值或输入说明
  • 版本：按 Enter 接受 1.0.0.0
  • 入口点：按 Enter 接受默认值（dotnet-app.exe）
  • Windows App SDK安装程序：选择“稳定”、“预览”或“实验”

此命令：

  • 将 .csproj 中的 TargetFramework 更新为受支持的 Windows TFM（如有需要）
  • 添加 Microsoft.WindowsAppSDK 和 Microsoft.Windows.SDK.BuildTools NuGet 包引用
  • 为您应用标识创建appxmanifest.xml和Assets文件夹

注释

与本机/C++ 项目不同，.NET 流程不创建 winapp.yaml 文件。 NuGet 包直接通过你的 .csproj管理。 使用 dotnet restore 在克隆后还原包。

5. 使用身份进行调试

  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 App 运行时环境 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。

小窍门

  • 微软商店为你签署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