Escribir un complemento personalizado para el Portal de dispositivos Windows

Puedes escribir una aplicación empaquetada (UWP o Win32 empaquetada mediante SDK de Aplicaciones para Windows) que usa el portal de dispositivos de Windows para hospedar una página web y proporcionar información de diagnóstico. La funcionalidad del complemento Device Portal se implementa mediante la windows.devicePortalProvider extensión , que está disponible para todas las aplicaciones empaquetadas independientemente del marco de interfaz de usuario.

Note

Este artículo está dirigido a desarrolladores que crean herramientas de diagnóstico o administración para dispositivos IoT Enterprise, implementaciones de quiosco multimedia u otros entornos de Windows administrados en los que se usa Device Portal para la supervisión remota. Si va a crear una aplicación de escritorio estándar Windows 11, es poco probable que necesite un complemento device Portal, considere la posibilidad de usar diagnósticos de aplicaciones o Windows Analizador de rendimiento en su lugar.

La compatibilidad con complementos de Device Portal está disponible en Windows 10 y versiones posteriores.

Creación del proyecto

Cree un nuevo proyecto de aplicación en Microsoft Visual Studio. Vaya a Archivo > Nuevo > Proyecto y seleccione una de las siguientes plantillas de proyecto:

• Para una aplicación UWP: Aplicación vacía (Windows Universal) para C#
• Para una aplicación de escritorio WinUI 3: Aplicación vacía empaquetada (WinUI 3 para escritorio)

En el cuadro de diálogo Configurar el nuevo proyecto , asigne al proyecto el nombre DevicePortalProvider y, a continuación, haga clic en Crear. Esta será la aplicación que contiene el servicio de aplicaciones.

Adición de la funcionalidad devicePortalProvider

Añade la capacidad rescap:devicePortalProvider al archivo Package.appxmanifest de tu aplicación.

Note

El rescap espacio de nombres (funcionalidad restringida) debe declararse antes de poder usarse. Consulte Declaraciones de funcionalidad de la aplicación para obtener más información.

En Explorador de soluciones, haga doble clic Package.appxmanifest para abrir el diseñador de manifiestos y, a continuación, cambie a la pestaña Funcionalidades y compruebe proveedor del portal de dispositivos si aparece o agréguelo manualmente editando el XML.

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

Configuración del servicio de aplicaciones

Los complementos de Device Portal usan servicios de aplicaciones para comunicarse entre el proceso de host del complemento y Device Portal. Abra Package.appxmanifest, vaya a la pestaña Declaraciones, agregue una declaración de Windows Device Portal Provider y configúrela con el nombre del servicio.

Como alternativa, edite el XML directamente:

<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

Los prefijos de espacio de nombres XML uap3 y uap4 deben declararse en el elemento raíz <Package> de su manifiesto y agregarse al 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">

Los atributos siguientes requieren la configuración específica de la aplicación:

Atributo	Descripción
EntryPoint	Especifica la clase que implementa el servicio de aplicaciones.
Name (AppService)	Nombre único del servicio de aplicaciones. Este nombre se usa como atributo AppServiceName en el DevicePortalProvider elemento .
DisplayName	Nombre que aparecerá en la interfaz de usuario del Portal de dispositivos.
HandlerRoute	El prefijo de la ruta URL que Device Portal usa para redirigir las solicitudes a tu complemento. Todas las solicitudes cuya ruta de acceso comienza con este valor se reenvieron al servicio de aplicaciones. La ruta debe comenzar y terminar con barras diagonales.

Agrega el código de App Service

Agregue un proyecto de componente de Windows Runtime a la solución para hospedar el servicio de aplicaciones en segundo plano:

1. En Explorador de soluciones, haga clic con el botón derecho en la solución y seleccione Agregar > nuevo Project.
2. Seleccione Windows Runtime Componente (Windows universal) y asígneles el nombre DevicePortalProvider.
3. Haga clic con el botón derecho en el nuevo proyecto y seleccione Añadir > Nuevo elemento > Servicio de aplicación.

Los detalles de implementación del código de App Service se encuentran en el artículo Creación y consumo de un servicio de aplicaciones .

Implementación del controlador de Device Portal

Esta es una implementación de ejemplo de un servicio de aplicaciones del complemento Device Portal:

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

Control de solicitudes entrantes

El controlador del complemento recibe todas las solicitudes GET, POST, DELETE y PUT que Device Portal dirige a HandlerRoute. Una implementación 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 contenido estático

Si quieres proporcionar contenido web (HTML, CSS, JavaScript) desde el paquete de la aplicación, puedes colocar esos archivos en una carpeta y responder a las solicitudes con el contenido del archivo.

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

Ejecute el servicio de la aplicación como Sistema

En algunos casos, para realizar pruebas completas del complemento Device Portal, es posible que deba ejecutar el complemento como cuenta del sistema. Consulte el artículo de MSDN Magazine para obtener más información.

Consulte también

• Introducción a Windows Device Portal
• Declaraciones de funcionalidad de la aplicación
• Crear y consumir un servicio de aplicación
• Referencia de api principal de Windows Device Portal