春風十里不如你，全新Windows UI 3(WinUI 3) 的第一個實現Project Reunion 0.5

什么是WinUI

Windows UI庫 (WinUI) 是適用於 Windows 桌面應用程序和 UWP 應用程序的本機用戶體驗 (UX) 框架。

WinUI is a user interface layer that contains modern controls and styles for building Windows apps. As the native UI layer in Windows it embodies Fluent Design, giving each Windows app the polished feel that customers expect.

‎WinUI是一個用戶界面層，包含用於構建Windows應用的現代控件和樣式。‎‎作為Windows中的原生UI層，它體現了‎‎流暢的設計‎‎，為每個Windows應用提供了客戶所期望的拋光感覺。‎

通俗一點理解，WinUI將UWP的UI層從Windows SDK的其它部分分離，並將從Windows轉移到Nuget。現在建一個C++或C#(.NET 5)程序，再從Nuget上裝個WinUI 3的包套個UI層，一個基於Fluent Design，觸摸友好，性能無與倫比的應用程序就誕生了。

什么是WinUI 3

Windows UI庫(WinUI)3是用於構建新式Windows應用的原生用戶體驗(UX)平台。WinUI 3的此預覽版既適用於桌面/Win32應用，也適用於UWP應用，並且包含VisualStudio項目模板和NuGet包，前者有助於你開始使用基於WinUI的用戶界面構建應用，后者包含WinUI庫。

從下圖中，可以看出UI Framework技術的演進：

1992年的MFC -> 2002年的WinForms -> 2006年的WPF -> 2012年的UWP+Win UI2 Library，最終迎來了我們今天的主角WinUI 3(3rd generation of WinUI)。

從“WinUI 2”到“WinUI 3”

WinUI 2.x可以在UWP應用程序中使用，並可通過XAML Islands納入到新的或現有的桌面應用程序中。

Windows UI庫(WinUI)3是用於構建新式Windows應用的原生用戶體驗(UX)框架。 它獨立於Windows操作系統，作為Project Reunion的一部分提供。Project Reunion 0.5版本提供Visual Studio項目模板，可幫助你開始使用基於WinUI 3的用戶界面構建應用。

WinUI 3 Project Reunion 0.5是WinUI 3的第一個穩定的支持版本，可用於創建可發布到Microsoft Store的生產應用。 此版本包含了穩定性更新和常規改進，使WinUI 3能夠前向兼容，並可用於生產。

什么是Project Reunion

Project Reunion 是一組新的開發人員組件和工具，它們代表着 Windows 應用開發平台的下一步發展。 Project Reunion 提供了一組統一的 API 和工具，各種目標 Windows 10 OS 版本上的任何桌面應用都能夠一致地使用它們。

Project Reunion 不會替代現有的桌面 Windows 應用平台和框架，例如 .NET（包括 Windows 窗體和 WPF）和 C++/Win32。 而是通過一組通用的 API 和工具（開發人員可以在這些平台中使用）來對這些現有平台進行補充。

• https://github.com/microsoft/ProjectReunion

在生產環境中，支持在 MSIX 打包桌面應用（C#/.NET 5 或 C++/Win32）中使用 Project Reunion 0.5。 可將使用 Project Reunion 0.5 的打包桌面應用發布到 Microsoft Store。 對於 UWP 應用，Project Reunion 0.5 僅作為預覽版提供。 生產環境中使用的 UWP 應用不支持此版本。

Project Reunion 0.5 包含以下可在應用中使用的 API 和組件集

組件	說明
WindowsUI庫3	WindowsUI庫(WinUI)3是適用於Windows應用的下一代Windows用戶體驗(UX)平台。 此版本包含VisualStudio項目模板和NuGet包，前者有助於你開始使用基於WinUI的用戶界面構建應用，后者包含WinUI庫。
使用MRTCore管理資源	MRTCore提供API來加載和管理你的應用所使用的資源。 MRTCore是新式 Windows資源管理系統的簡化版本。
使用DWriteCore呈現文本	通過DWriteCore，你可以獲取用於呈現文本的所有當前DirectWrite功能，包括與設備無關的文本布局系統、硬件加速文本、多格式文本和廣泛的語言支持。

