Napište vlastní plugin pro Windows Device Portal

Naučte se psát aplikaci pro UPW, která k hostování webové stránky používá portál zařízení s Windows (WDP) a poskytuje diagnostické informace.

Počínaje Windows 10 Creators Update (verze 1703, build 15063) můžete k hostování diagnostických rozhraní vaší aplikace použít Portál zařízení. Tento článek popisuje tři části potřebné k vytvoření DevicePortalProvider pro vaši aplikaci – manifest balíčku aplikace změny, nastavení připojení aplikace ke službě portálu zařízenía zpracování příchozí žádosti.

Vytvoření nového projektu aplikace pro UPW

V sadě Microsoft Visual Studio vytvořte nový projekt aplikace pro UPW. Přejděte na Soubor > Nový > Project a vyberte Prázdná aplikace (Univerzální aplikace pro Windows) projazyka C# a potom klikněte na Další. V dialogovém okně Konfigurovat nový projekt. Pojmenujte projekt DevicePortalProvider a potom klikněte na Vytvořit. Bude to aplikace, která obsahuje službu App Service. Možná budete muset aktualizovat Sadu Visual Studio nebo nainstalovat nejnovější sadu Windows SDK.

Přidání rozšíření devicePortalProvider do manifestu balíčku aplikace

Do souboru package.appxmanifest budete muset přidat nějaký kód, aby vaše aplikace fungovala jako plugin pro Device Portal. Nejprve do horní části souboru přidejte následující definice oboru názvů. Přidejte je také do atributu 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">
    ...

Abyste mohli deklarovat, že vaše aplikace je zprostředkovatelem portálu zařízení, musíte vytvořit službu App Service a nové rozšíření zprostředkovatele portálu zařízení, které ji používá. Do elementu Extensions pod Applicationpřidejte rozšíření windows.appService i rozšíření windows.devicePortalProvider. Ujistěte se, že se atributy AppServiceName shodují v jednotlivých rozšířeních. To značí službě Portál zařízení, že tuto službu App Service je možné spustit za účelem zpracování požadavků v oboru názvů obslužné rutiny.

