Gravar um plug-in personalizado para o Portal de Dispositivos do Windows

Você pode escrever um aplicativo empacotado (UWP ou Win32 empacotado usando SDK do Aplicativo Windows) que usa o Portal do Dispositivo Windows para hospedar uma página da Web e fornecer informações de diagnóstico. A funcionalidade de plug-in do Portal do Dispositivo é implementada usando a windows.devicePortalProvider extensão, que está disponível para todos os aplicativos empacotados, independentemente da estrutura da interface do usuário.

O suporte ao plug-in do Portal do Dispositivo está disponível em Windows 10 e posteriores.

Criar o projeto

Crie um novo projeto de aplicativo no Microsoft Visual Studio. Vá para Arquivo > Novo > Projeto e selecione um dos seguintes modelos de projeto:

• Para um aplicativo UWP: aplicativo em branco (Windows Universal) para C#
• Para um aplicativo da área de trabalho WinUI 3: Aplicativo em branco, Empacotado (WinUI 3 na Área de Trabalho)

Na caixa de diálogo Configurar seu novo projeto , nomeie o projeto DevicePortalProvider e clique em Criar. Esse será o aplicativo que contém o serviço de aplicativo.

Adicionar a funcionalidade devicePortalProvider

Adicione o recurso rescap:devicePortalProvider ao arquivo Package.appxmanifest do seu aplicativo.

Em Gerenciador de Soluções, clique duas vezes em Package.appxmanifest para abrir o designer de manifesto, depois mude para a guia Recursos e marque Provedor do Portal do Dispositivo, se estiver listado, ou adicione-o manualmente editando o XML.

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

Configurar o serviço de aplicativo

Os plug-ins do Portal do Dispositivo usam serviços de aplicativo para se comunicar entre o processo de host do plug-in e o Portal do Dispositivo. Abra Package.appxmanifest, mude para a guia Declarações, adicione a declaração Provedor do Portal de Dispositivos do Windows e configure-a com o nome do serviço.

Como alternativa, 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>

<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 atributos a seguir exigem uma configuração específica para seu aplicativo:

Adicionar o código do serviço de aplicativo

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

1. Em Gerenciador de Soluções, clique com o botão direito do mouse na solução e selecione Adicionar > Novo Project.
2. Selecione Windows Runtime Componente (Windows Universal) e nomeie-o DevicePortalProvider.
3. Clique com o botão direito do mouse no novo projeto e selecione Adicionar > Novo Item > Serviço de Aplicativo.

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

Implementar o manipulador do Portal de Dispositivos

Aqui está uma implementação de exemplo de um serviço de aplicativo plug-in do Portal do Dispositivo:

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

Tratar solicitações recebidas

Seu manipulador de plugin recebe todas as solicitações GET, POST, DELETE e PUT que o Device Portal encaminha para 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 você quiser fornecer conteúdo da Web (HTML, CSS, JavaScript) dentro do pacote do aplicativo, poderá colocar esses arquivos em uma pasta e responder a solicitações com o conteúdo do arquivo.

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 aplicativo como Sistema

Em alguns casos, para concluir o teste do plug-in do Portal do Dispositivo, talvez seja necessário executar o plug-in como a conta do sistema. Consulte o artigo da Revista MSDN para obter detalhes.

Consulte também

• Visão geral do Portal do Dispositivo Windows
• Declarações de funcionalidades do aplicativo
• Criar e consumir um serviço de aplicativo
• Referência da API principal do Portal do Dispositivo Windows