面向Windows開發人員的Project Reunion優勢

Project Reunion提供了各種Windows API，其實現與OS分離，並通過NuGet包發布給開發人員。Project Reunion並不打算替換Windows SDK。Windows SDK將繼續按原樣工作，並且Windows的許多核心組件將通過API不斷改進，這些API通過OS和Windows SDK版本發布。建議開發人員按照自己的進度采用Project Reunion。

在不同的桌面應用平台中實現統一的API圖面

想要創建桌面Windows應用的開發人員必須在多個應用平台和框架之間進行選擇。盡管每個平台都提供了許多可供使用其他平台構建的應用使用的功能和API，但是某些功能和API僅供特定平台使用。Project Reunion統一了所有桌面Windows 10應用對Windows API的訪問。無論選擇哪種應用模型，你都可以訪問ProjectReunion中提供的同一組Windows API。
隨着時間的推移，我們計划對Project Reunion進行進一步的投資，以減少不同應用模型之間的差異。Project Reunion將同時提供WinRT API和本機CAPI。

在多個Windows 10版本中實現一致的支持

隨着Windows API隨新OS版本的發展而不斷發展，開發人員必須使用版本自適應代碼等技術來解決版本中的所有差異，以吸引其應用程序受眾。這可能會增加代碼和開發體驗的復雜性。

Project Reunion API適用於Windows 10版本1809以及Windows 10的所有更高版本。這意味着，只要你的客戶使用的是Windows 10版本1809或任何更高版本，就可以在新的Project Reunion API和功能發布后立即使用，而無需編寫版本自適應代碼。

加快發布節奏

新的Windows API和功能通常與每年以一次或兩次的節奏發布的OS版本相關。Project Reunion將以更快的節奏發布更新，使你能夠在創建Windows開發平台后更早、更快地訪問這些創新。

ASTA到STA線程模型

如果要將代碼從現有UWP應用遷移到使用Project Reunion的新C#/.NET5或C++/Win32/WinUI3項目，請注意，新項目使用單線程單元(STA)線程模型，而不是UWP應用使用的應用程序STA(ASTA)線程模型。如果代碼采用ASTA線程模型的非可重入行為，則代碼可能不會按預期方式運行。

WinUI 3路線圖

控件和特性

• * Coming to a future version of WinUI 3.
• ** Work in progress.

兼容性/特性	WinUI 3	UWP XAML & WinUI 2	WPF	WinForms	MFC
Windows app types supported	UWP (Preview) and Win32	UWP	Win32	Win32	Win32
Windows versions supported	Windows 10 (1809+)	Windows 10 (1703+)	Windows XP or higher	Windows XP or higher	Windows XP or higher
Supported on all Windows device families	√*	√
Native C/C++	√	√			√
.NET 5 Support	√		√	√
WebView2 (Chromium-based engine)	√		√**	√**
Built-in Fluent Design controls	√	√
Built-in support for modern input (e.g. touch, pen, gamepad*)	√	√
Uses latest DirectX version for graphics performance	√	√
High performance data binding (x:Bind)	√	√
Input Validation	√		√	√	√

WinUI 3控件庫

查看WinUI 3控件庫（以前稱為 XAML控件庫 - WinUI 3版本）以獲取示例應用，該示例應用包含屬於WinUI 3 Project Reunion 0.5的所有控件和功能。

git clone --single-branch --branch winui3 https://github.com/microsoft/Xaml-Controls-Gallery.git

git checkout winui3

Visual Studio支持

VS 版本	WinUI 3 - Project Reunion 0.5
16.8	否
16.9	是，但沒有熱重載、實時可視化樹或實時屬性資源管理器功能
16.10 預覽版	是，具有所有 WinUI 3 工具

開發環境要求

1. 確保開發計算機上已安裝Windows 10版本1809（內部版本17763）或更高版本的OS。

2. 如果尚未安裝Visual Studio 2019版本16.10預覽版（或更高版本），請先安裝。

1）安裝Visual Studio時，必須包含以下組件：

• 在安裝對話框的“工作負載”選項卡上，確保選擇了“通用 Windows 平台開發”。
• 在安裝對話框的“單個組件”選項卡上，確保在“SDK、庫和框架”部分選擇了Windows 10 SDK(10.0.19041.0)。

