Escreva um plug-in personalizado para o Windows Device Portal

Pode escrever uma aplicação empacotada (UWP ou Win32 empacotada usando SDK de Aplicações Windows) que utilize o Portal de Dispositivos Windows para hospedar uma página web e fornecer informação de diagnóstico. A funcionalidade do plug-in Portal de Dispositivos é implementada usando a windows.devicePortalProvider extensão, que está disponível para todas as aplicações incluídas, independentemente do framework da interface.

Note

Este artigo destina-se a programadores que estão a construir ferramentas de diagnóstico ou gestão para dispositivos IoT Enterprise, implantações de quiosques ou outros ambientes Windows geridos onde o Portal de Dispositivos é utilizado para monitorização remota. Se estiver a construir uma aplicação de ambiente de trabalho Windows 11 padrão, é pouco provável que precise de um plugin para o Portal de Dispositivos — considere usar o diagnóstico de aplicações ou Windows Analisador de Desempenho em vez disso.

O suporte a plugins do Portal de Dispositivos está disponível no Windows 10 e versões posteriores.

Criar o projeto

Crie um novo projeto de aplicação em Microsoft Visual Studio. Vá a File > New > Project e selecione um dos seguintes modelos de project:

  • Para uma aplicação UWP: Blank App (Windows Universal) para C#
  • Para uma aplicação desktop WinUI 3: Aplicação em branco, Empacotada (WinUI 3 no ambiente de trabalho)

Na caixa de diálogo Configurar o seu novo projeto , nomeie o projeto como DevicePortalProvider e depois clique em Criar. Esta será a aplicação que contém o serviço de aplicação.

Adicionar a capacidade devicePortalProvider

Adicione a rescap:devicePortalProvider funcionalidade ao ficheiro Package.appxmanifest da sua aplicação.

Note

O espaço de nomes rescap (Capacidade Restrita) deve ser declarado antes de que possa ser utilizado. Consulte as declarações de capacidades da aplicação para mais detalhes.

No Explorador de Soluções, clique Package.appxmanifest duas vezes para abrir o designer do manifesto, depois mude para o separador Capacidades e verifique o Fornecedor do Portal de Dispositivos se estiver listado, ou adicione-o manualmente editando o XML.

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

Configurar o serviço de aplicação

Os plugins do Portal de Dispositivos usam serviços de aplicação para comunicar entre o processo anfitrião do plugin e o Portal do Dispositivo. Abrir Package.appxmanifest, mudar para o separador Declarações, adicionar uma declaração do Provedor do Portal de Dispositivos Windows e configurá-la com o nome do serviço.

Alternativamente, edite o XML diretamente:

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

Importante

Os prefixos de namespace XML uap3 e uap4 têm de ser declarados no elemento raiz <Package> do seu manifesto e adicionados ao atributo 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">

Os seguintes atributos requerem uma configuração específica para a sua aplicação:

Attribute Descrição
EntryPoint Especifica a classe que implementa o serviço de aplicação.
Name (AppService) O nome único do serviço de aplicação. Este nome é usado como AppServiceName atributo no DevicePortalProvider elemento.
DisplayName O nome que aparecerá na interface do Portal de Dispositivos.
HandlerRoute O prefixo de caminho URL que o Portal de Dispositivos usa para encaminhar pedidos para o seu plugin. Todos os pedidos cujo caminho começa com este valor são encaminhados para o seu serviço de aplicação. A rota deve começar e terminar com cortes.

Adicionar o código do serviço de aplicação

Adicione um projeto Windows Runtime Component à sua solução para hospedar o serviço de aplicação em segundo plano:

  1. No Explorador de Soluções, clique com o botão direito na solução e selecione Adicionar > Novo Project.
  2. Selecione Windows Runtime Component (Universal Windows) e chame-lhe DevicePortalProvider.
  3. Clique com o botão direito no novo projeto e selecione Adicionar > Novo Item > Serviço de Aplicação.

Os detalhes da implementação do código do serviço de aplicação estão no artigo Criar e consumir um serviço de aplicação .

Implemente o seu handler de Portal de Dispositivos

Aqui está um exemplo de implementação de um serviço de aplicação plugin para o Portal de Dispositivos:

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

Lidar com pedidos recebidos

O seu processador de plug-ins recebe todos os pedidos GET, POST, DELETE e PUT que o Portal de Dispositivos encaminha para o seu HandlerRoute. Uma implementação típica:

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

Servir conteúdo estático

Se quiser servir conteúdo web (HTML, CSS, JavaScript) a partir do pacote da sua aplicação, pode colocar esses ficheiros numa pasta e responder a pedidos com o conteúdo do ficheiro.

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

Executar o serviço de aplicação como Sistema

Em alguns casos, para testes completos do plugin Device Portal, pode ser necessário executar o plugin como conta do Sistema. Consulte o artigo da MSDN Magazine para mais detalhes.

Consulte também

  • Last updated on