處理 URI 啟用

發行項
02/20/2025

瞭解如何註冊應用程式，以成為統一資源標識碼（URI）配置名稱的預設處理程式。 Windows 傳統型應用程式和通用 Windows 平臺（UWP）應用程式都可以註冊為 URI 配置名稱的預設處理程式。如果使用者選擇您的應用程式作為 URI 配置名稱的預設處理程式，則每次啟動該類型的 URI 時，都會啟動您的應用程式。

建議您只有在預期處理所有該類型 URI 協議的啟動時，才註冊 URI 協議名稱。如果您選擇註冊 URI 配置名稱，則必須為終端使用者提供針對該 URI 配置啟用應用程式時預期的功能。例如，註冊 mailto：URI 配置名稱的應用程式應該會開啟至新的電子郵件訊息，讓使用者可以撰寫新的電子郵件。如需 URI 關聯的詳細資訊，請參閱檔案、資料夾和連結庫。

這些步驟示範如何註冊自定義 URI 配置名稱、alsdk://，以及如何在用戶啟動 alsdk:// URI 時啟用您的應用程式。

重要 API

本主題中會使用下列 API：

注意

在 Windows 中，某些 URI 和副檔名會保留供內建應用程式和作業系統使用。當嘗試向保留的 URI 或檔案副檔名註冊您的應用程式時，系統會忽略這些動作。請參閱保留的 URI 配置名稱和檔案類型，以取得您無法註冊應用程式的 URI 配置字母清單，因為這些配置是保留或禁止的。

步驟 1：指定封裝指令清單中的擴充點

應用程式只會針對套件指令清單中列出的URI配置名稱接收啟用事件。以下是如何指示您的應用程式處理 alsdk URI 協議名稱的方法。

