Escreva um plug-in personalizado para o Windows Device Portal

Saiba como escrever um aplicativo UWP que usa o Windows Device Portal (WDP) para hospedar uma página da Web e fornecer informações de diagnóstico.

A partir do Windows 10 Creators Update (versão 1703, compilação 15063), você pode usar o Device Portal para hospedar as interfaces de diagnóstico do seu aplicativo. Este artigo aborda as três partes necessárias para criar um DevicePortalProvider para a sua aplicação – as alterações do manifesto do pacote da aplicação , configurando a ligação da sua aplicação ao serviço Device Portal , e gerir um pedido de entrada.

Criar um novo projeto de aplicativo UWP

No Microsoft Visual Studio, crie um novo projeto de aplicativo UWP. Vá para > Novo Projeto > e selecione Aplicativo em Branco (Windows Universal) paraC# e clique em Avançar. Na caixa de diálogo Configurar o seu novo projeto. Nomeie o projeto "DevicePortalProvider" e clique em Criar. Este será o aplicativo que contém o serviço de aplicativo. Talvez seja necessário atualizar o Visual Studio ou instalar o SDK mais recente do Windows.

Adicione a extensão devicePortalProvider ao manifesto do pacote do aplicativo

Você precisará adicionar algum código ao seu arquivo de package.appxmanifest do para tornar seu aplicativo funcional como um plug-in do Device Portal. Primeiro, adicione as seguintes definições de namespace na parte superior do arquivo. Adicione-os também ao atributo 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">
    ...

Para declarar que seu aplicativo é um Provedor de Portal de Dispositivo, você precisa criar um serviço de aplicativo e uma nova extensão de Provedor de Portal de Dispositivo que o use. Adicione a extensão windows.appService e a extensão windows.devicePortalProvider no elemento Extensions em Application. Certifique-se de que os atributos AppServiceName correspondem em cada extensão. Isso indica ao serviço Device Portal que esse serviço de aplicativo pode ser iniciado para lidar com solicitações no namespace do manipulador.

...   
<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>
...

O atributo HandlerRoute faz referência ao namespace REST reivindicado pelo seu aplicativo. Todas as solicitações HTTP nesse namespace (implicitamente seguidas por um curinga) recebidas pelo serviço Device Portal serão enviadas ao seu aplicativo para serem tratadas. Nesse caso, qualquer solicitação HTTP autenticada com êxito para <ip_address>/MyNamespace/api/* será enviada para seu aplicativo. Os conflitos entre as rotas do manipulador são resolvidos por meio de uma verificação de "vitórias mais longas": qualquer rota que corresponda a mais solicitações é selecionada, o que significa que uma solicitação para "/MyNamespace/api/foo" corresponderá a um provedor com "/MyNamespace/api" em vez de uma com "/MyNamespace".

Dois novos recursos são necessários para essa funcionalidade. eles também devem ser adicionados ao arquivo package.appxmanifest do .

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

Configure a sua tarefa em segundo plano e o Componente WinRT

Para configurar a ligação do Device Portal, a sua aplicação deve estabelecer uma ligação de serviço de aplicação do serviço Device Portal com a instância do Device Portal a operar na sua aplicação. Para fazer isso, adicione um novo componente WinRT ao seu aplicativo com uma classe que implementa 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;
        //...
    }

Verifique se seu nome corresponde ao namespace e ao nome da classe configurados pelo AppService EntryPoint ("MySampleProvider.SampleProvider"). Quando fizeres a tua primeira solicitação ao provedor do Device Portal, o Device Portal armazenará a solicitação, iniciará a tarefa em segundo plano da tua aplicação, chamará o seu método Run e passará um IBackgroundTaskInstance. Em seguida, seu aplicativo o usa para configurar uma instância de 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;
}

Há dois eventos que devem ser manipulados pelo aplicativo para concluir o loop de tratamento de solicitações: Closed, para sempre que o serviço Device Portal for desligado, e RequestReceived, que apresenta solicitações HTTP de entrada e fornece a funcionalidade principal do provedor do Device Portal.

Manipular o evento 'RequestReceived'

O evento RequestReceived será gerado uma vez para cada solicitação HTTP feita na rota do manipulador especificada do plug-in. O loop de tratamento de solicitação para provedores do Device Portal é semelhante ao do NodeJS Express: os objetos de solicitação e resposta são fornecidos junto com o evento e o manipulador responde preenchendo o objeto de resposta. Nos provedores do Device Portal, o evento RequestReceived e os seus gestores utilizam objetos do tipo Windows.Web.Http.HttpRequestMessage e 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;            
    }
    //...
}

Neste manipulador de solicitação de exemplo, primeiro extraímos os objetos de solicitação e resposta do parâmetro args e, em seguida, criamos uma cadeia de caracteres com a URL da solicitação e alguma formatação HTML adicional. Isso é adicionado no objeto Response como uma instância de HttpStringContent. Outras classes de IHttpContent, como as de "String" e "Buffer", também são permitidas.

A resposta é então definida como uma resposta HTTP e recebe um código de status 200 (OK). Ele deve renderizar como esperado no navegador que fez a chamada original. Observe que quando o manipulador de eventos RequestReceived retorna, a mensagem de resposta é retornada automaticamente ao agente do usuário: nenhum método "send" adicional é necessário.

Fornecimento de conteúdo estático

O conteúdo estático pode ser servido diretamente de uma pasta dentro do seu pacote, tornando muito fácil adicionar uma interface do usuário ao seu provedor. A maneira mais fácil de fornecer conteúdo estático é criar uma pasta de conteúdo em seu projeto que possa ser mapeada para uma URL.

Em seguida, adicione um manipulador de rotas em seu manipulador de eventos RequestReceived que deteta rotas de conteúdo estático e mapeia uma solicitação adequadamente.

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

Certifique-se de que todos os arquivos dentro da pasta de conteúdo estão marcados como "Conteúdo" e definido como "Copiar se mais recente" ou "Copiar sempre" no menu Propriedades do Visual Studio. Isso garante que os arquivos estarão dentro do seu pacote AppX quando você implantá-lo.

Usando APIs e recursos existentes do Device Portal

O conteúdo estático servido por um provedor do Device Portal é servido na mesma porta que o serviço principal do Device Portal. Isso significa que você pode referenciar o JS e o CSS existentes incluídos no Device Portal com as simples tags <link> e <script> no seu HTML. Em geral, sugerimos o uso de rest.js, que envolve todas as APIs REST principais do Device Portal em um objeto webbRest conveniente, e o arquivo common.css, que permitirá que você estilize seu conteúdo para se ajustar ao resto da interface do usuário do Device Portal. Você pode ver um exemplo disso na página de index.html incluída no exemplo. Ele usa rest.js para recuperar o nome do dispositivo e processos em execução do Device Portal.

É importante ressaltar que o uso dos métodos HttpPost/DeleteExpect200 no webbRest fará automaticamente a de manipulação de CSRF para você, o que permite que sua página da Web chame APIs REST que mudam de estado.

Depurando a conexão com o Device Portal

Para depurar sua tarefa em segundo plano, você deve alterar a maneira como o Visual Studio executa seu código. Siga as etapas abaixo para depurar uma conexão de serviço de aplicativo para inspecionar como seu provedor está lidando com as solicitações HTTP:

1. No menu Depurar, selecione Propriedades de DevicePortalProvider.
2. Na guia Depuração, na seção Ação de início, selecione "Não iniciar, mas depurar o meu código quando ele iniciar".
   
3. Defina um ponto de interrupção na função de manipulador RequestReceived.

Tópicos relacionados

• Visão geral do Windows Device Portal
• Criar e consumir um serviço de aplicativo