Panduan—Buat komponen C#/WinRT, dan gunakan dari C++/WinRT

Artikel
07/13/2023

C#/WinRT memungkinkan pengembang menggunakan .NET untuk menulis komponen Windows Runtime mereka sendiri di C# menggunakan proyek pustaka kelas. Komponen yang ditulis dapat digunakan dalam aplikasi desktop asli sebagai referensi paket atau sebagai referensi proyek dengan beberapa modifikasi.

Panduan ini menunjukkan cara membuat komponen Windows Runtime sederhana menggunakan C#/WinRT, mendistribusikan komponen sebagai paket NuGet, dan menggunakan komponen dari aplikasi konsol C++/WinRT. Untuk sampel lengkap yang menyediakan kode untuk artikel ini, lihat sampel penulisan C#/WinRT. Untuk detail selengkapnya tentang penulisan, lihat Komponen penulisan.

Untuk panduan penulisan kontrol WinUI dengan C#/WinRT khusus untuk digunakan dalam aplikasi SDK Aplikasi Windows, lihat artikel Panduan: Menulis komponen C# dengan kontrol WinUI 3 dan mengonsumsi dari aplikasi C++ SDK Aplikasi Windows

Prasyarat

Panduan ini memerlukan alat dan komponen berikut:

Visual Studio 2022
.NET 6.0 SDK atau yang lebih baru
C++/WinRT VSIX untuk templat proyek C++/WinRT

Membuat Komponen Runtime Windows sederhana menggunakan C#/WinRT

Mulailah dengan membuat proyek baru di Visual Studio. Pilih templat proyek Pustaka Kelas, dan beri nama proyek AuthoringDemo. Anda harus membuat penambahan dan modifikasi berikut pada proyek:

TargetFramework Perbarui dalam file AuthoringDemo.csproj dan tambahkan elemen berikut ke PropertyGroup:
```
<PropertyGroup>
    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <Platforms>x64</Platforms>
</PropertyGroup>
```
Untuk mengakses jenis Windows Runtime, Anda perlu mengatur versi Windows SDK tertentu di TFM. Untuk detail selengkapnya tentang versi yang didukung, lihat .NET 6 dan yang lebih baru: Gunakan opsi TFM.
Instal paket NuGet Microsoft.Windows.CsWinRT di proyek Anda.

a. Di Penjelajah Solusi, klik kanan pada simpul proyek dan pilih Kelola Paket NuGet.

b. Cari paket NuGet Microsoft.Windows.CsWinRT dan instal versi terbaru. Panduan ini menggunakan C#/WinRT versi 1.4.1.
Tambahkan elemen baru PropertyGroup yang mengatur CsWinRTComponent properti . Ini menentukan bahwa proyek Anda adalah komponen Windows Runtime sehingga .winmd file dihasilkan saat Anda membangun proyek.
```
<PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
```
Untuk daftar lengkap properti proyek C#/WinRT, lihat dokumentasi C#/WinRT NuGet.
Anda dapat menulis kelas runtime Menggunakan file kelas pustaka .cs . Klik kanan pada Class1.cs file, dan ganti namanya menjadi Example.cs. Tambahkan kode berikut ke file ini, yang menambahkan properti publik dan metode ke kelas runtime. Ingatlah untuk menandai kelas apa pun yang ingin Anda ekspos di komponen runtime sebagai public.
```
namespace AuthoringDemo
{
    public sealed class Example
    {
        public int SampleProperty { get; set; }

        public static string SayHello()
        {
            return "Hello from your C# WinRT component";
        }
    }
}
```
Anda sekarang dapat membangun proyek untuk menghasilkan .winmd file untuk komponen Anda. Klik kanan proyek di Penjelajah Solusi, dan klik Bangun. Anda akan melihat file yang dihasilkan AuthoringDemo.winmd di folder output build Anda.

Membuat paket NuGet untuk komponen

Sebagian besar pengembang akan ingin mendistribusikan dan berbagi komponen Windows Runtime mereka sebagai paket NuGet. Opsi lain adalah menggunakan komponen sebagai referensi proyek. Langkah-langkah berikut menunjukkan cara mengemas komponen AuthoringDemo . Saat Anda membuat paket, C#/WinRT mengonfigurasi komponen dan rakitan hosting dalam paket untuk mengaktifkan konsumsi dari aplikasi asli.

Ada beberapa cara untuk menghasilkan paket NuGet:

Jika Anda ingin membuat paket NuGet setiap kali Anda membangun proyek, tambahkan properti berikut ke file proyek AuthoringDemo lalu buat ulang proyek.
```
<PropertyGroup>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
</PropertyGroup>
```
Atau, Anda dapat membuat paket NuGet dengan mengklik kanan proyek AuthoringDemo di Penjelajah Solusi dan memilih Pack.