...   
<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 odkazuje na obor názvů REST deklarovaný vaší aplikací. Všechny požadavky HTTP na tento obor názvů (implicitně následované zástupným znakem) přijaté službou Portál zařízení se odešlou do vaší aplikace, aby se zpracovávaly. V takovém případě se do vaší aplikace odešle jakýkoli úspěšně ověřený požadavek HTTP na <ip_address>/MyNamespace/api/*. Konflikty mezi trasami obslužné rutiny se řeší pomocí pravidla „vyhrává nejdelší shoda“: vybírá se ta trasa, která odpovídá více požadavkům, což znamená, že požadavek na "/MyNamespace/api/foo" se bude shodovat s poskytovatelem na adrese "/MyNamespace/api", nikoli s adresou "/MyNamespace".

Pro tuto funkci jsou vyžadovány dvě nové funkce. musí být také přidány do souboru package.appxmanifest.

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

Poznámka:

Možnost devicePortalProvider je omezená (rescap), což znamená, že před publikováním aplikace musíte získat předchozí schválení ze Storu. To vám nebrání v místním testování aplikace prostřednictvím bočního načítání. Další informace o omezených možnostech najdete v tématu Deklarace schopností aplikace.

Nastavení úlohy na pozadí a komponenty WinRT

Aby bylo možné nastavit připojení portálu zařízení, musí vaše aplikace připojit připojení služby App Service ze služby Portál zařízení s instancí portálu zařízení spuštěnou v rámci vaší aplikace. Uděláte to tak, že do aplikace přidáte novou komponentu WinRT s třídou, která implementuje 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;
        //...
    }

Ujistěte se, že jeho název odpovídá oboru názvů a názvu třídy nastavenému objektem AppService EntryPoint (MySampleProvider.SampleProvider). Když učiníte první přístup ke svému poskytovateli zařízení Device Portal, tento portál žádost uloží, spustí úlohu na pozadí vaší aplikace, zavolá její metodu Spustit a předá ji instanci IBackgroundTaskInstance. Aplikace ji pak použije k nastavení instance DevicePortalConnection.

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

Aplikace musí zpracovat dvě události, aby dokončila smyčku zpracování požadavků: Uzavřeno, kdykoli se služba Portálu zařízení vypne, a PožadavekPřijato, která zpracovává příchozí požadavky HTTP a zajišťuje hlavní funkčnost poskytovatele Portálu zařízení.

Zpracování události RequestReceived

Událost RequestReceived se vyvolá jednou pro každý HTTP požadavek, který je proveden na zadané cestě obslužné rutiny pluginu. Smyčka zpracování požadavků pro poskytovatele portálu zařízení je podobná té v NodeJS Express: objekty požadavku a odpovědi jsou k dispozici společně s událostí a obslužná rutina reaguje vyplněním objektu odpovědi. U poskytovatelů portálu zařízení událost RequestReceived a její obslužné rutiny používají objekty Windows.Web.Http.HttpRequestMessage a 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;            
    }
    //...
}

V této ukázkové obslužné rutině požadavku nejprve získáme objekty požadavku a odpovědi z parametru args, a poté vytvoříme řetězec s adresou URL požadavku a s dalším HTML formátováním. To se přidá do objektu Response jako HttpStringContent instance. Jsou povoleny i jiné třídy IHttpContent, jako jsou třídy String a Buffer.

Odpověď se pak nastaví jako odpověď HTTP a dostane stavový kód 200 (OK). Měl by se vykreslit podle očekávání v prohlížeči, který provedl původní volání. Všimněte si, že když se obslužná rutina události RequestReceived vrátí, odpovědní zpráva se automaticky vrátí uživatelskému agentovi: není nutné použít žádnou další metodu "send".

zpráva odpovědi na portálu zařízení

Poskytování statického obsahu

Statický obsah lze obsluhovat přímo ze složky v balíčku, což usnadňuje přidání uživatelského rozhraní k vašemu poskytovateli. Nejjednodušší způsob, jak obsluhovat statický obsah, je vytvořit v projektu složku obsahu, která se může mapovat na adresu URL.

složka statického obsahu portálu zařízení

Potom přidejte obslužnou rutinu trasy do RequestReceived obslužné rutiny události, která detekuje trasy statického obsahu a mapuje požadavek odpovídajícím způsobem.

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");
    }
}

Ujistěte se, že jsou všechny soubory ve složce obsahu označené jako "Obsah" a že v nabídce Vlastnosti sady Visual Studio je nastavená možnost Kopírovat, pokud je novější nebo Kopírovat vždy. Tím se zajistí, že se soubory při nasazení budou v balíčku AppX nacházet.

konfigurace kopírování souboru statického obsahu

Použití existujících prostředků a rozhraní API portálu zařízení

Statický obsah obsluhovaného poskytovatelem portálu zařízení se obsluhuje na stejném portu jako základní služba Portál zařízení. To znamená, že ve svém HTML můžete jednoduše používat značky <link> a <script> pro odkazování na stávající JS a CSS zahrnuté v portálu zařízení. Obecně doporučujeme použít rest.js, který zabalí všechna základní rozhraní REST API portálu zařízení do pohodlného objektu webbRest a soubor common.css, který vám umožní stylovat obsah tak, aby se vešl do zbytku uživatelského rozhraní portálu zařízení. Příklad najdete na stránce index.html, která je součástí ukázky. Používá rest.js k načtení názvu zařízení a spuštěných procesů z portálu zařízení.

výstup plug-in modulu portálu zařízení

Důležité je, že použití metod HttpPost/DeleteExpect200 na webbRest automaticky provede CSRF zpracování, což webové stránce umožňuje volat rozhraní REST API pro změnu stavu.

Poznámka:

Statický obsah, který je součástí portálu zařízení, neposkytuje záruku proti zásadním změnám. Ačkoli se neočekává, že se rozhraní API budou často měnit, mohou se měnit zejména v souborech common.js a controls.js, které by váš poskytovatel neměl používat.

Ladění připojení k portálu pro zařízení

Aby bylo možné ladit úlohu na pozadí, musíte změnit způsob, jakým Visual Studio spouští váš kód. Při ladění připojení služby App Service postupujte podle následujících kroků a zkontrolujte, jak váš poskytovatel zpracovává požadavky HTTP:

  1. V nabídce Ladění vyberte DevicePortalProvider Properties.
  2. Na kartě Ladění v části Akce Start vyberte "Nespouštět, ale ladit můj kód při spuštění".
    umístit modul plug-in do režimu ladění
  3. Nastavte zarážku v handleru RequestReceived. bod přerušení v obslužné rutině požadavkupřijato

Poznámka:

Ujistěte se, že architektura sestavení přesně odpovídá architektuře cíle. Pokud používáte 64bitový počítač, musíte ho nasadit pomocí sestavení AMD64. 4. Stisknutím klávesy F5 nasaďte aplikaci 5. Vypněte portál zařízení a pak ho znovu zapněte, aby našla vaši aplikaci (jenom když změníte manifest aplikace – zbytek času můžete jednoduše znovu nasadit a přeskočit tento krok). 6. V prohlížeči přejděte do jmenného prostoru poskytovatele, a zarážka by měla být dosažena.

  • Last updated on