通过手动在外部位置打包的方式授予包身份

项目
2025-05-22

有关添加包标识背后的动机，以及在 Visual Studio 中生成标识包和手动生成标识包之间的差异，请参阅概述。

本主题介绍如何手动生成和注册标识包。有关在 Visual Studio 中创建标识包的信息，请参阅在 Visual Studio 中使用外部位置打包以赋予包标识。

以下是手动生成和注册标识包的步骤（本主题详细介绍）：

为标识包创建包清单
生成并签名标识包
将标识元数据添加到桌面应用程序清单
在安装程序中注册标识包
可选步骤

为标识包创建程序包清单

创建标识包的第一步是基于以下模板创建包清单。这是 MSIX 清单，但仅用于标识，不会更改应用的运行时行为。

<?xml version="1.0" encoding="utf-8"?>
<Package IgnorableNamespaces="uap uap10"
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities">
  <Identity Name="ContosoPhotoStore" Publisher="CN=Contoso" Version="1.0.0.0" ProcessorArchitecture="neutral" />
  <Properties>
    <DisplayName>Contoso PhotoStore</DisplayName>
    <PublisherDisplayName>Contoso</PublisherDisplayName>
    <Logo>Assets\storelogo.png</Logo>
    <uap10:AllowExternalContent>true</uap10:AllowExternalContent>
  </Properties>
  <Resources>
    <Resource Language="en-us" />
  </Resources>
  <Dependencies>
    <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.19041.0" MaxVersionTested="10.0.26100.0" />
  </Dependencies>
  <Capabilities>
    <rescap:Capability Name="runFullTrust" />
    <rescap:Capability Name="unvirtualizedResources"/>
  </Capabilities>
  <Applications>
    <Application Id="ContosoPhotoStore" Executable="ContosoPhotoStore.exe" uap10:TrustLevel="mediumIL" uap10:RuntimeBehavior="win32App"> 
      <uap:VisualElements AppListEntry="none" DisplayName="Contoso PhotoStore" Description="Contoso PhotoStore App" BackgroundColor="transparent" Square150x150Logo="Assets\Square150x150Logo.png" Square44x44Logo="Assets\Square44x44Logo.png" />
    </Application>
  </Applications>
</Package>

请注意以下有关此清单的重要详细信息：

填入应用程序的详细信息到 Identity 元素属性中
- Publisher必须与用于对应用程序进行签名的证书匹配Subject
将应用程序的详细信息输入到 DisplayName 和 PublisherDisplayName 元素中
- 除非在简单标识之外向清单添加其他功能，否则这些值不会显示在任何位置
将 Logo 元素更新为应用程序安装目录中的相对路径，该路径将指向 .png、.jpg或 .jpeg 图像
确保元素 AllowExternalContent 设置为 true 如下所示，以便重用现有安装程序
按如下方式设置 TargetDeviceFamilyMinVersion 和 MaxVersionTested：
- 将MinVersion设置为10.0.19041.0以在 Windows 10 和 Windows 11 操作系统版本中实现最大覆盖范围和统一性。
- 将MinVersion设置为10.0.26100.0以将标识包限制为 Windows 11 版本 24H2 及更高版本
- 将MaxVersionTested设置为10.0.26100.0，如下所示
确保按如下所示来声明 runFullTrust 和 unvirtualizedResources 功能，以便实现 Win32 兼容性
为与应用程序关联的每个可执行文件添加一个 Application 元素，如下所示
- 确保 TrustLevel 是 mediumIL，且 RuntimeBehavior 是 win32App，如 Win32 兼容性所示。
VisualElements 子元素是必需的，但 AppListEntry="none" 属性可确保标识包不会显示在已安装的应用程序中。
- 更新DisplayName和Description属性的相关详细信息，其余属性保持原样（引用的图像路径不需要解析）

在后续步骤中注册包时，从此清单创建的标识包将连接到应用程序的安装目录。

生成并签名标识包

创建标识包清单后，使用 Windows SDK 中的 MakeAppx.exe 工具生成标识包。

MakeAppx.exe pack /o /d <path to directory that contains manifest> /nv /p <output path>\MyPackage.msix

注意：需要 /nv 标志才能绕过清单中引用的文件路径的验证。

若要在最终用户计算机上安装，必须使用目标计算机上受信任的证书对标识包进行签名。可以为开发目的创建新的自签名证书，并使用 Windows SDK 中提供的 SignTool 对标识包进行签名，但 IT 部门或 Azure 受信任的签名等服务的生产证书需要在最终用户计算机上注册该包。

SignTool.exe sign /fd SHA256 /a /f <path to certificate>\MyCertificate.pfx /p <certificate password> <path to package with external ___location>\MyPackage.msix

注意：有关如何使用生产证书在 CI/CD 管道中生成和签名标识包，请参阅 MSIX 和 CI/CD 管道概述，获取示例。

将标识元数据添加到桌面应用程序清单

通过包含应用程序清单（也称为并行清单或融合清单）并将元数据与标识包清单中的元数据匹配，你可以将标识包与应用程序可执行文件连接起来。

在 Visual Studio 中，可以通过打开“项目”上下文菜单并选择“添加新>>”，将应用程序清单添加到可执行项目。

下面是一个应用程序清单示例片段，其中演示了将二进制文件与标识包中的元数据连接所需的 msix 元素。

<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <assemblyIdentity version="0.0.0.0" name="ContosoPhotoStore"/>
  <msix xmlns="urn:schemas-microsoft-com:msix.v1"
          publisher="CN=Contoso"
          packageName="ContosoPhotoStore"
          applicationId="ContosoPhotoStore"
        />
</assembly>

元素的属性 msix 必须与标识包清单中的这些值匹配：

packageName和publisher属性必须分别匹配您标识包清单中的Name元素中的Publisher和Identity属性。
该applicationId属性必须与标识包清单中相应Id元素的Application属性匹配

在安装程序中注册标识包

将标识与应用程序关联的最后一步是在安装程序中注册标识包，并将其与应用程序的安装目录相关联。

以下代码片段演示如何使用 PackageManager.AddPackageByUriAsync 该方法注册标识包。

using Windows.Management.Deployment;

...

var externalUri = new Uri(externalLocation);
var packageUri = new Uri(packagePath);

var packageManager = new PackageManager();

var options = new AddPackageOptions();
options.ExternalLocationUri = externalUri;

await packageManager.AddPackageByUriAsync(packageUri, options);

请注意以下有关此代码的重要详细信息：

将 externalLocation 设置为您的应用程序安装目录的绝对路径（不包括任何可执行文件名称）
将packagePath设置为上一步中生成的标识包的绝对路径（包括文件名）

有关 C# 和 C++ 中的生产就绪代码，请参阅以下示例应用。这些示例还演示如何在卸载时注销标识包。

示例应用

请参阅 PackageWithExternalLocation 示例，了解功能齐全的 C# 和C++应用，这些应用演示如何注册标识包。

可选步骤

本地化

了解包标识的某些功能可能会导致标识包清单中的字符串显示在 Windows OS 中。例如：

使用相机、麦克风或位置 API 的应用程序将在 Windows 隐私设置中具有专用的控制切换，以及用户可用于授予或拒绝对这些敏感资源的访问权限的中转同意提示。
注册共享目标的应用程序将显示在共享对话框中。

若要本地化标识包清单中的字符串，请参阅本地化清单。

通过