生成第一个 WinUI 应用

构建你的第一个 WinUI 应用，并在 Windows 上看到它运行。 本快速入门将带你完成从工具设置到应用运行的过程，然后指导你完成第一次界面更新。

在您开始之前

您将了解到的内容

• 选择并设置开发工具。
• 创建并运行 WinUI 应用。
• 更新界面并在正在运行的应用中看到你的更改。

选择开发工具

按照本快速入门中的任意一条推荐路径操作：

• winapp CLI：在您首选的编辑器中通过终端工作。 此命令行工作流也非常适合智能体编程。
• Visual Studio：使用集成式开发和调试体验。

如果您的工具已经安装，请转到 创建您的第一个应用。

安装工具

winapp CLI

1. 启用 开发人员模式。 可以使用 开发者设置 打开其设置。

2. 安装 .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
   

   如果所需工具已安装，请跳过安装。

3. 打开一个新终端以使其识别已安装的命令，然后检查版本：

   dotnet --version
   winapp --version
   

   此工作流需使用 .NET SDK 10 或更高版本以及 winapp CLI 0.6 或更高版本。

注释

winapp CLI 目前处于公开预览阶段。 winapp new管理 WinUI 项目模板，但它不安装.NET SDK。 有关新的项目创建命令和运行命令，请参阅 CLI 0.6 公告。

Visual Studio

安装 Visual Studio 2026 并选择 WinUI 应用开发 工作负载，然后启用 开发人员模式。

使用 WinGet 设置

打开 Windows 终端，然后运行此 PowerShell 命令，以安装所需的 Visual Studio 工作负载，并通过 WinGet 配置文件启用开发人员模式：

winget configure -f https://aka.ms/winui-config

您可以在 配置 README 中查阅该配置及其相关要求。

手动设置

如果你希望手动设置或没有 WinGet：

1. 启用 开发人员模式。

2. 下载并安装 Visual Studio 2026。

3. 在 Visual Studio 安装程序中，选择 WinUI 应用程序开发工作负载。

   

创建第一个应用

使用你在上面安装的工作流创建并启动该项目。

winapp CLI

从存放项目的文件夹中运行：

winapp new --name MyWinUIApp --template winui --use-defaults
cd MyWinUIApp
winapp run

winapp new 创建一个空白的 WinUI 应用。 winapp run 会构建项目并启动它；你不需要单独的构建或包注册命令。

Visual Studio

1. 打开 Visual Studio，然后选择创建新项目。

2. 搜索 WinUI，选择 WinUI 空白应用（打包） C# 模板，然后选择 下一步。

   

3. 将 project MyWinUIApp 命名，然后选择 Create。

4. 按 F5 生成并运行应用。

你的应用将打开一个桌面窗口。 继续下面的 进行更改。

做出更改

保留刚创建的项目。 向其现有界面添加一条消息：

1. 关闭正在运行的应用。 在编辑器中打开 MainPage.xaml 。 如果模板不包含该文件，请改为打开 MainWindow.xaml 。

2. 查找保存应用内容的布局面板。 在当前 CLI 空白模板中， MainPage.xaml 包含一个空 <Grid />。 将那个空白网格替换为：

   <Grid>
       <TextBlock
           Text="Hello, WinUI!"
           HorizontalAlignment="Center"
           VerticalAlignment="Center" />
   </Grid>
   

   如果面板已包含控件，则只在该面板内添加 TextBlock。 保留现有控件、名称和事件处理程序。 不要替换外层的 Page 或 Window，也不要替换 MainWindow.xaml 中的框架控件和标题栏。

3. 保存文件。 从项目文件夹中再次运行 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 的模板中，将消息添加到该页面，而不是替换窗口中承载页面的框架控件。

后续步骤

构建笔记应用

笔记应用教程使用单独的 WinUINotes 项目来教授页面、导航、数据绑定和本地存储。 还可以在 代码示例和 WinUI Gallery中找到重点控件示例。