在 [方案總管]中，雙擊 package.appxmanifest 以開啟清單設計工具。選取 [宣告] 索引標籤，然後在 [可用的 宣告] 下拉式清單中，選取 [通訊協定]，然後按兩下 [[新增]。

以下是您可以填入通訊協定指令清單設計工具之每個欄位的簡短描述（如需詳細資訊，請參閱 AppX 套件指令清單）：

田	描述
標誌	在 [控制面板]中的 [設定預設程式] 中，指定用於識別 URI 配置名稱的標誌。如果未指定標誌，則會使用應用程式的小型標誌。
顯示名稱	指定顯示名稱，以便在 [控制面板][設定預設程式] 中識別 URI 協議名稱。
名稱	選擇 URI 結構的名稱。
	附註 [名稱] 必須全部以小寫字母為單位。
	保留和禁止的檔案類型請參閱保留的 URI 配置名稱和檔案類型，以取得您無法註冊 Windows 應用程式的字母清單，因為它們是保留或禁止的。
可執行檔	指定通訊協議的預設啟動可執行檔。如果未指定，則會使用應用程式的可執行檔。如果指定，字串長度必須介於 1 到 256 個字元之間，必須以 “.exe” 結尾，且不能包含下列字元：>、<、：、、、\|、？或。如果指定，也會使用進入點。如果未指定進入點*，則會使用為應用程式定義的進入點。
進入點	指定處理通訊協定延伸的工作。這通常是 Windows 執行階段類型的完整命名空間合格名稱。如果未指定，則會使用應用程式的進入點。
起始頁	處理延展性點的網頁。
資源群組	可用來將擴充功能的啟用集結在一起的標記，以供資源管理之用。
所需檢視（僅限 Windows）	指定 [Desired View] 字段，以指出應用程式視窗針對 URI 配置名稱啟動時所需的空間量。 Desired View 的可能值為 Default、UseLess、UseHalf、UseMore或 UseMinimum。注意 Windows 在判斷目標應用程式的最終視窗大小時，會考慮多種不同的因素，例如來源應用程式的喜好設定、螢幕上的應用程式數目、螢幕方向等等。設定 Desired View 並不保證目標應用程式的特定視窗化行為。行動裝置系列：行動裝置系列不支援所需的檢視。

輸入 images\Icon.png 做為標誌。
輸入 SDK Sample URI Scheme 作為 顯示名稱
輸入 alsdk 作為名稱。
按 Ctrl+S 將變更儲存至 package.appxmanifest。

這樣會將類似的 Extension 元素新增到套件清單中。 windows.protocol 類別指出應用程式會處理 alsdk URI 配置名稱。

    <Applications>
        <Application Id= ... >
            <Extensions>
                <uap:Extension Category="windows.protocol">
                  <uap:Protocol Name="alsdk">
                    <uap:Logo>images\icon.png</uap:Logo>
                    <uap:DisplayName>SDK Sample URI Scheme</uap:DisplayName>
                  </uap:Protocol>
                </uap:Extension>
          </Extensions>
          ...
        </Application>
   </Applications>

步驟 2：新增適當的圖示

成為 URI 設定名稱預設值的應用程式，其圖示會顯示在系統的各個位置，例如在 [預設程式] 控制面板中。針對此目的，請將 44x44 圖示與您的專案一起納入。比對應用程式磚標誌的外觀，並使用應用程式的背景色彩，而不是讓圖示透明。讓標誌延伸至邊緣，不留空白。在白色背景上測試您的圖示。如需圖示的詳細資訊，請參閱應用程式圖示和標誌。

步驟 3：處理啟動的事件

注意

在 WinUI 應用程式中，在 App.OnLaunched 中（或實際上隨時）您可以呼叫（AppInstance.GetActivatedEventArgs），以擷取啟動的事件自變數，並檢查它們以判斷應用程式是如何啟動的。如需 UWP 與 WinUI 應用程式之間生命週期差異的詳細資訊，請參閱應用程式生命週期功能移轉。

在 UWP 應用程式中，OnActivated 事件處理程式會接收所有啟用事件。 Kind 屬性表示啟用事件的類型。此範例設定為處理通訊協定啟用事件。

public partial class App
{
   protected override void OnActivated(IActivatedEventArgs args)
  {
      if (args.Kind == ActivationKind.Protocol)
      {
         ProtocolActivatedEventArgs eventArgs = args as ProtocolActivatedEventArgs;
         // TODO: Handle URI activation
         // The received URI is eventArgs.Uri.AbsoluteUri
      }
   }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs const& args)
{
    if (args.Kind() == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
    {
        auto protocolActivatedEventArgs{ args.as<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs>() };
        // TODO: Handle URI activation  
        auto receivedURI{ protocolActivatedEventArgs.Uri().RawUri() };
    }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs^ args)
{
   if (args->Kind == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
   {
      Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^ eventArgs =
          dynamic_cast<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^>(args);
      
      // TODO: Handle URI activation  
      // The received URI is eventArgs->Uri->RawUri
   }
}

注意

透過通訊協定合約啟動時，請確定 [上一頁] 按鈕會將使用者帶回啟動應用程式的畫面，而不是應用程式先前的內容。

下列程式代碼會透過其 URI 以程式設計方式啟動應用程式：

   // Launch the URI
   var uri = new Uri("alsdk:");
   var success = await Windows.System.Launcher.LaunchUriAsync(uri)

如需如何透過 URI 啟動應用程式的詳細資訊，請參閱啟動 URI 的預設應用程式。

建議應用程式為每個開啟新頁面的啟用事件建立新的 XAML Frame。如此一來，新 XAML Frame 的流覽後置將不會包含應用程式在暫停時可能在目前視窗上擁有的任何先前內容。決定使用單一 XAML Frame 來處理啟動和文件合約的應用程式，應該在導航至新頁面之前，先清除 Frame 導航日誌上的頁面。

透過通訊協定啟用啟動時，應用程式應考慮包含可讓使用者返回應用程式頂端頁面的 UI。

備註

任何應用程式或網站都可以使用您的 URI 配置名稱，包括惡意名稱。因此，您在 URI 中取得的任何資料都可能來自不受信任的來源。建議您永遠不要根據您在 URI 中收到的參數執行永久動作。例如，URI 參數可用來將應用程式啟動至使用者的帳戶頁面，但我們建議您永遠不要使用這些參數來直接修改用戶帳戶。

注意

如果您要為應用程式建立新的 URI 配置名稱，請務必遵循 RFC 4395中的指引。這可確保您的名稱符合 URI 配置的標準。

注意

透過通訊協定合約啟動 UWP 應用程式時，請確定 [上一頁] 按鈕會將使用者帶回啟動應用程式的畫面，而不是移至應用程式先前的內容。

我們建議應用程式在每次啟用事件中開啟新的 URI 目標時，建立新的 XAML Frame。如此一來，新 XAML Frame 的流覽後置將不會包含應用程式在暫停時可能在目前視窗上擁有的任何先前內容。

如果您決定要讓應用程式使用單一 XAML Frame for Launch and Protocol Contracts，請在流覽至新頁面之前，清除 Frame 瀏覽日誌上的頁面。透過通訊協定合約啟動時，請考慮將UI納入您的應用程式，讓使用者回到應用程式頂端。

共用方式為

處理 URI 啟用

重要 API

步驟 1：指定封裝指令清單中的擴充點

步驟 2：新增適當的圖示

步驟 3：處理啟動的事件

備註

其他資源

共用方式為

處理 URI 啟用

重要 API

步驟 1：指定封裝指令清單中的擴充點

步驟 2：新增適當的圖示

步驟 3：處理啟動的事件

備註

相關內容

其他資源