2）要構建.NET應用，還必須包含以下組件：

• 在安裝對話框的“工作負載”選項卡上，確保選擇了“.NET桌面開發”。

3）要構建C++應用，還必須包含以下組件：

• 在安裝對話框的“工作負載”選項卡上，確保選擇了“C++桌面開發”。
• 在安裝對話框右側的“安裝詳細信息”窗格中，確保在“通用Windows平台開發”部分選擇了“C++(v142)通用Windows平台工具”可選組件。

3. 如果以前安裝了VisualStudio的WinUI3預覽版擴展，請卸載該擴展。

4. 請確保系統中已為正式NuGet服務索引啟用了NuGet包源https://api.nuget.org/v3/index.json。

a. 在VisualStudio中，選擇"工具""->NuGet包管理器->包管理器設置"以打開"選項"對話框。

b. 在"選項"對話框的左窗格中，選擇"包源"選項卡，並確保將指向的nuget.org的包源https://api.nuget.org/v3/index.json作為源URL。

5. 下載並安裝適用於VisualStudio的項目Project Reunion 0.5擴展。擴展有兩個版本：一個用於桌面(c#/.NET5或c++/WinRT)應用，另一個用於UWP應用。

Project Reunion 0.5 發行版有兩個可用的 Visual Studio 擴展：Project Reunion VSIX 和 Project Reunion 預覽 VSIX 。 Project Reunion VSIX 包含可用於生成 MSIX 打包桌面生產應用的項目模板。 Project Reunion 預覽 VSIX 包含可用於生成 MSIX 打包桌面應用或 UWP 應用的實驗性項目模板。

若要在desktop中使用Project Reunion(c#/.NET5或c++/WinRT)應用：

• 在VisualStudio2019中，單擊“擴展”>“管理擴展”，搜索Project Reunion，然后安裝Project Reunion擴展。
• 或者，可以直接從Visual Studio Marketplace下載並安裝項目Project Reunion 0.5擴展。

若要在UWP應用中使用Project Reunion，你必須安裝不支持在生產環境中使用的擴展預覽版本：

• 卸載項目的任何現有版本。
• 在VisualStudio2019中，單擊"擴展"">管理擴展"，然后單擊左下角的"更改擴展設置"。安裝舊版本之前，請關閉為所有用戶安裝的包的自動更新。
• 下載並安裝項目Project Reunion 0.5預覽擴展。

安裝完成之后，我們新建項目就能看到關於WinUI 3的新項目模板了。

6. 若要在Visual Studio 2019 16.10 Preview中使用WinUI 3工具（如"實時可視化樹"、"熱重載"和"實時屬性資源管理器"），必須使用Visual Studio預覽功能啟用WinUI 3工具。

1. Navigate to the Preview Features page by going to Tools -> Options -> Environment -> Preview Features
2. Click on "Enable UI Debugging Tooling for WinUI 3 Projects"
3. Click on OK

7. 若要接收來自最新穩定版本的項目Project Reunion 0.5的所有修補程序，需要將.NET SDK顯式設置為最新版本。為此，請將以下項組添加到.csproj文件中，並保存項目。

<ItemGroup>            
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.18362.16" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.18362.16" />
</ItemGroup>

8. 如果你在使用擴展應用Reshaper，建議最好更新到最新版為好

• JetBrains.dotUltimate.2021.1.1.exe

創建使用Project Reunion的新項目

適用於Visual Studio 2019(包含適用於"桌面應用"和"UWP應用的預覽擴展"的擴展的項目"0.5擴展")提供使用基於WinUI 3的UI層生成項目的項目模板，並提供對所有其他項目的所有其他Api的訪問權限。

支持在生產環境中使用的桌面 (c #/.NET 5 和 c + +/WinRT) 項目模板。 UWP 項目模板僅作為開發人員預覽版提供，不能用於生成適用於生產環境的應用。

創建項目后，除了桌面和 UWP 應用常用的所有其他 Windows 和 .NET API 之外，你還可以使用以下 Project Reunion API 和組件

• Windows UI 庫 3: https://docs.microsoft.com/zh-cn/windows/apps/winui/winui3/
• 使用 MRT Core 管理資源: https://docs.microsoft.com/zh-cn/windows/apps/project-reunion/mrtcore/mrtcore-overview
• 使用 DWriteCore 呈現文本: https://docs.microsoft.com/zh-cn/windows/apps/project-reunion/dwritecore

創建適用於C#和.NET 5的WinUI 3桌面應用

1. 打開Visual Studio 2019 Preview 16.10，選擇創建新項目。

2. 選擇一個基於WinUI 3桌面的空白模板。

3. 輸入項目名字demoDesktopInWinUi3，點擊創建按鈕。

4. 在下面的對話框中，將“目標版本”設置為Windows 10 版本 2004（內部版本 19041），並將“最低版本”設置為Windows 10 版本 1809（內部版本 17763），然后單擊“確定” 。

因為WinUI框架最低要求1809版本的Windows10。

5. 接下來，很快會創建好解決方案和兩個對應的項目。其中，

• 項目名稱(桌面)：此項目包含應用的代碼。App.xaml文件和App.xaml.cs和代碼隱藏文件定義了一個Application類，它表示你的應用實例。MainWindow.xaml文件和MainWindow.xaml.cs代碼隱藏文件定義了一個MainWindow類，它表示你的應用顯示的主窗口。這些類派生自WinUI提供的Microsoft.UI.Xaml命名空間中的類型。

• 項目名稱(程序包)：這是一個Windows 應用程序打包項目，已配置該項目以將應用生成到MSIX包中。 這提供了一種新式部署體驗、通過包擴展與Windows 10功能集成的功能以及更多其他功能。 此項目包含應用的程序包清單，默認情況下它是你的解決方案的啟動項目。

6. 若要向應用項目中添加新項，請在解決方案資源管理器中右鍵單擊“項目名稱(桌面)”項目節點，然后選擇“添加” -> “新項”。 在“添加新項”對話框中，選擇“WinUI”選項卡，選擇要添加的項，然后單擊“添加”。

7. 生成並運行解決方案，確認應用運行時不會出錯。

第一次編譯，就遇到一個報錯，This version of Project Reunion requires WinRT.Runtime.dll version 1.2 or greater，差點慌了。

根據微軟給的提示，就兩條路，要么升級.Net SDK到v5.0.6版本，我查了下我自己的，才v5.0.3，我還以為真的有新版本，結果到下載頁一看，傻眼了，最新版不也就才到v5.0.5，哪來的v5.0.6，差點走偏。

后來，突然反應過來，這個關於Microsoft.Windows.SDK.NET.Ref FrameworkReference的提示很眼熟，哦，原來就是前面提到的開發環境中第7點，果然就是它，那肯定就靠你了，大兄弟。

用Visual Studio Code打開當前目錄，找到“項目名稱(桌面)”項目的.csproj，在ItemGroup節點中，插入：

    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.18362.16" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.18362.16" />

保存后，回到項目一看，重新生成所有，完事，就這么好了。

8. 廢話少說，Ctrl+F5，運行吧。

構建基本的WinUI 3桌面應用

應用程序解決方案

默認情況下，該解決方案包含兩個項目：應用程序本身以及用於創建.msix應用包的另一個項目。

當前需要MSIX應用包才能將使用Project Reunion 0.5的應用部署到其他計算機。但是，未來版本的Project Reunion將支持部署未打包應用。

應用程序項目

雙擊應用程序項目文件（或右鍵單擊並選擇“編輯項目文件”），這樣便會在XML文本編輯器中打開該文件。

我們可以看到TargetFramework是指定為net5.0-windows10.0.19041了，今后這是.NET的主要實現。

還有，ItemGroup節點下，各種Project Reunion功能的NuGet PackageReference元素，包括WinUI。

MainWindow.xaml文件

XAML Window類已擴展為支持桌面窗口，從而轉換為UWP和桌面應用模型所使用的每個低級別窗口實現的抽象。 具體而言，UWP使用CoreWindow，而Win32使用窗口句柄（或稱HWND）和相應的Win32 API。

從托管的C#/.NET 5應用調用原生函數

在解決方案上右鍵，選擇管理解決方案的Nuget包，搜索PInvoke.User32，將PInvoke.User32安裝到項目名稱(桌面)中。

前往App.xaml.cs中，定義MainWindowWindowHandle接收當前程序的句柄，在OnLaunched函數中獲取當前程序句柄。

若要獲取窗口句柄，請使用GetActiveWindow方法。 此方法返回當前活動窗口的窗口句柄（在激活目標窗口之后調用此方法）。

/// <summary>
/// Invoked when the application is launched normally by the end user.  Other entry points
/// will be used such as when the application is launched to open a specific file.
/// </summary>
/// <param name="args">Details about the launch request and process.</param>
protected override void OnLaunched(Microsoft.UI.Xaml.LaunchActivatedEventArgs args)
{
    m_window = new MainWindow();
    m_window.Activate();

    m_windowhandle = PInvoke.User32.GetActiveWindow();
}

private Window m_window;

IntPtr m_windowhandle;
public IntPtr MainWindowWindowHandle { get { return m_windowhandle; } }

然后前往MainWindow.xaml.cs中，找到myButton_Click事件，追加邏輯，通過調用原生函數來實現當前窗體的最大化動作。

private void myButton_Click(object sender, RoutedEventArgs e)
{
    myButton.Content = "Clicked";

    IntPtr hwnd = (App.Current as App).MainWindowWindowHandle;
    PInvoke.User32.ShowWindow(hwnd, PInvoke.User32.WindowShowStyle.SW_MAXIMIZE);
}

編譯並運行應用，按“單擊我”按鈕，應用窗口應最大化。

以“完全信任權限”模式運行桌面應用

WinUI 3提供了一種功能，使應用程序能夠在AppContainer的安全沙盒以外以“完全信任權限”運行。

在UWP應用的時候，我們總是會默認以受限制的方式運行，而基於WinUI 3的不會，接下來的舉個例子：

將MainWindow.xaml文件的內容改為：

<StackPanel 
    Orientation="Horizontal" 
    HorizontalAlignment="Center" 
    VerticalAlignment="Center">
    <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
    <ContentDialog x:Name="contentDialog" CloseButtonText="Close">
        <StackPanel>
            <TextBlock Name="cdTextBlock"/>
        </StackPanel>
    </ContentDialog>
</StackPanel>

然后前往MainWindow.xaml.cs中，找到myButton_Click事件，追加邏輯，從System.Diagnostics調用.NET API以獲取當前進程中加載的模塊，循環訪問Process.Modules對象中的每個ProcessModule。

private async void MyButton_Click(object sender, RoutedEventArgs e)
{
    myButton.Content = "Clicked";

    var description = new System.Text.StringBuilder();
    var process = System.Diagnostics.Process.GetCurrentProcess();
    foreach (System.Diagnostics.ProcessModule module in process.Modules)
    {
        description.AppendLine(module.FileName);
    }

    cdTextBlock.Text = description.ToString();
    await contentDialog.ShowAsync();
}

編譯並運行應用，按“單擊我”按鈕，對話框應顯示進程列表。

參考

• WinUI - The modern native UI platform of Windows.
• About WinUI
• Windows UI Library Roadmap
• Windows UI 庫 3 - Project Reunion 0.5 預覽版（2021 年 3 月）發行說明
• https://github.com/microsoft/ProjectReunion
• Announcing Project Reunion 0.5!
• Project Reunion 0.5 - Available now!
• 使用 Project Reunion 0.5 構建桌面 Windows 應用
• Project Reunion Roadmap
• Project Reunion 入門
• 部署使用項目配置的應用
• https://www.jetbrains.com/resharper/
• Fluent Design System
• Visual Studio 2019 v16.10 Preview 發行說明
• Visual Studio 2019 版本 16.10 預覽版 2
• 適用於桌面應用的 WinUI 3 入門
• 生成基本的 WinUI 3 - Project Reunion 0.5 桌面應用
• WinUI 3 控件庫
• Visual Studio 中的 WinUI 3 項目模板
• Download .NET 5.0
• What's new in .NET 5
• Enterprise development futures: Project Reunion
• WinUI 3 試玩報告