逐步解說—建立 C#/WinRT 元件並從 C++/WinRT 中加以取用

發行項
10/05/2023

C#/WinRT 可讓使用 .NET 的開發人員透過類別庫專案，在 C# 中撰寫自己的 Windows 執行階段元件。所撰寫的元件可於原生 Windows 傳統型應用程式中，以套件參考的形式或以專案參考 (需稍作修改) 的形式加以取用。

本逐步解說會示範如何使用 C#/WinRT 建立簡單的 Windows 執行階段元件、以 NuGet 套件的形式散發元件，以及從 C++/WinRT 主控台應用程式中取用元件。如需可提供本文適用程式碼的完整範例，請參閱 C#/WinRT 撰寫範例。如需如何進行撰寫的詳細資訊，請參閱撰寫元件。

如需如何使用 C#/WinRT 撰寫 WinUI 控制項以特別用於 Windows 應用程式 SDK 應用程式的逐步解說，請參閱逐步解說：使用 WinUI 3 控制項撰寫 C# 元件並從 C++ Windows 應用程式 SDK 應用程式加以取用一文

必要條件

本逐步解說需要使用下列工具和元件：

Visual Studio 2022
.NET 6.0 SDK 或更新版本
C++/WinRT VSIX for C++/WinRT 專案範本

使用 C#/WinRT 建立簡單的 Windows 執行階段元件

請先在 Visual Studio 中建立新專案。選取 [類別庫] 專案範本，並將專案命名為 AuthoringDemo。您必須對專案進行下列新增和修改：

更新 AuthoringDemo.csproj 檔案中的 TargetFramework，並將下列元素新增至 PropertyGroup：
```
<PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platforms>x64</Platforms>
</PropertyGroup>
```
若要存取 Windows 執行階段類型，您必須在 TFM 中設定特定的 Windows SDK 版本。如需所支援版本的詳細資訊，請參閱 .NET 6 和更新版本：使用 TFM 選項。
將 Microsoft.Windows.CsWinRT NuGet 套件安裝到您的專案中。

a. 在 [方案總管] 中，以滑鼠右鍵按一下專案節點，然後選取 [管理 NuGet 套件]。

b. 搜尋 Microsoft.Windows.CsWinRT NuGet 套件，並安裝最新版本。本逐步解說使用 C#/WinRT 1.4.1 版。
新增可設定 CsWinRTComponent 屬性的 PropertyGroup 元素。這會指定您的專案是 Windows 執行階段元件，而在您建置專案時產生 .winmd 檔案。
```
<PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
```
如需 C#/WinRT 專案屬性的完整清單，請參閱 C#/WinRT NuGet 文件。
您可以使用程式庫 .cs 類別檔案來撰寫執行階段類別。以滑鼠右鍵按一下 Class1.cs 檔案，並將其重新命名為 Example.cs。將下列程式碼新增至這個檔案，以將公用屬性和方法新增至執行階段類別。請記得將您想要在執行階段元件中公開的任何類別標示為 public。
```
namespace AuthoringDemo
{
    public sealed class Example
    {
        public int SampleProperty { get; set; }

        public static string SayHello()
        {
            return "Hello from your C# WinRT component";
        }
    }
}
```
您現在可以建置專案以便為您的元件產生 .winmd 檔案。在 [方案總管] 中以滑鼠右鍵按一下該專案，然後按一下 [建置]。您便會在建置輸出檔案夾中看到所產生的 AuthoringDemo.winmd 檔案。

產生元件的 NuGet 套件

大多數開發人員會想要以 NuGet 套件的形式散發和共用其 Windows 執行階段元件。另一個選項是以專案參考的形式取用元件。下列步驟示範如何封裝 AuthoringDemo 元件。當您產生套件時，C#/WinRT 會設定套件中的元件和裝載組件，以啟用從原生應用程式取用的功能。

有數種方式可以產生 NuGet 套件：

如果您想要在每次建置專案時產生 NuGet 套件，請將下列屬性新增至 AuthoringDemo 專案檔，然後重建專案。
```
<PropertyGroup>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
</PropertyGroup>
```
或者，您也可以在 [方案總管] 中以滑鼠右鍵按一下 [AuthoringDemo] 專案，然後選取 [封裝]，以產生 NuGet 套件。

在建置套件時，[建置] 視窗應該會指出系統已成功建立 NuGet 套件 AuthoringDemo.1.0.0.nupkg。如需使用 .NET CLI 時的 NuGet 套件屬性詳細資訊，請參閱使用 dotnet CLI 建立套件。

從 C++/WinRT 應用程式中取用元件

