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

C#/WinRT memungkinkan pengembang menggunakan .NET untuk menulis komponen Windows Runtime mereka sendiri di C# menggunakan proyek pustaka kelas. Komponen yang dirancang 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 Authoring.

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

Prasyarat

Panduan ini memerlukan alat dan komponen berikut:

Visual Studio 2022 atau yang lebih baru
.NET 8.0 SDK (LTS) atau yang lebih baru
C++/WinRT VSIX untuk templat project C++/WinRT

Membuat Komponen Windows Runtime sederhana menggunakan C#/WinRT

Mulailah dengan membuat proyek baru di Visual Studio. Pilih templat Class Library project, dan beri nama project AuthoringDemo. Anda harus membuat penambahan dan modifikasi berikut ke project:

Perbarui TargetFramework dalam unsur file AuthoringDemo.csproj dan tambahkan elemen berikut ke PropertyGroup:
```
<PropertyGroup>
    <TargetFramework>net8.0-windows10.0.19041.0</TargetFramework>
    <Platforms>x64</Platforms>
</PropertyGroup>
```
Untuk mengakses jenis Windows Runtime, Anda perlu mengatur versi SDK Windows tertentu di TFM. Untuk detail selengkapnya tentang versi yang didukung, lihat .NET 6 dan yang lebih baru: Gunakan opsi TFM.
Pasang paket Microsoft.Windows.CsWinRT NuGet dalam 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.
Tambahkan elemen baru PropertyGroup yang mengatur CsWinRTComponent properti . Ini menentukan bahwa proyek Anda adalah komponen Windows Runtime sehingga file .winmd dihasilkan saat Anda membangun proyek.
```
<PropertyGroup>   
    <CsWinRTComponent>true</CsWinRTComponent>
</PropertyGroup>
```
Untuk daftar lengkap properti project C#/WinRT, lihat dokumentasi C#/WinRT NuGet.
Anda dapat menulis kelas runtime menggunakan berkas kelas dari 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 project untuk menghasilkan file .winmd untuk komponen Anda. Klik kanan proyek di Penjelajah Solusi, dan klik Build. 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 mendukung penggunaan oleh aplikasi asli.

Ada beberapa cara untuk menghasilkan paket NuGet:

Jika Anda ingin membuat paket NuGet setiap kali Anda membuat project, tambahkan properti berikut ke file AuthoringDemo project lalu buat ulang project.
```
<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 Buat paket menggunakan CLI dotnet untuk detail selengkapnya tentang properti paket NuGet dengan CLI .NET.

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.

Nota

Menggunakan komponen C#/WinRT dari aplikasi C#/.NET dapat dilakukan dengan dukungan 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 atau yang lebih baru.

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

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

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 project.
- Opsi 1 (Referensi paket):
  
  a. Klik kanan CppConsoleApp project dan pilih Kelola paket NuGet. Anda mungkin perlu mengonfigurasi sumber paket Anda untuk menambahkan referensi ke paket AuthoringDemo NuGet. Untuk melakukan ini, klik ikon Settings di NuGet Package Manager dan tambahkan sumber paket ke jalur yang sesuai.
  
  b. Setelah mengonfigurasi sumber paket Anda, cari paket AuthoringDemo dan klik Instal.
- Option 2 (referensi proyek):
  
  a. Klik kanan CppConsoleApp project dan pilih Tambahkan ->Reference. Di bawah simpul Projects, tambahkan referensi ke AuthoringDemo project.
Untuk menghosting komponen, Anda harus menambahkan file manifes untuk pendaftaran kelas yang dapat diaktifkan. Untuk informasi lebih lanjut tentang hosting komponen terkelola, lihat Hosting Komponen Terkelola.

a. Untuk menambahkan file manifes, sekali lagi klik kanan pada project 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 bisa 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 Package.appxmanifest mereka, seperti yang dijelaskan dalam Walkthrough: Membuat komponen C# dengan kontrol WinUI dan menggunakan dari aplikasi C++ SDK Aplikasi Windows.

b. Ubah project untuk menyertakan file manifes dalam output saat menyebarkan project. Klik file CppConsoleApp.exe.manifest di Penjelajah Solusi dan atur properti Content ke True. Berikut adalah contoh tampilannya.

Konten
Buka pch.h di bawah File Header project, dan tambahkan baris kode berikut untuk menyertakan komponen Anda.
```
#include <winrt/AuthoringDemo.h>
```

Buka main.cpp di bawah File Sumber project, 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 CppConsoleApp project. Anda sekarang akan melihat output di bawah ini.

output Konsol C++/WinRT

Kode contoh
Komponen Pengeditan
Hosting komponen yang dikelola

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-04-14