使用应用 URI 处理程序启用“网站的应用”功能

项目
07/04/2024

网站应用将你的应用与网站相关联，以便当某人打开指向您的网站的链接时，将启动你的应用，而不是打开浏览器。如果未安装应用，网站会像往常一样在浏览器中打开。用户可以信任此体验，因为只有经过验证的内容所有者才能注册链接。用户将能够转到“设置”>“应用”>“网站的应用”检查其所有 Web 到应用链接。

若要启用 Web 到应用链接，需要：

标识应用将在清单文件中处理的 URI
一个 JSON 文件，用于定义应用与网站之间的关联。应用包系列名称与应用清单声明位于同一主机根目录中。
处理应用中的激活。

注意

从 Windows 10 创意者更新开始，Microsoft Edge 旧版中单击的支持链接将启动相应的应用。在其他浏览器中单击的受支持链接（例如，Microsoft Edge Chromium、Internet Explorer 等）将让你了解浏览体验。

注册以处理应用清单中的 http 和 https 链接

你的应用需要标识它将处理的网站 URI。为此，请将 Windows.appUriHandler 扩展注册添加到应用的清单文件 Package.appxmanifest。

例如，如果网站的地址为“msn.com”，则会在应用的清单中输入以下条目：

<Applications>
  <Application ... >
      ...
      <Extensions>
         <uap3:Extension Category="windows.appUriHandler">
          <uap3:AppUriHandler>
            <uap3:Host Name="msn.com" />
          </uap3:AppUriHandler>
        </uap3:Extension>
      </Extensions>
  </Application>
</Applications>

上述声明注册应用以处理来自指定主机的链接。如果网站有多个地址（例如：m.example.com、www.example.com 和 example.com），请在每个地址内<uap3:AppUriHandler>添加一个单独的<uap3:Host Name=... />条目。

将应用和网站与 JSON 文件相关联

若要确保只有应用可以打开网站上的内容，请将应用的包系列名称包含在位于 Web 服务器根目录的 JSON 文件或域的已知目录中。这表示您的网站同意列出的应用打开网站上的内容。可以在应用清单设计器的“包”部分找到包系列名称。

重要

JSON 文件不应具有.json文件后缀。

创建名为 windows-app-web-link 的 JSON 文件（不含.json文件扩展名），并提供应用的程序包系列名称。例如：

[{
  "packageFamilyName" : "Your app's package family name, e.g MyApp_9jmtgj1pbbz6e",
  "paths" : [ "*" ],
  "excludePaths" : [ "/news/*", "/blog/*" ]
 }]

Windows 将与网站建立 https 连接，并将在 Web 服务器上查找相应的 JSON 文件。

通配符

上面的 JSON 文件示例演示了通配符的使用。通配符允许你支持多种链接，代码行更少。 Web 到应用链接支持 JSON 文件中的两种类型的通配符：

通配符	描述
*	表示任何子字符串
?	表示单个字符

例如，给定上述示例中的 "excludePaths" : [ "/news/*", "/blog/*" ]，你的应用将支持以你的网站地址（例如 msn.com）开头的所有路径，除了/news/ 和 /blog/ 下的路径。将支持 msn.com/weather.html，但不支持 msn.com/news/topnews.html。

多个应用

如果有两个要链接到网站的应用，请在 windows-app-web-link JSON 文件中列出两个应用程序包系列名称。支持这两个应用。如果两者都已安装，则会向用户显示一个选择，这是默认链接。如果他们希望在以后更改默认链接，可以在“设置”>“应用网站”中更改它。开发人员还可以随时更改 JSON 文件，并最早在更新后的 8 天内查看更改。

[{
  "packageFamilyName": "Your apps's package family name, e.g MyApp_9jmtgj1pbbz6e",
  "paths": [ "*" ],
  "excludePaths" : [ "/news/*", "/blog/*" ]
 },
 {
  "packageFamilyName": "Your second app's package family name, for example, MyApp2_8jmtgj2pbbz6e",
  "paths": [ "/example/*", "/links/*" ]
 }]

若要为用户提供最佳体验，请使用排除路径来确保仅联机内容已从 JSON 文件中支持的路径中排除。

