C# 使用 WinUI 3 项目模板创建桌面应用程序

文章目录

1. 概述
2. 先决条件
3. 创建项目步骤
4. 项目结构简介
5. 代码示例
- 5.1. `MainWindow.xaml` (UI 定义)
- 5.2. `MainWindow.xaml.cs` (逻辑代码)
6. 生成和运行应用程序
7. 关键概念

1. 概述

本示例演示如何使用 Visual Studio 中的 “Blank App, Packaged (WinUI 3 in Desktop)” C# 项目模板创建一个简单的 WinUI 3 桌面应用程序。这个应用程序将包含一个按钮和一个文本块，点击按钮后，文本块的内容会发生改变。

2. 先决条件

Visual Studio 2022 或更高版本： 确保已安装 “.NET Multi-platform App UI development” (MAUI) 工作负载，或者至少是 “Universal Windows Platform development” 工作负载，并确保 WinUI 3 模板可用。通常，安装最新的 Windows App SDK 扩展会自动添加这些模板。
Windows App SDK： 确保已安装最新版本的 Windows App SDK。Visual Studio 安装程序通常会处理这个问题。
启用开发者模式： 在 Windows 设置中启用开发者模式（设置 -> 更新和安全 -> 开发者选项 -> 开发者模式）。

3. 创建项目步骤

（1）打开 Visual Studio。
（2）点击 “创建新项目 (Create a new project)”。
（3）在搜索框中输入 “WinUI”。
（4）选择 C# 版本的 空白应用，已打包（桌面版中的WinUI 3） 即 “Blank App, Packaged (WinUI 3 in Desktop)” 模板。
* 注意： 不要选择 UWP 版本的模板，也不要选择 “Blank App, Packaged with WAP (WinUI 3 in Desktop)”（除非你有特定需求并了解其差异）。

项目模板
（5）给项目命名（例如 MyWinUI3AppCS），选择一个位置，然后点击 “创建 (Create)”。

创建项目

（6） Visual Studio 可能会提示你选择目标 Windows 版本和最低 Windows 版本。通常可以接受默认设置。

4. 项目结构简介

创建项目后，你会看到以下关键文件和文件夹：

App.xaml / App.xaml.cs: 应用程序的入口点。App.xaml.cs 中的 OnLaunched 方法负责创建和显示主窗口。
MainWindow.xaml / MainWindow.xaml.cs: 应用程序的主窗口。
- MainWindow.xaml: 定义窗口的 UI 布局（使用 XAML）。
- MainWindow.xaml.cs: 包含窗口的逻辑代码（C#）。
Package.appxmanifest: 应用程序包的清单文件，包含应用程序的元数据、功能声明等。

5. 代码示例

我们将修改 MainWindow.xaml 和 MainWindow.xaml.cs。

5.1. `MainWindow.xaml` (UI 定义)

打开 MainWindow.xaml 文件，将其内容替换为以下 XAML 代码：

<Windowx:Class="MyWinUI3AppCS.MainWindow"xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"xmlns:local="using:MyWinUI3AppCS"xmlns:d="http://schemas.microsoft.com/expression/blend/2008"xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"mc:Ignorable="d"><StackPanel Orientation="Vertical" HorizontalAlignment="Center" VerticalAlignment="Center" Spacing="20"><TextBlock x:Name="myTextBlock" Text="Hello, WinUI 3!" FontSize="24" HorizontalAlignment="Center"/><Button x:Name="myButton" Content="Click Me" Click="MyButton_Click" HorizontalAlignment="Center"/></StackPanel>
</Window>

XAML 说明：

<Window>: 应用程序的主窗口根元素。
<StackPanel>: 一个布局控件，将其子元素垂直（Orientation="Vertical"）或水平排列。
- HorizontalAlignment="Center" 和 VerticalAlignment="Center": 使 StackPanel 及其内容在窗口中居中。
- Spacing="20": 设置子元素之间的间距。
<TextBlock x:Name="myTextBlock">: 用于显示文本。
- x:Name="myTextBlock": 为文本块指定一个名称，以便在 C# 代码中引用它。
- Text="Hello, WinUI 3!": 初始显示的文本。
- FontSize="24": 设置字体大小。
<Button x:Name="myButton">: 一个按钮控件。
- x:Name="myButton": 为按钮指定名称。
- Content="Click Me": 按钮上显示的文本。
- Click="MyButton_Click": 指定当按钮被点击时要调用的事件处理程序方法（在 C# 代码中定义）。

5.2. `MainWindow.xaml.cs` (逻辑代码)

打开 MainWindow.xaml.cs 文件，确保它包含以下代码（模板通常会生成构造函数，我们主要添加事件处理程序）：

using Microsoft.UI.Xaml;
using Microsoft.UI.Xaml.Controls;
using Microsoft.UI.Xaml.Controls.Primitives;
using Microsoft.UI.Xaml.Data;
using Microsoft.UI.Xaml.Input;
using Microsoft.UI.Xaml.Media;
using Microsoft.UI.Xaml.Navigation;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Runtime.InteropServices.WindowsRuntime;
using Windows.Foundation;
using Windows.Foundation.Collections;// To learn more about WinUI, the WinUI project structure,
// and more about our project templates, see: http://aka.ms/winui-project-info.namespace MyWinUI3AppCS
{/// <summary>/// An empty window that can be used on its own or navigated to within a Frame./// </summary>public sealed partial class MainWindow : Window{public MainWindow(){this.InitializeComponent();// Optional: Set a title for the windowthis.Title = "My First WinUI 3 App (C#)";}private void MyButton_Click(object sender, RoutedEventArgs e){myTextBlock.Text = "Button Clicked! Welcome!";}}
}

C# 代码说明：

public sealed partial class MainWindow : Window: 定义了 MainWindow 类，它继承自 Microsoft.UI.Xaml.Window。partial 关键字表示该类的定义分布在多个文件中（XAML 生成的代码和我们编写的代码）。
public MainWindow(): 类的构造函数。
- this.InitializeComponent();: 非常重要！ 这个方法由 XAML 编译器生成，它负责加载 XAML 中定义的 UI 元素并将它们连接到代码。必须在构造函数中首先调用它。
- this.Title = "My First WinUI 3 App (C#)";: (可选) 设置窗口的标题栏文本。
private void MyButton_Click(object sender, RoutedEventArgs e): 这是在 XAML 中为按钮的 Click 事件指定的处理程序。
- myTextBlock.Text = "Button Clicked! Welcome!";: 当按钮被点击时，这行代码会通过 myTextBlock (在 XAML 中定义的 TextBlock 的 x:Name) 访问该文本块，并将其 Text 属性更改为新的字符串。

6. 生成和运行应用程序

在 Visual Studio 顶部工具栏中，确保选择了正确的启动项目（应该是你刚创建的项目）。
选择一个目标平台（例如 x64 或 x86）。
点击 “启动 (Start)” 按钮（通常是一个绿色的播放箭头）或按 F5。
应用程序将会编译并启动。你会看到一个窗口，其中包含文本 “Hello, WinUI 3!” 和一个 “Click Me” 按钮。点击按钮后，文本会变为 “Button Clicked! Welcome!”。

程序运行