為 Windows 裝置入口撰寫自訂外掛

你可以寫一個打包的應用程式（UWP 或使用 Windows 應用程式 SDK 打包的 Win32），利用 Windows 裝置入口網站來架設網頁並提供診斷資訊。 Device Portal 外掛功能是透過擴充 windows.devicePortalProvider 功能實作，所有封裝應用程式皆可使用，無論 UI 架構為何。

附註

本文旨在協助為使用 Device Portal 進行遠端監視的 IoT Enterprise 裝置、資訊站部署或其他受管理的 Windows 環境建置診斷或管理工具的開發人員。如果你正在打造標準的Windows 11桌面應用程式，通常不需要裝置入口網站外掛——建議改用應用程式診斷或Windows 效能分析器。

裝置入口網站外掛程式支援適用於 Windows 10 及更新版本。

建立專案

在 Microsoft Visual Studio 建立一個新的應用程式專案。前往檔案>新增>專案，然後選取下列其中一個專案範本：

針對 UWP 應用程式：空白應用程式 (Windows 通用) (C#)
若為 WinUI 3 桌面應用程式：空白應用程式，已封裝（桌面版 WinUI 3）

在 「配置你的新專案 」對話框中，將專案命名 為 DevicePortalProvider，然後點選 「建立」。這將是包含該應用程式服務的應用程式。

新增 devicePortalProvider 功能

把這個 rescap:devicePortalProvider 功能加入你的應用程式 Package.appxmanifest 檔案。

附註

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

uap3 和 uap4 XML 命名空間前綴必須在資訊清單的根 <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">

以下屬性需要針對你的應用程式進行特定設定：

Attribute	說明
`EntryPoint`	指定實作應用程式服務的類別。
`Name` （AppService）	這個應用程式服務的獨特名稱。此名稱會作為 `DevicePortalProvider` 元素中的 `AppServiceName` 屬性使用。
`DisplayName`	裝置入口介面中會出現的名稱。
`HandlerRoute`	裝置入口網站用來將請求導向您的外掛程式的 URL 路徑前綴。所有路徑以此值開始的請求都會轉發到你的應用程式服務。路由必須以斜線（/）開頭和結尾。

新增應用程式服務代碼

在您的解決方案中新增一個 Windows 執行階段元件專案來承載背景應用程式服務：

在 方案總管 中，右鍵點擊該解決方案並選擇新增 > Project。
選擇 Windows 執行階段元件（通用 Windows），並將其命名為 DevicePortalProvider。
右鍵點擊新專案，並選擇 新增 > 項目 > 應用程式服務。

關於 App Service 程式碼實作的詳細資訊，請參閱「建立並消費應用服務」的文章。

實作你的裝置入口處理程式

以下是 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
        }
    }
}

處理傳入請求

你的外掛程式處理常式會接收 Device Portal 路由到你的 HandlerRoute 的所有 GET、POST、DELETE 和 PUT 請求。典型實作：

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

將應用程式服務以 System 帳戶身分執行

在某些情況下，為了完整測試裝置入口外掛，你可能需要以系統帳號執行該外掛。詳情請參閱 MSDN雜誌文章。

另請參閱

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-07-07