有关工作示例,请参阅 dotnet-file-app 示例。 有关完整参考,请参阅 CLI 参考中的 单文件模式 。
.NET 10 可以运行没有项目文件的单个.cs文件。 本指南演示如何使用 winapp run 以包标识运行该文件,从而确保 Windows.ApplicationModel.Package.Current 等 API、应用通知以及设备端 AI 功能正常工作。 你无需编写清单文件或图像资源:winapp 会为你生成它们。
包标识是Windows app模型中的核心概念。 它允许应用程序访问特定的 Windows API、提供简洁的安装/卸载体验等。 使用 dotnet run 运行的基于文件的应用没有包标识。
Prerequisites
.NET SDK 10.0.300 或更高版本:安装 .NET 10 SDK(安装后需要重启):
winget install Microsoft.DotNet.SDK.10 --source wingetwinapp 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 将直接使用该文件,而不再生成默认清单。 请参阅自带清单。
后续步骤
-
打包分发:
winapp run仅用于开发环境下的应用注册。 若要生成可交付的 MSIX,请将代码移至项目中,并按照 .NET 指南中的 使用 MSIX 打包 操作。 - 探索 Windows API:具有包标识,你现在可以使用通知、设备端 AI 和其他依赖标识的 API