Saat Anda membuat paket, jendela Build harus menunjukkan bahwa paket AuthoringDemo.1.0.0.nupkg NuGet berhasil dibuat. Lihat Membuat paket menggunakan dotnet CLI untuk detail selengkapnya tentang properti paket NuGet dengan .NET CLI.

Menggunakan komponen dari aplikasi C++/WinRT

Komponen Windows Runtime yang ditulis C#/WinRT dapat digunakan dari bahasa yang kompatibel dengan Windows Runtime (WinRT). Langkah-langkah berikut menunjukkan cara memanggil komponen yang ditulis di atas dalam aplikasi konsol C++/WinRT.

Catatan

Menggunakan komponen C#/WinRT dari aplikasi C#/.NET didukung oleh referensi paket atau referensi proyek. Skenario ini setara dengan mengonsumsi pustaka kelas C# biasa dan tidak melibatkan aktivasi WinRT dalam banyak kasus. Dimulai dengan C#/WinRT 1.3.5, referensi proyek untuk konsumen C# memerlukan .NET 6.

Tambahkan proyek Aplikasi Konsol C++/WinRT baru ke solusi Anda. Perhatikan bahwa proyek ini juga dapat menjadi bagian dari solusi yang berbeda jika Anda memilihnya.

a. Di Penjelajah Solusi, klik kanan simpul solusi Anda dan klik Tambahkan ->Proyek Baru.

b. Dalam kotak dialog Tambahkan Proyek Baru, cari templat proyek Aplikasi Konsol C++/WinRT. Pilih templat dan klik Berikutnya.

c. Beri nama proyek baru CppConsoleApp dan klik Buat.
Tambahkan referensi ke komponen AuthoringDemo, baik sebagai paket NuGet atau referensi proyek.
- Opsi 1 (Referensi paket):
  
  a. Klik kanan proyek CppConsoleApp dan pilih Kelola paket NuGet. Anda mungkin perlu mengonfigurasi sumber paket Anda untuk menambahkan referensi ke paket AuthoringDemo NuGet. Untuk melakukan ini, klik ikon Pengaturan di NuGet Package Manager dan tambahkan sumber paket ke jalur yang sesuai.
  
  b. Setelah mengonfigurasi sumber paket Anda, cari paket AuthoringDemo dan klik Instal.
- Opsi 2 (Referensi proyek):
  
  a. Klik kanan proyek CppConsoleApp dan pilih Tambahkan ->Referensi. Di bawah simpul Proyek , tambahkan referensi ke proyek AuthoringDemo .
Untuk menghosting komponen, Anda harus menambahkan file manifes untuk pendaftaran kelas yang dapat diaktifkan. Untuk detail selengkapnya tentang hosting komponen terkelola, lihat Hosting komponen terkelola.

a. Untuk menambahkan file manifes, sekali lagi klik kanan pada proyek dan pilih Tambahkan -> Item Baru. Cari templat File Teks dan beri nama CppConsoleApp.exe.manifest. Tempelkan konten berikut, yang menentukan kelas runtime menggunakan entri pendaftaran kelas yang dapat diaktifkan:
```
<?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>
```
File manifes aplikasi diperlukan untuk aplikasi yang tidak dikemas. Untuk aplikasi paket, konsumen aplikasi perlu mendaftarkan kelas yang dapat diaktifkan dalam file manifes paket merekaPackage.appxmanifest, seperti yang dijelaskan dalam Panduan: Membuat komponen C# dengan kontrol WinUI 3 dan menggunakan dari aplikasi C++ SDK Aplikasi Windows.

b. Ubah proyek untuk menyertakan file manifes dalam output saat menyebarkan proyek. Klik file CppConsoleApp.exe.manifest di Penjelajah Solusi dan atur properti Konten ke True. Berikut adalah contoh tampilannya.
Buka pch.h di bawah File Header proyek, dan tambahkan baris kode berikut untuk menyertakan komponen Anda.
```
#include <winrt/AuthoringDemo.h>
```

Buka main.cpp di bawah File Sumber proyek, dan ganti dengan konten berikut.

#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;
}

Buat dan jalankan proyek CppConsoleApp . Anda sekarang akan melihat output di bawah ini.

Panduan—Buat komponen C#/WinRT, dan gunakan dari C++/WinRT

Prasyarat

Membuat Komponen Runtime Windows sederhana menggunakan C#/WinRT

Membuat paket NuGet untuk komponen

Menggunakan komponen dari aplikasi C++/WinRT

Saran dan Komentar

Sumber Daya Tambahan:

Panduan—Buat komponen C#/WinRT, dan gunakan dari C++/WinRT

Prasyarat

Membuat Komponen Runtime Windows sederhana menggunakan C#/WinRT

Membuat paket NuGet untuk komponen

Menggunakan komponen dari aplikasi C++/WinRT

Topik terkait

Saran dan Komentar

Sumber Daya Tambahan: