处理 URI 激活

重要的 API

• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
• Windows.UI.Xaml.Application.OnActivated

了解如何将应用注册为统一资源标识符 (URI) 方案名称的默认处理程序。 Windows 桌面应用和 通用 Windows 平台 （UWP） 应用都可以注册为 URI 方案名称的默认处理程序。 如果用户选择你的应用作为 URI 方案名称的默认处理程序，则每次启动该类型的 URI 时，都会激活你的应用。

如果希望处理该类型的 URI 方案的所有 URI 启动，建议仅注册 URI 方案名称。 如果选择注册 URI 方案名称，则必须为最终用户提供为该 URI 方案激活应用时预期的功能。 例如，注册 mailto：URI 方案名称的应用应打开给新的电子邮件，以便用户可以撰写新的电子邮件。 有关 URI 关联的详细信息，请参阅 文件类型和 URI 指南和清单。

这些步骤演示如何注册自定义 URI 方案名称， alsdk://以及如何在用户启动 alsdk:// URI 时激活应用。

注意

在 UWP 应用中，保留某些 URI 和文件扩展以供内置应用和操作系统使用。 将忽略尝试使用保留 URI 或文件扩展名注册应用。 有关无法注册 UWP 应用的 URI 方案的字母顺序列表，请参阅 保留 URI 方案名称和文件类型 ，因为它们是保留的还是禁止的。

步骤 1：在包清单中指定扩展点

应用仅接收程序包清单中列出的 URI 方案名称的激活事件。 下面介绍如何指示应用处理 alsdk URI 方案名称。

1. 在解决方案资源管理器中，双击 package.appxmanifest 以打开清单设计器。 选择“声明”选项卡，然后在“可用声明”下拉列表中选择“协议”，然后单击“添加”。

   下面是可以填写协议清单设计器的每个字段的简要说明（有关详细信息，请参阅 AppX 程序包清单 ）：

字段	说明
Logo	指定用于在控制面板的“设置默认程序”中标识 URI 方案名称的徽标。 如果未指定徽标，则使用应用的小型徽标。
显示名称	指定显示名称以标识控制面板的“设置默认程序”中的 URI 方案名称。
Name	选择 URI 方案的名称。
	请注意 ，名称必须采用所有小写字母。
	保留和禁止文件类型 请参阅 保留 URI 方案名称和文件类型 ，了解无法注册 UWP 应用的 URI 方案的字母列表，因为它们是保留或禁止的。
Executable	指定协议的默认启动可执行文件。 如果未指定，则使用应用的可执行文件。 如果已指定，字符串长度必须是 1 到 256 个字符、必须以“.exe”结尾，并且不能包含以下字符：>、<、:、"、|、? 或 *。 如果指定， 则还会使用入口点 。 如果未指定入口点，则使用为应用定义的入口点。
入口点	指定处理协议扩展的任务。 这通常是Windows 运行时类型的完全命名空间限定名称。 如果未指定，则使用应用的入口点。
起始页	处理扩展点的网页。
资源组	一个标记，可用于将扩展激活组合在一起，以便进行资源管理。
所需视图 （仅限 Windows）	指定 Desired View 字段，以指示应用窗口启动 URI 方案名称时所需的空间量。 所需视图的可能值为 Default、UseLess、UseHalf、UseMore 或 UseMinimum。 请注意 ，Windows 在确定目标应用的最终窗口大小时会考虑多种不同的因素，例如源应用的首选项、屏幕上的应用数、屏幕方向等。 设置 Desired View 不能保证目标应用的特定窗口化行为。 移动设备系列：移动设备系列不支持所需视图 。

2. 输入 images\Icon.png 为 徽标。

3. 输入 SDK Sample URI Scheme 为 显示名称

4. 输入 alsdk 作为“名称”。

5. 按 Ctrl+S 将更改保存到 package.appxmanifest。

   这会向包清单添加类似于此扩展 元素的扩展 元素。 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 框架 。 这样，新 XAML 框架 的导航后台堆栈将不会包含应用在暂停时当前窗口中可能具有的任何先前内容。 决定使用单个 XAML 框架启动和文件协定的应用应在导航到新页面之前清除框架导航日记中的页面。

通过协议激活启动时，应用应考虑包括允许用户返回到应用顶部页面的 UI。

注解

任何应用或网站都可以使用 URI 方案名称，包括恶意名称。 因此，在 URI 中获取的任何数据都可能来自不受信任的源。 建议不要根据 URI 中收到的参数执行永久操作。 例如，URI 参数可用于将应用启动到用户帐户页，但我们建议你永远不要使用它们直接修改用户帐户。

注意

如果为应用创建新的 URI 方案名称，请确保遵循 RFC 4395 中的指南。 这可确保名称符合 URI 方案的标准。

注意

通过协议合约启动后，请确保“后退”按钮可使用户返回到已启动应用的屏幕，而不是应用的早期内容。

我们建议应用为每个打开新 Uri 目标的激活事件创建新的 XAML 框架 。 这样，新 XAML 框架 的导航后台堆栈将不会包含应用在暂停时当前窗口中可能具有的任何先前内容。

如果你决定希望应用使用单个 XAML 框架进行启动和协议协定，请在导航到新页面之前清除框架导航日记中的页面。 通过协议协定启动时，请考虑在应用中包括 UI，使用户能够返回到应用顶部。

相关主题

完整示例应用

• 关联启动示例

概念

• 默认程序
• 文件类型和 URI 关联模型

任务

• 启动 URI 的默认应用
• 处理文件激活

准则

• 文件类型和 URI 指南

参考

• AppX 包清单
• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
• Windows.UI.Xaml.Application.OnActivated