将 winapp CLI 与基于文件的.NET应用配合使用

有关工作示例,请参阅 dotnet-file-app 示例。 有关完整参考,请参阅 CLI 参考中的 单文件模式 。

.NET 10 可以运行没有项目文件的单个.cs文件。 本指南演示如何使用 winapp run 以包标识运行该文件,从而确保 Windows.ApplicationModel.Package.Current 等 API、应用通知以及设备端 AI 功能正常工作。 你无需编写清单文件或图像资源:winapp 会为你生成它们。

包标识是Windows app模型中的核心概念。 它允许应用程序访问特定的 Windows API、提供简洁的安装/卸载体验等。 使用 dotnet run 运行的基于文件的应用没有包标识。

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 文件。 WindowsTargetFramework使代码能够访问 Windows 运行时 API(例如Package)。

使用 dotnet run 运行:

dotnet run hello.cs

输出为 Not packaged:应用在没有包标识的情况下运行。

2. 以包标识运行

使用 winapp 运行同一文件:

winapp run hello.cs

winapp 生成应用,在构建输出中生成清单和默认映像资产,将应用注册为包,然后启动它。 输出现在显示包标识:

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

源文件夹中仍然只有 hello.cs。 由于这是控制台应用(OutputType=Exe),winapp 通过执行别名启动它,因此其输出将显示在终端中。

注册在应用退出后保持不变,因此再次运行 winapp run hello.cs 会重复使用相同的标识。 在 步骤 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 形式显示在“开始”菜单中。

有关每个标识属性及其默认值,请参阅 清单属性。

4. 使用 dotnet run 运行

若要通过普通的dotnet run获得相同的打包启动方式,请在hello.cs文件顶部引用Microsoft.Windows.SDK.BuildTools.WinApp包:

#:package Microsoft.Windows.SDK.BuildTools.WinApp@*
dotnet run hello.cs

输出显示与 winapp run 相同的包标识。 由于 dotnet run 会输出到不同的生成目录,因此会提示正在替换从其他位置安装的现有注册。 这是预期的,你可以忽略它。

该包还会为应用提供占位符窗口图标,因此窗口化应用在其标题栏中显示图标。 若要使用自定义图标,请将 ApplicationIcon 指向一个 .ico 文件:

#:property ApplicationIcon=Assets\MyApp.ico

有关控制此启动的属性,请参阅“使用dotnet run运行”。

5. 清理

通过向 winapp unregister 传递 .cs 文件以移除注册:

winapp unregister hello.cs

添加功能或自定义清单

部分 API 需声明相应功能。 例如,Windows AI API 需要systemAIModels:

#:property WinAppCapabilities=systemAIModels

winapp 将每个功能声明写入正确的清单元素。 请参阅Capabilities,了解完整列表和命名规则。

协议处理程序、文件关联及其他 Shell 集成功能需提供自定义清单。 将 hello.appxmanifest 置于 hello.cs 旁,winapp 将直接使用该文件,而不再生成默认清单。 请参阅自带清单。

后续步骤