處理 URI 啟用

發行項
04/01/2024

重要 API

了解如何登錄應用程式，以使它成為統一資源識別項 (URI) 配置名稱的預設處理常式。 Windows 桌面應用程式和通用 Windows 平台 (UWP) 應用程式都可以註冊為 URI 方案名稱的預設處理程序。如果使用者選擇您的應用程式作為 URI 方案名稱的預設處理程序，則每次啟動該類型的 URI 時都會啟動您的應用程式。

如果您希望處理該類型 URI 方案的所有 URI 啟動，我們建議您僅註冊 URI 方案名稱。如果您選擇註冊 URI 方案名稱，則必須向最終使用者提供為該 URI 方案啟動您的應用程式時所需的功能。例如，註冊 mailto: URI 方案名稱的應用程式應開啟新電子郵件，以便使用者可以撰寫新電子郵件。如需 URI 關聯的詳細資訊，請參閱檔類型和 URI 的指南和檢查清單。

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

注意

在 UWP 應用程式中，某些 URI 和檔案延伸模組會保留供內建應用程式和作業系統使用。系統會忽略嘗試向保留 URI 或檔案延伸模組註冊您的應用程式。請參閱保留的 URI 方案名稱和文件類型，以了解無法為 UWP 應用程式註冊的 Uri 方案的字母順序列表，因為它們是保留的或禁止的。

步驟 1：指定封裝指令清單中的延伸模組點

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

在方案總管中，按兩下「package.appxmanifest」以打開清單設計器。選擇聲明索引標籤，然後在可用聲明下拉清單中選擇協定，然後按一下新增。

以下是您可以在協議清單設計器中填寫的每個欄位的簡要說明 (關於詳細信息，請參閱 AppX 套件清單)：

欄位	描述
標誌	指定用於標識控制面板上的設定預設程式中的 URI 方案名稱的標誌。如果未指定標誌，則使用應用程式的小標誌。
顯示名稱	指定顯示名稱以識別控制面板上的設定預設程式中的 URI 方案名稱。
名稱	選擇 URI 設定的名稱。
	注意名稱必須全部以小寫字母為單位。
	保留和禁止的檔案類型：請參閱保留的 URI 方案名稱和檔案類型，以取得按字母順序排列的 Uri 方案列表，您無法為 UWP 應用程式註冊這些方案，因為它們已保留或禁止。
可執行檔	指定協定的預設啟動可執行檔。如果未指定，則會使用應用程式的可執行檔。如果指定，則字串長度必須介於 1 到 256 個字元之間，必須以「.exe」結尾，且不能包含以下字元：>、<、、:、「、\|、? 或。如果指定，也會使用入口點。如果未指定入口點*，則使用為應用程式定義的入口點。
進入點	指定處理通訊協定延伸的工作。這通常是 Windows 執行時類型的完全命名空間限定名稱。如果未指定，則會使用應用程式的進入點。
開始頁面	處理擴充點的網頁。
資源群組	您可以使用該標籤將延伸模組啟動分組在一起以進行資源管理。
所需的檢視 (僅限 Windows)	指定所需檢視欄位以指示應用程式視窗在針對 URI 方案名稱啟動時所需的空間量。所需檢視的可能值為 Default、UseLess、UseHalf、UseMore 或 UseMinimum。注意Windows 在決定目標應用程式的最終視窗大小時會考慮多種不同因素，例如來源應用程式的首選項、螢幕上的應用程式數量、螢幕方向等。設定所需檢視並不保證目標應用程式的特定視窗化行為。行動裝置系列：行動裝置系列不支援所需的檢視。

輸入 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：處理啟動的事件

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

Protected Overrides Sub OnActivated(ByVal args As Windows.ApplicationModel.Activation.IActivatedEventArgs)
   If args.Kind = ActivationKind.Protocol Then
      ProtocolActivatedEventArgs eventArgs = args As ProtocolActivatedEventArgs
      
      ' TODO: Handle URI activation
      ' The received URI is eventArgs.Uri.AbsoluteUri
 End If
End Sub

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 配置的標準。

注意

透過通訊協定合約啟動時，請確保後退按鈕將使用者帶回啟動應用程式的螢幕，而不是應用程式之前的內容。

我們建議應用為每個開啟新 Uri 目標的啟動事件建立一個新的 XAML Frame。這樣，新 XAML Frame 的導航後退堆疊將不會包含應用程式暫停時在目前視窗上可能具有的任何先前內容。

如果您決定希望應用程式使用單一 XAML Frame 來啟動和協定協定，請在導航至新頁面之前清除 Frame 導覽記錄上的頁面。透過通訊協定合約啟動時，請考慮將 UI 納入您的應用程式，讓使用者回到應用程式頂端。

共用方式為

處理 URI 啟用

步驟 1：指定封裝指令清單中的延伸模組點

步驟 2：新增適當的圖示

步驟 3：處理啟動的事件

備註

完整的範例應用程式

概念

工作

指導方針

參考

意見反應

其他資源

共用方式為

處理 URI 啟用

步驟 1：指定封裝指令清單中的延伸模組點

步驟 2：新增適當的圖示

步驟 3：處理啟動的事件

備註

相關主題

完整的範例應用程式

概念

工作

指導方針

參考

意見反應

其他資源