构建你的第一个 WinUI 应用,并在 Windows 上看到它运行。 本快速入门将带你完成从工具设置到应用运行的过程,然后指导你完成第一次界面更新。
您将了解到的内容
- 选择并设置开发工具。
- 创建并运行 WinUI 应用。
- 更新界面并在正在运行的应用中看到你的更改。
选择开发工具
按照本快速入门中的任意一条推荐路径操作:
- winapp CLI:从首选编辑器中的终端工作。 此命令行工作流也非常适合智能体编程。
- Visual Studio:使用集成开发和调试体验。
如果您的工具已经安装,请转到 创建您的第一个应用。
安装工具
安装 .NET 10 SDK 和 Windows 应用 Development CLI。 如果使用 WinGet,请运行:
winget install --id Microsoft.DotNet.SDK.10 --exact --source winget winget install --id Microsoft.WinAppCli --exact --source winget如果所需工具已安装,请跳过安装。
打开一个新终端以使其识别已安装的命令,然后检查版本:
dotnet --version winapp --version此工作流需使用 .NET SDK 10 或更高版本以及 winapp CLI 0.6 或更高版本。
注释
winapp CLI 目前处于公开预览阶段。
winapp new管理 WinUI 项目模板,但它不安装.NET SDK。 有关新的项目创建命令和运行命令,请参阅 CLI 0.6 公告。
创建第一个应用
使用你在上面安装的工作流创建并启动该项目。
从存放项目的文件夹中运行:
winapp new --name MyWinUIApp --template winui --use-defaults
cd MyWinUIApp
winapp run
winapp new 创建空白 WinUI 应用。
winapp run 生成项目并启动它;不需要单独的生成或包注册命令。
若要从命令行选择其他初学者模板、调试崩溃、自动化 UI 或打包应用,请参阅 将 winapp CLI 与 WinUI 配合使用。
你的应用将打开一个桌面窗口。 继续下面的 进行更改。
做出更改
保留刚创建的项目。 向其现有界面添加一条消息:
关闭正在运行的应用。 在编辑器中打开
MainPage.xaml。 如果模板不包含该文件,请改为打开MainWindow.xaml。查找保存应用内容的布局面板。 在当前 CLI 空白模板中,
MainPage.xaml包含一个空<Grid />。 将那个空白网格替换为:<Grid> <TextBlock Text="Hello, WinUI!" HorizontalAlignment="Center" VerticalAlignment="Center" /> </Grid>如果面板已包含控件,则只在该面板内添加
TextBlock。 保留现有控件、名称和事件处理程序。 不要替换外层的Page或Window,也不要替换MainWindow.xaml中的框架控件和标题栏。保存文件。 从项目文件夹中再次运行
winapp run,或在 Visual Studio 中按 F5。
恭喜! 你已创建、运行和更新了第一个 WinUI 应用。 窗口现在显示 Hello,WinUI!
Troubleshooting
| 问题 | 需要检查的事项 |
|---|---|
winapp 或 dotnet 未被识别。 |
安装后重新打开终端。 使用 CLI 选项卡中的版本命令确认这两种工具都可用。 |
winapp new 未被识别。 |
此工作流需要 winapp CLI 0.6 或更高版本。 使用所选的安装方法更新 CLI。 |
| WinUI 模板未出现在 Visual Studio 中。 | 打开 Visual Studio 安装程序,选择 修改,并确认已安装 WinUI 应用程序开发 工作负载。 事后重启Visual Studio。 |
| 生成过程报告了 SDK 或还原错误。 | 检查所选工作流的先决条件以及生成输出中的第一个错误。 使用Windows 应用 SDK 支持在更改项目属性之前检查版本要求。 |
| 部署时报告开发者模式已禁用。 | 启用 开发人员模式,然后再次运行应用。 |
| 你的新消息未出现。 | 保存 XAML 文件并重新启动项目。 在带有 MainPage.xaml 的模板中,将消息添加到该页面,而不是替换窗口中承载页面的框架控件。 |
共享应用
当你准备好将你的应用交到用户手中时,可以选择如何分发它。 无需使用 Microsoft Store;这是多个选项中的一个选项:
-
直接共享:从自己的网站或GitHub发布分发 MSIX 包、安装程序或 .zip 文件。 还可以通过
winget install使应用可安装。 您处理代码签名和更新。 - 通过Microsoft Store发布:在应用商店中获取发现、受信任的安装体验、MSIX 包的免费签名和自动更新。
发布你的第一个Windows应用将介绍这两种方式,包括代码签名、打包以及首批用户将看到的内容。 若要并排比较每个选项,请参阅 “选择分发路径”。
后续步骤
笔记应用教程使用单独的 WinUINotes 项目来教授页面、导航、数据绑定和本地存储。
如果你在终端工作,将 winapp CLI 与 WinUI 配合使用涵盖了完整的命令行工作流:模板、dotnet run、调试、UI 自动化、测试和打包。
你还可以在代码示例和 WinUI 库中查找聚焦控件示例。
当您准备好让其他人使用您的应用时,发布您的第一个 Windows 应用会显示如何直接或通过 Microsoft Store 共享应用。