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. 生成和運行應用程序

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 或旁加載方式分發和安裝。

打包后的目錄如下：