首先检查排除路径，如果存在匹配项，则会使用浏览器而不是指定的应用打开相应的页面。在上述示例中，“/news/*”包括该路径下的任何页面，而“/news*”（没有正斜杠结尾“news”）包括“news*”下的任何路径，如“newslocal/”、“newsinternational/”等。

处理激活链接以链接到内容

导航到应用的 Visual Studio 解决方案和 OnActivated（）中添加链接内容的处理App.xaml.cs。在以下示例中，在应用中打开的页面取决于 URI 路径：

protected override void OnActivated(IActivatedEventArgs e)
{
    Frame rootFrame = Window.Current.Content as Frame;
    if (rootFrame == null)
    {
        ...
    }

    // Check ActivationKind, Parse URI, and Navigate user to content
    Type deepLinkPageType = typeof(MainPage);
    if (e.Kind == ActivationKind.Protocol)
    {
        var protocolArgs = (ProtocolActivatedEventArgs)e;        
        switch (protocolArgs.Uri.AbsolutePath)
        {
            case "/":
                break;
            case "/index.html":
                break;
            case "/sports.html":
                deepLinkPageType = typeof(SportsPage);
                break;
            case "/technology.html":
                deepLinkPageType = typeof(TechnologyPage);
                break;
            case "/business.html":
                deepLinkPageType = typeof(BusinessPage);
                break;
            case "/science.html":
                deepLinkPageType = typeof(SciencePage);
                break;
        }
    }

    if (rootFrame.Content == null)
    {
        // Default navigation
        rootFrame.Navigate(deepLinkPageType, e);
    }

    // Ensure the current window is active
    Window.Current.Activate();
}

请务必 将最终 if (rootFrame.Content == null) 逻辑替换为 rootFrame.Navigate(deepLinkPageType, e); 上述示例所示。

测试它：本地验证工具

可以通过运行可在以下项中获取的应用主机注册验证程序工具来测试应用和网站的配置：

%windir%\system32\AppHostRegistrationVerifier.exe

使用以下参数运行此工具来测试应用和网站的配置：

AppHostRegistrationVerifier.exe主机名 packagefamilyname filepath

主机名：你的网站（例如，microsoft.com）
程序包系列名称（PFN）：应用的 PFN
文件路径：用于本地验证的 JSON 文件（例如 C:\SomeFolder\windows-app-web-link）

如果该工具未返回任何内容，则上传后，验证将处理该文件。如果存在错误代码，则不起作用。

可以在本地验证过程中启用以下注册表项来强制旁加载应用的路径匹配：

HKCU\Software\Classes\LocalSettings\Software\Microsoft\Windows\CurrentVersion\ AppModel\SystemAppData\YourApp\AppUriHandlers

键名：ForceValidation。值：1

测试它：Web 验证

关闭应用程序以验证单击链接时应用是否已激活。然后，复制网站中某个受支持的路径的地址。例如，如果你的网站地址为“msn.com”，并且支持路径之一为“path1”，你将使用 http://msn.com/path1

验证应用是否已关闭。按 Windows 键 + R 打开“运行”对话框，并在窗口中粘贴该链接。应用应启动而不是 Web 浏览器。

此外，还可以使用 LaunchUriAsync API 从另一个应用启动它来测试应用。也可以使用此 API 在手机上进行测试。

若要遵循协议激活逻辑，在 OnActivated 事件处理程序中设置断点。

AppUriHandlers 提示：

请确保仅指定应用可以处理的链接。
列出你将支持的所有主机。请注意，www.example.com 和 example.com 是不同的主机。
用户可以选择他们喜欢在“设置”中处理网站的应用。
JSON 文件必须上传到 https 服务器。
如果需要更改要支持的路径，可以在不重新发布应用的情况下重新发布 JSON 文件。用户将在 1-8 天内看到更改。
使用 AppUriHandlers 的所有旁加载应用都将在安装时验证主机的链接。无需上传 JSON 文件来测试该功能。
每当应用是使用 LaunchUriAsync 启动的 UWP 应用或使用 ShellExecuteEx 启动的 Windows 桌面应用时，此功能都有效。如果 URL 对应于已注册的应用 URI 处理程序，则会启动应用，而不是浏览器。

另请参阅

Web 到应用示例项目 windows.protocol 注册处理 URI 激活关联启动示例演示如何使用 LaunchUriAsync（） API。

通过