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

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 代码：

<Window
    x: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 window
            this.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. 生成和运行应用程序

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

7. 关键概念

• XAML (Extensible Application Markup Language): 用于声明式地定义 WinUI 3 应用程序的用户界面。
• Code-Behind: 与 XAML 文件关联的 C# (或 C++) 代码文件，用于处理 UI 逻辑和事件。
• Controls: UI 的构建块，如 Button, TextBlock, TextBox, StackPanel 等。
• Events: 用户与 UI 交互时触发的动作，如按钮点击 (Click)。
• Windows App SDK: 提供了一组库和工具，使桌面应用程序能够使用现代 Windows UI (WinUI 3)、API 和平台特性。
• Packaged App: 应用程序被打包成 .msix 格式，可以通过 Microsoft Store 或旁加载方式分发和安装。

打包后的目录如下：