Напишите настраиваемый плагин для портала устройств Windows

Вы можете написать упаковаемое приложение (UWP или упаковано Win32 с помощью Windows App SDK), которое использует портал устройств Windows для размещения веб-страницы и предоставления диагностических сведений. Функция подключаемого модуля портала устройств реализуется с помощью windows.devicePortalProvider расширения, которое доступно для всех упакованных приложений независимо от платформы пользовательского интерфейса.

Note

Эта статья предназначена для разработчиков создания средств диагностики или управления для устройств IoT Enterprise, развертываний киосков или других управляемых Windows сред, где портал устройств используется для удаленного мониторинга. Если вы создаете стандартное классическое приложение для Windows 11, вам, скорее всего, не понадобится подключаемый модуль для Портала устройств — лучше использовать Диагностика приложений или Windows Анализатор производительности.

Поддержка плагина Device Portal доступна в Windows 10 и более поздних версиях Windows.

Создание проекта

Создайте проект приложения в Microsoft Visual Studio. Перейдите в Файл > Создать > Проект и выберите один из следующих шаблонов проектов:

  • Для приложения UWP: Пустое приложение (универсальное приложение Windows) для C#
  • Для классического приложения WinUI 3: Пустое приложение, упакованное (WinUI 3 в классическом приложении)

В диалоговом окне "Настройка нового проекта " назовите проект DevicePortalProvider и нажмите кнопку "Создать". Это будет приложение, содержащее службу приложений.

Добавьте возможность devicePortalProvider

Добавьте возможность rescap:devicePortalProvider в файл Package.appxmanifest вашего приложения.

Note

Пространство имен rescap (с ограниченными возможностями) необходимо объявить, прежде чем его можно будет использовать. Дополнительные сведения см. в объявлениях возможностей приложений .

В Обозреватель решений дважды щелкнитеPackage.appxmanifest, чтобы открыть конструктор манифестов, а затем перейдите на вкладку "Возможности" и проверьте поставщик портала устройств, если он указан, или вручную добавьте его, изменив XML.

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

Настройка службы приложений

Подключаемые модули портала устройств используют службы приложений для обмена данными между процессом узла подключаемого модуля и порталом устройств. ОткройтеPackage.appxmanifest, перейдите на вкладку "Объявления", добавьте объявление поставщика портала устройств Windows и настройте его с именем службы.

Кроме того, измените XML напрямую:

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

Important

Префиксы пространства имён XML uap3 и uap4 должны быть объявлены в корневом элементе <Package> вашего манифеста и добавлены в атрибут 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">

Для следующих атрибутов требуется конфигурация, связанная с приложением:

Атрибут Описание
EntryPoint Указывает класс, реализующий службу приложений.
Name (AppService) Уникальное имя службы приложений. Это имя используется в качестве AppServiceName атрибута в элементе DevicePortalProvider .
DisplayName Имя, которое появится в пользовательском интерфейсе портала устройств.
HandlerRoute Префикс пути URL-адреса, который Device Portal использует для маршрутизации запросов к вашему подключаемому модулю. Все запросы, путь которых начинается с этого значения, перенаправляются в службу приложений. Маршрут должен начинаться и заканчиваться косыми чертами.

Добавление кода службы приложений

Добавьте проект компонента среда выполнения Windows в решение для размещения фоновой службы приложений:

  1. В Обозреватель решений щелкните правой кнопкой мыши по решению и выберите Добавить > новый проект.
  2. Выберите компонент среда выполнения Windows (универсальная Windows) и назовите его DevicePortalProvider.
  3. Щелкните правой кнопкой мыши по новому проекту и выберите Добавить > Новый элемент > Служба приложений.

Сведения о реализации кода службы приложений приведены в статье "Создание и использование службы приложений ".

Реализуйте обработчик 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
        }
    }
}

Обработка входящих запросов

Обработчик подключаемого модуля получает все запросы GET, POST, DELETE и PUT, которые Device Portal перенаправляет в ваш HandlerRoute. Типичная реализация:

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

Обслуживание статического содержимого

Если вы хотите обслуживать веб-содержимое (HTML, CSS, JavaScript) из пакета приложения, вы можете поместить эти файлы в папку и ответить на запросы с содержимым файла.

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

Запуск службы приложений в качестве системы

В некоторых случаях для полного тестирования подключаемого модуля портала устройств может потребоваться запустить подключаемый модуль в качестве учетной записи системы. Дополнительные сведения см. в статье msdn Magazine .

См. также

  • Last updated on