Menulis plugin kustom untuk Portal Perangkat Windows

Anda dapat menulis aplikasi paket (UWP atau Win32 paket menggunakan SDK Aplikasi Windows) yang menggunakan Portal Perangkat Windows untuk menghosting halaman web dan memberikan informasi diagnostik. Fungsionalitas plugin Device Portal diimplementasikan menggunakan ekstensi windows.devicePortalProvider, yang tersedia untuk semua aplikasi terkemas, apa pun kerangka kerja UI yang digunakan.

Note

Artikel ini ditujukan untuk pengembang yang membangun alat diagnostik atau manajemen untuk perangkat IoT Enterprise, penyebaran kios, atau lingkungan Windows terkelola lainnya di mana Portal Perangkat digunakan untuk pemantauan jarak jauh. Jika Anda membangun aplikasi desktop Windows 11 standar, Anda tidak mungkin memerlukan plugin Portal Perangkat — pertimbangkan untuk menggunakan diagnostik Aplikasi atau Windows Penganalisis Kinerja sebagai gantinya.

Dukungan plugin Portal Perangkat tersedia di Windows 10 dan yang lebih baru.

Membuat proyek

Buat proyek aplikasi baru di Microsoft Visual Studio. Buka File > Project Baru > dan pilih salah satu templat project berikut ini:

  • Untuk aplikasi UWP: Aplikasi Kosong (Windows Universal) untuk C#
  • Untuk aplikasi desktop WinUI 3: Aplikasi Kosong, Terpaket (WinUI 3 di Desktop)

Dalam kotak dialog Konfigurasikan proyek baru Anda , beri nama proyek DevicePortalProvider, lalu klik Buat. Ini akan menjadi aplikasi yang memuat layanan aplikasi.

Menambahkan kemampuan devicePortalProvider

Tambahkan kapabilitas rescap:devicePortalProvider ke file Package.appxmanifest aplikasi Anda.

Note

Namespace rescap (Kemampuan Terbatas) harus dideklarasikan sebelum dapat digunakan. Lihat Deklarasi kemampuan aplikasi untuk detailnya.

Di Penjelajah Solusi, klik Package.appxmanifest dua kali untuk membuka perancang manifes, lalu beralihlah ke tab Kemampuan dan periksa Penyedia Portal Perangkat jika tercantum, atau tambahkan secara manual dengan mengedit XML.

<Capabilities>
  <rescap:Capability Name="devicePortalProvider" />
</Capabilities>

Menyiapkan layanan aplikasi

Plugin Portal Perangkat menggunakan layanan aplikasi untuk berkomunikasi antara proses host plugin dan Portal Perangkat. Buka Package.appxmanifest, beralihlah ke tab Deklarasi, tambahkan deklarasi Penyedia Portal Perangkat Windows, dan konfigurasikan dengan nama layanan.

Atau, edit XML secara langsung:

<Applications>
  <Application Id="App" ...>
    ...
    <Extensions>
      <uap3:Extension Category="windows.appService" EntryPoint="DevicePortalProvider.DevicePortalPluginService">
        <uap3:AppService Name="com.microsoft.myapp.devicePortalService" SupportsRemoteSystems="true"/>
      </uap3:Extension>
      <uap4:Extension Category="windows.devicePortalProvider">
        <uap4:DevicePortalProvider DisplayName="My App Plugin" AppServiceName="com.microsoft.myapp.devicePortalService" HandlerRoute="/MyCustomApp/"/>
      </uap4:Extension>
    </Extensions>
  </Application>
</Applications>

Important

Awalan namespace XML uap3 dan uap4 harus dideklarasikan dalam elemen root <Package> pada manifes Anda, dan ditambahkan ke atribut IgnorableNamespaces:

<Package
  ...
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4"
  IgnorableNamespaces="... uap3 uap4">

Atribut berikut memerlukan konfigurasi khusus untuk aplikasi Anda:

Attribute Deskripsi
EntryPoint Menentukan kelas yang mengimplementasikan layanan aplikasi.
Name (AppService) Nama unik layanan aplikasi. Nama ini digunakan sebagai AppServiceName atribut dalam DevicePortalProvider elemen .
DisplayName Nama yang akan muncul di antarmuka pengguna Portal Perangkat.
HandlerRoute Awalan jalur URL yang digunakan Device Portal untuk merutekan permintaan ke plugin Anda. Semua permintaan yang jalurnya dimulai dengan nilai ini diteruskan ke layanan aplikasi Anda. Rute harus dimulai dan diakhiri dengan tanda garis miring.

