Menulis plugin kustom untuk Portal Perangkat Windows

Pelajari cara menulis aplikasi UWP yang menggunakan Windows Device Portal (WDP) untuk menghosting halaman web dan memberikan informasi diagnostik.

Dimulai dengan Pembaruan Pembuat Windows 10 (versi 1703, build 15063), Anda dapat menggunakan Portal Perangkat untuk menghosting antarmuka diagnostik aplikasi Anda. Artikel ini membahas tiga bagian yang diperlukan untuk membuat DevicePortalProvider untuk aplikasi Anda – perubahan manifes paket aplikasi , menyiapkan koneksi aplikasi Anda ke layanan Portal Perangkat, dan menangani permintaan masuk.

Membuat proyek aplikasi UWP baru

Di Microsoft Visual Studio, buat proyek aplikasi UWP baru. Buka File > Proyek > Baru dan pilih Aplikasi Kosong (Windows Universal) untuk C#, lalu klik Berikutnya. Dalam kotak dialog Konfigurasi proyek baru Anda. Beri nama proyek "DevicePortalProvider" lalu klik Buat. Ini akan menjadi aplikasi yang berisi layanan aplikasi. Anda mungkin perlu memperbarui Visual Studio atau menginstal Windows SDK terbaru.

Menambahkan ekstensi devicePortalProvider ke manifes paket aplikasi Anda

Anda harus menambahkan beberapa kode ke file package.appxmanifest untuk membuat aplikasi Anda berfungsi sebagai plugin Portal Perangkat. Pertama, tambahkan definisi namespace berikut di bagian atas file. Tambahkan mereka juga ke atribut IgnorableNamespaces.

<Package
    ... 
    xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
    xmlns:uap4="http://schemas.microsoft.com/appx/manifest/uap/windows10/4"
    IgnorableNamespaces="uap mp rescap uap4">
    ...

Untuk menyatakan bahwa aplikasi Anda adalah Penyedia Portal Perangkat, Anda perlu membuat layanan aplikasi dan ekstensi Penyedia Portal Perangkat baru yang menggunakannya. Tambahkan ekstensi windows.appService dan ekstensi windows.devicePortalProvider di Extensions elemen di bawah Application. Pastikan AppServiceName atribut cocok di setiap ekstensi. Ini menunjukkan ke layanan Portal Perangkat bahwa layanan aplikasi ini dapat diluncurkan untuk menangani permintaan pada namespace handler.

...   
<Application 
    Id="App" 
    Executable="$targetnametoken$.exe"
    EntryPoint="DevicePortalProvider.App">
    ...
    <Extensions>
        <uap:Extension Category="windows.appService" EntryPoint="MySampleProvider.SampleProvider">
            <uap:AppService Name="com.sampleProvider.wdp" />
        </uap:Extension>
        <uap4:Extension Category="windows.devicePortalProvider">
            <uap4:DevicePortalProvider 
                DisplayName="My Device Portal Provider Sample App" 
                AppServiceName="com.sampleProvider.wdp" 
                HandlerRoute="/MyNamespace/api/" />
        </uap4:Extension>
    </Extensions>
</Application>
...

