使用应用 URI 处理程序为网站启用应用

项目
02/22/2025

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

重要

从 Windows 10 创意者更新开始，以及在所有 Windows 11 版本中，在 Microsoft Edge 旧版中单击的支持链接将启动相应的应用。在支持的浏览器（例如 Microsoft Edge Chromium、Firefox、Internet Explorer 等）中，点击支持的链接将保持您的浏览体验。

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

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

注册以处理应用清单中的 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, and 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 解决方案中的 App.xaml.cs，然后在 OnActivated() 中添加对链接内容的处理。在以下示例中，在应用中打开的页面取决于 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 文件路径

主机名：您的网站（例如，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 技术提示

这些提示将帮助你充分利用 AppUriHandlers 功能：

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

网页到应用程序示例工程

windows.protocol 注册

处理 URI 激活

通过