以 C#/WinRT 撰寫的 Windows 執行階段元件可從任何與 Windows 執行階段 (WinRT) 相容的語言加以取用。下列步驟示範如何在 C++/WinRT 主控台應用程式中呼叫上面所撰寫的元件。

注意

套件參考或專案參考都支援從 C#/.NET 應用程式取用 C#/WinRT 元件。此案例相當於取用任何一般 C# 類別庫，而且在大部分情況下不會牽涉到 WinRT 的啟用。從 C#/WinRT 1.3.5 開始，C# 取用者的專案參考需要使用 .NET 6。

將新的 C++/WinRT 主控台應用程式專案新增至您的解決方案。請注意，如果您想要的話，此專案也可以成為不同解決方案的一部分。

a. 在 [方案總管] 中，以滑鼠右鍵按一下您的解決方案節點，然後按一下 [新增] ->[新增專案]。

b. 在 [新增專案] 對話方塊中，搜尋 C++/WinRT 主控台應用程式專案範本。選取範本，然後按 [下一步]。

c. 將新專案命名為 CppConsoleApp，然後按一下 [建立]。
將 AuthoringDemo 元件的參考新增為 NuGet 套件或專案參考。
- 選項 1 (套件參考)：
  
  a. 以滑鼠右鍵按一下 [CppConsoleApp] 專案，然後選取 [管理 NuGet 套件]。您可能需要設定套件來源，以新增 AuthoringDemo NuGet 套件的參考。若要這樣做，請按一下 NuGet 套件管理員中的 [設定] 圖示，並將套件來源新增至適當路徑。
  
  b. 在設定套件來源後，請搜尋 AuthoringDemo 套件，然後按一下 [安裝]。
- 選項 2 (專案參考)：
  
  a. 以滑鼠右鍵按一下 [CppConsoleApp] 專案，然後選取 [新增] -> [參考]。在 [專案] 節點下，新增 AuthoringDemo 專案的參考。
若要裝載元件，您必須新增適用於可啟用類別註冊的資訊清單檔案。如需受控元件裝載的詳細資訊，請參閱受控元件裝載。

a. 若要新增資訊清單檔案，請再次以滑鼠右鍵按一下專案，然後選擇 [新增] -> [新增項目]。搜尋文字檔範本，並將其命名為 CppConsoleApp.exe.manifest。貼上下列內容，以使用可啟用類別註冊項目指定執行階段類別：
```
<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
    <assemblyIdentity version="1.0.0.0" name="CppConsoleApp"/>
    <file name="WinRT.Host.dll">
        <activatableClass
            name="AuthoringDemo.Example"
            threadingModel="both"
            xmlns="urn:schemas-microsoft-com:winrt.v1" />
    </file>
</assembly>
```
未封裝的應用程式需要使用應用程式資訊清單檔案。若為已封裝的應用程式，則應用程式取用者必須在其 Package.appxmanifest 套件資訊清單檔案中註冊可啟用類別，如逐步解說：使用 WinUI 3 控制項建立 C# 元件並從 C++ Windows 應用程式 SDK 應用程式加以取用中所述。

b. 修改專案，以在部署專案時將資訊清單檔案納入輸出中。按一下 [方案總管] 中的 [CppConsoleApp.exe.manifest] 檔案，並將 [內容] 屬性設定為 [True]。以下是其外觀的範例。
在專案的 [標頭檔] 底下開啟 pch.h，並新增下面這行程式碼以包含您的元件。
```
#include <winrt/AuthoringDemo.h>
```

在專案的 [原始程式檔] 底下開啟 main.cpp，並使用下列內容加以取代。

#include "pch.h"
#include "iostream"

using namespace winrt;
using namespace Windows::Foundation;

int main()
{
    init_apartment();

    AuthoringDemo::Example ex;
    ex.SampleProperty(42);
    std::wcout << ex.SampleProperty() << std::endl;
    std::wcout << ex.SayHello().c_str() << std::endl;
}

建置並執行 CppConsoleApp 專案。您現在應該會看到下列輸出。

共用方式為

逐步解說—建立 C#/WinRT 元件並從 C++/WinRT 中加以取用

必要條件

使用 C#/WinRT 建立簡單的 Windows 執行階段元件

產生元件的 NuGet 套件

從 C++/WinRT 應用程式中取用元件

其他資源

共用方式為

逐步解說—建立 C#/WinRT 元件並從 C++/WinRT 中加以取用

必要條件

使用 C#/WinRT 建立簡單的 Windows 執行階段元件

產生元件的 NuGet 套件

從 C++/WinRT 應用程式中取用元件

相關主題

其他資源