Atribut HandlerRoute merujuk pada namespace REST yang diklaim oleh aplikasi Anda. Setiap permintaan HTTP pada namespace tersebut (secara implisit diikuti oleh kartu bebas) yang diterima oleh layanan Device Portal akan dikirim ke aplikasi Anda untuk ditangani. Dalam hal ini, permintaan <ip_address>/MyNamespace/api/* HTTP yang berhasil diautentikasi akan dikirim ke aplikasi Anda. Konflik antara rute handler diselesaikan melalui pemeriksaan "kemenangan terpanjang": rute mana pun yang cocok dengan lebih banyak permintaan yang dipilih, yang berarti bahwa permintaan ke "/MyNamespace/api/foo" akan cocok dengan penyedia dengan "/MyNamespace/api" daripada satu dengan "/MyNamespace".

Dua kemampuan baru diperlukan untuk fungsionalitas ini. mereka juga harus ditambahkan ke file package.appxmanifest Anda.

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

Nota

Kemampuan "devicePortalProvider" dibatasi ("rescap"), yang berarti Anda harus mendapatkan persetujuan sebelumnya dari Store sebelum aplikasi Anda dapat diterbitkan di sana. Namun, ini tidak mencegah Anda menguji aplikasi Anda secara lokal melalui sideloading. Untuk informasi selengkapnya tentang kemampuan terbatas, lihat Deklarasi kemampuan aplikasi.

Siapkan tugas latar belakang dan Komponen WinRT Anda

Untuk menyiapkan koneksi Portal Perangkat, aplikasi Anda harus menghubungkan koneksi layanan aplikasi dari layanan Portal Perangkat dengan instans Portal Perangkat yang berjalan dalam aplikasi Anda. Untuk melakukan ini, tambahkan Komponen WinRT baru ke aplikasi Anda dengan kelas yang mengimplementasikan IBackgroundTask.

using Windows.System.Diagnostics.DevicePortal;
using Windows.ApplicationModel.Background;

namespace MySampleProvider {
    // Implementing a DevicePortalConnection in a background task
    public sealed class SampleProvider : IBackgroundTask {
        BackgroundTaskDeferral taskDeferral;
        DevicePortalConnection devicePortalConnection;
        //...
    }

Pastikan namanya cocok dengan namespace layanan dan nama kelas yang disiapkan oleh AppService EntryPoint ("MySampleProvider.SampleProvider"). Saat Anda membuat permintaan pertama ke penyedia Device Portal, Device Portal akan menampung permintaan tersebut, meluncurkan tugas latar belakang aplikasi Anda, memanggil metode Run, dan meneruskan IBackgroundTaskInstance. Aplikasi Anda kemudian menggunakannya untuk menyiapkan DevicePortalConnection instans.

// Implement background task handler with a DevicePortalConnection
public void Run(IBackgroundTaskInstance taskInstance) {
    // Take a deferral to allow the background task to continue executing 
    this.taskDeferral = taskInstance.GetDeferral();
    taskInstance.Canceled += TaskInstance_Canceled;

    // Create a DevicePortal client from an AppServiceConnection 
    var details = taskInstance.TriggerDetails as AppServiceTriggerDetails;
    var appServiceConnection = details.AppServiceConnection;
    this.devicePortalConnection = DevicePortalConnection.GetForAppServiceConnection(appServiceConnection);

    // Add Closed, RequestReceived handlers 
    devicePortalConnection.Closed += DevicePortalConnection_Closed;
    devicePortalConnection.RequestReceived += DevicePortalConnection_RequestReceived;
}

Ada dua peristiwa yang harus ditangani oleh aplikasi untuk menyelesaikan perulangan penanganan permintaan: Ditutup, setiap kali layanan Portal Perangkat dimatikan, dan RequestReceived, yang menampilkan permintaan HTTP masuk dan menyediakan fungsionalitas utama penyedia Portal Perangkat.

Menangani peristiwa RequestReceived

Peristiwa RequestReceived akan diangkat sekali untuk setiap permintaan HTTP yang dibuat pada Rute Penangan yang ditentukan plugin Anda. Perulangan penanganan permintaan untuk penyedia Portal Perangkat mirip dengan yang ada di NodeJS Express: objek permintaan dan respons disediakan bersama dengan peristiwa, dan handler merespons dengan mengisi objek respons. Di penyedia Portal Perangkat, peristiwa RequestReceived dan penangannya menggunakan Windows.Web.Http.HttpRequestMessage dan objek HttpResponseMessage.

// Sample RequestReceived echo handler: respond with an HTML page including the query and some additional process information. 
private void DevicePortalConnection_RequestReceived(DevicePortalConnection sender, DevicePortalConnectionRequestReceivedEventArgs args)
{
    var req = args.RequestMessage;
    var res = args.ResponseMessage;

    if (req.RequestUri.AbsolutePath.EndsWith("/echo"))
    {
        // construct an html response message
        string con = "<h1>" + req.RequestUri.AbsoluteUri + "</h1><br/>";
        var proc = Windows.System.Diagnostics.ProcessDiagnosticInfo.GetForCurrentProcess();
        con += String.Format("This process is consuming {0} bytes (Working Set)<br/>", proc.MemoryUsage.GetReport().WorkingSetSizeInBytes);
        con += String.Format("The process PID is {0}<br/>", proc.ProcessId);
        con += String.Format("The executable filename is {0}", proc.ExecutableFileName);
        res.Content = new Windows.Web.HttpStringContent(con);
        res.Content.Headers.ContentType = new Windows.Web.Http.Headers.HttpMediaTypeHeaderValue("text/html");
        res.StatusCode = Windows.Web.Http.HttpStatusCode.Ok;            
    }
    //...
}

Dalam contoh penanganan permintaan ini, pertama-tama kami menarik objek permintaan dan respons dari parameter args , lalu membuat string dengan URL permintaan dan beberapa pemformatan HTML tambahan. Ini ditambahkan ke dalam objek Respons sebagai instans HttpStringContent. Kelas IHttpContent lainnya, seperti kelas untuk "String" dan "Buffer," juga diizinkan.

Respons kemudian ditetapkan sebagai respons HTTP dan diberi kode status 200 (OK). Ini harus dirender seperti yang diharapkan di browser yang melakukan panggilan asli. Perhatikan bahwa ketika pengendali peristiwa RequestReceived kembali, pesan respons secara otomatis dikembalikan ke agen pengguna: tidak perlu metode "kirim" tambahan.

Menyediakan konten statis

Konten statis dapat disajikan langsung dari folder dalam paket Anda, sehingga sangat mudah untuk menambahkan UI ke penyedia Anda. Cara term mudah untuk menyajikan konten statis adalah dengan membuat folder konten di proyek Anda yang dapat memetakan ke URL.

Kemudian, tambahkan penangan rute di penanganan acara RequestReceived yang mendeteksi rute konten statis dan memetakan permintaan dengan tepat.

if (req.RequestUri.LocalPath.ToLower().Contains("/www/")) {
    var filePath = req.RequestUri.AbsolutePath.Replace('/', '\\').ToLower();
    filePath = filePath.Replace("\\backgroundprovider", "")
    try {
        var fileStream = Windows.ApplicationModel.Package.Current.InstalledLocation.OpenStreamForReadAsync(filePath).GetAwaiter().GetResult();
        res.StatusCode = HttpStatusCode.Ok;
        res.Content = new HttpStreamContent(fileStream.AsInputStream());
        res.Content.Headers.ContentType = new HttpMediaTypeHeaderValue("text/html");
    } catch(FileNotFoundException e) {
        string con = String.Format("<h1>{0} - not found</h1>\r\n", filePath);
        con += "Exception: " + e.ToString();
        res.Content = new Windows.Web.Http.HttpStringContent(con);
        res.StatusCode = Windows.Web.Http.HttpStatusCode.NotFound;
        res.Content.Headers.ContentType = new Windows.Web.Http.Headers.HttpMediaTypeHeaderValue("text/html");
    }
}

Pastikan bahwa semua file di dalam folder konten ditandai sebagai "Konten" dan diatur ke "Salin jika lebih baru" atau "Salin selalu" di menu Properti Visual Studio. Ini memastikan bahwa file akan berada di dalam Paket AppX Anda saat Anda menyebarkannya.

Menggunakan sumber daya dan API Portal Perangkat yang ada

Konten statis yang dilayani oleh penyedia Portal Perangkat dilayani pada port yang sama dengan layanan Portal Perangkat inti. Ini berarti Anda dapat merujuk JS dan CSS yang sudah terdapat dalam Portal Perangkat dengan menggunakan tag <link> dan <script> sederhana di HTML Anda. Secara umum, kami menyarankan penggunaan rest.js, yang membungkus semua REST API Portal Perangkat inti dalam objek webbRest yang nyaman, dan file common.css , yang akan memungkinkan Anda untuk menata konten Anda agar sesuai dengan UI Portal Perangkat lainnya. Anda dapat melihat contoh ini di halaman index.html yang disertakan dalam sampel. Ini menggunakan rest.js untuk mengambil nama perangkat dan menjalankan proses dari Portal Perangkat.

output plugin portal perangkat

Yang penting, penggunaan metode HttpPost/DeleteExpect200 di webbRest akan secara otomatis menangani CSRF untuk Anda, yang memungkinkan situs web Anda memanggil REST API yang mengubah status.

Nota

Konten statis yang disertakan dengan Portal Perangkat tidak dilengkapi dengan jaminan terhadap perubahan yang mengganggu. Meskipun API tidak diharapkan sering berubah, mereka mungkin akan berubah, terutama dalam file common.js dan controls.js, yang seharusnya tidak digunakan oleh penyedia Anda.

Memperbaiki koneksi Portal Perangkat

Untuk men-debug tugas latar belakang, Anda harus mengubah cara Visual Studio menjalankan kode Anda. Ikuti langkah-langkah di bawah ini untuk menelusuri kesalahan koneksi layanan aplikasi untuk memeriksa bagaimana penyedia Anda menangani permintaan HTTP:

1. Dari menu Debug, pilih DevicePortalProvider Properties.
2. Di bawah tab Debugging, di bagian tindakan Mulai, pilih "Jangan jalankan, tetapi debug kode saya ketika dimulai".
   
3. Atur titik henti dalam fungsi handler RequestReceived Anda.

Nota

Pastikan arsitektur build cocok dengan arsitektur target dengan tepat. Jika Anda menggunakan PC 64-bit, Anda harus menyebarkan menggunakan build AMD64. 4. Tekan F5 untuk menyebarkan aplikasi Anda 5. Nonaktifkan Portal Perangkat, lalu aktifkan kembali sehingga bisa menemukan aplikasi Anda (hanya diperlukan saat Anda mengubah manifes aplikasi - sisanya, Anda cukup menyebarkan ulang dan melewati langkah ini). 6. Di browser Anda, akses namespace penyedia, dan titik henti seharusnya terkena.

Topik terkait

• Gambaran Umum Portal Perangkat Windows
• Membuat dan menggunakan layanan aplikasi