Menambahkan kode layanan aplikasi

Tambahkan proyek Komponen Windows Runtime ke solusi Anda untuk menghosting layanan aplikasi latar belakang:

  1. Di Penjelajah Solusi, klik kanan solusi dan pilih Tambahkan > Project Baru.
  2. Pilih Komponen Windows Runtime (Universal Windows) dan beri nama DevicePortalProvider.
  3. Klik kanan proyek baru dan pilih Tambah > Item Baru > App Service.

Detail implementasi kode layanan aplikasi ada di artikel Membuat dan menggunakan layanan aplikasi .

Implementasikan handler Device Portal Anda

Berikut adalah contoh implementasi layanan aplikasi plugin Device Portal:

using Windows.ApplicationModel.AppService;
using Windows.ApplicationModel.Background;
using Windows.Storage;
using Windows.System.Diagnostics.DevicePortal;
using Windows.Web.Http;

namespace DevicePortalProvider
{
    public sealed class DevicePortalPluginService : IBackgroundTask
    {
        private BackgroundTaskDeferral _taskDeferral;
        private DevicePortalConnection _connection;

        public void Run(IBackgroundTaskInstance taskInstance)
        {
            _taskDeferral = taskInstance.GetDeferral();
            taskInstance.Canceled += OnTaskCanceled;

            var triggerDetails = taskInstance.TriggerDetails as AppServiceTriggerDetails;
            _connection = DevicePortalConnection.GetForAppServiceConnection(triggerDetails.AppServiceConnection);
            _connection.RequestReceived += _connection_RequestReceived;
        }

        private void OnTaskCanceled(IBackgroundTaskInstance taskInstance, BackgroundTaskCancellationReason reason)
        {
            _taskDeferral.Complete();
        }

        private async void _connection_RequestReceived(DevicePortalConnection sender, DevicePortalConnectionRequestReceivedEventArgs args)
        {
            // Handle the incoming request and send a response
        }
    }
}

Menangani permintaan masuk

Penangan plugin Anda menerima semua permintaan GET, POST, DELETE, dan PUT yang dirutekan oleh Device Portal ke HandlerRoute Anda. Implementasi umum:

private async void _connection_RequestReceived(
    DevicePortalConnection sender, 
    DevicePortalConnectionRequestReceivedEventArgs args)
{
    var request = args.RequestMessage;
    var response = args.ResponseMessage;

    // Use the request's path to determine what data to return
    // The path must begin with the HandlerRoute declared in the manifest (e.g. "/MyCustomApp/")
    if (request.RequestUri.LocalPath.Equals("/MyCustomApp/info", StringComparison.OrdinalIgnoreCase))
    {
        response.Content = new HttpStringContent(
            "{ \"appVersion\": \"1.0\" }",
            Windows.Storage.Streams.UnicodeEncoding.Utf8,
            "application/json");
        response.StatusCode = HttpStatusCode.Ok;
    }
}

Menyajikan konten statis

Jika Anda ingin menyajikan konten web (HTML, CSS, JavaScript) dari dalam paket aplikasi, Anda dapat menempatkan file tersebut di folder dan menanggapi permintaan dengan konten file.

private async void _connection_RequestReceived(
    DevicePortalConnection sender,
    DevicePortalConnectionRequestReceivedEventArgs args)
{
    var storageFile = await Windows.ApplicationModel.Package.Current.InstalledLocation.GetFileAsync(@"data\content.html");
    string htmlContent = await FileIO.ReadTextAsync(storageFile);

    args.ResponseMessage.Content = new HttpStringContent(
        htmlContent,
        Windows.Storage.Streams.UnicodeEncoding.Utf8,
        "text/html");
    args.ResponseMessage.StatusCode = HttpStatusCode.Ok;
}

Jalankan layanan aplikasi sebagai Sistem

Dalam beberapa kasus, untuk pengujian lengkap plugin Portal Perangkat, Anda mungkin perlu menjalankan plugin sebagai akun Sistem. Lihat artikel Majalah MSDN untuk detailnya.

Baca juga

  • Last updated on