Поделиться через

Присвоение идентичности пакету путем упаковки с использованием внешнего места вручную.

Для получения информации о мотивациях добавления идентификатора пакета, а также различиях между созданием пакетов в Visual Studio и их созданием вручную, см. раздел "Обзор".

В этом разделе описывается, как создать и зарегистрировать пакет удостоверений вручную. Сведения о создании пакета идентификатора в Visual Studio см. в статье Присвоение идентификатора пакету путем упаковки с внешним расположением в Visual Studio.

Ниже приведены шаги (подробно описанные в этом разделе) для создания и регистрации пакета удостоверений вручную:

  1. Создайте манифест пакета для пакета идентификации
  2. Создание и подписание пакета удостоверений
  3. Добавьте метаданные удостоверения в манифесты настольных приложений
  4. Зарегистрируйте пакет удостоверений в установщике
  5. Необязательные шаги

Создайте манифест для пакета идентификации

Первым шагом к созданию пакета идентификации является создание манифеста пакета на основе приведенного ниже шаблона. Это манифест 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 Заполните атрибуты элемента сведениями о приложении
    • Name — требуемое имя пакета удостоверений
    • Publisher должен соответствовать Subject сертификату, используемому для подписывания приложения.
    • Version — это требуемая версия пакета удостоверений. Распространенная практика заключается в выравнивании версии пакета удостоверений с версией приложения. Вы не сможете зарегистрировать версию пакета удостоверений в системе, если эта версия пакета уже зарегистрирована. Сначала необходимо отменить регистрацию существующего пакета, чтобы переустановить пакет с той же версией.
    • ProcessorArchitecture должен быть neutral как указано, чтобы пакет идентификатора работал на всех архитектурах (x86, x64 и ARM64)
  • Заполните элементы 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, как показано
    • Примечание. Эта AllowExternalContent функция была представлена в сборке Windows 10.0.19041.0. Если ваше приложение работает на более ранних версиях ОС, чем указано, необходимо выполнить проверку версии ОС в установщике и не регистрировать пакет идентификации на версиях ОС, которые старше 10.0.19041.0. См. раздел "Регистрация пакета удостоверений" в установщике.
  • Убедитесь, что возможности runFullTrust и unvirtualizedResources объявлены так, как показано для совместимости с Win32.
  • Добавьте элемент Application, как показано, для каждого исполняемого файла, связанного с вашим приложением.
    • Убедитесь, что TrustLevel является mediumIL, а RuntimeBehavior является win32App, как показано для совместимости с Win32.
  • VisualElements Дочерний элемент является обязательным, но AppListEntry="none" атрибут гарантирует, что пакет удостоверений не отображается среди установленных приложений.
    • DisplayName Обновите и Description атрибуты с соответствующими сведениями и оставьте другие атрибуты, как показано (пути к указанному изображению не нужно разрешать).
    • См. Локализация и визуальные ресурсы для сценариев, в которых здесь может потребоваться локализация и изображения.

Пакет идентификации, созданный из этого манифеста, будет связан с директорией установки вашего приложения при регистрации пакета на следующем шаге.

Создание и подписание пакета идентификации

После создания манифеста пакета удостоверений создайте пакет удостоверений с помощью средстваMakeAppx.exe в пакете SDK для Windows.

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

Примечание. Флаг /nv требуется для обхода проверки пути к файлам, на которые ссылается ссылка, в манифесте.

Для установки на компьютеры конечных пользователей пакет удостоверений должен быть подписан сертификатом, которому доверяют на целевом компьютере. Вы можете создать самозаверяющий сертификат для целей разработки и подписать пакет удостоверений с помощью SignTool, который доступен в пакете SDK для Windows, но рабочий сертификат из ИТ-отдела или службы, например доверенный подписывание 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 элемента в манифесте пакета удостоверений.

Регистрация идентификационного пакета в установщике

Последним шагом для связывания удостоверения с приложением является регистрация пакета удостоверений в установщике и связывание его с каталогом установки приложения.

PowerShell

Выполнение powershell.exe с правильными параметрами — самый простой способ регистрации пакета. Рекомендации отличаются для установок на пользователя и на всю систему.

Per-User (PowerShell)

Чтобы зарегистрировать пакет идентификации во время персональной установки:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Path <PackagePath> -ExternalLocation <ExternalLocation>"
  • Задайте <PackagePath> абсолютный путь к подписанному пакету удостоверений, создаваемому на предыдущем шаге (с именем файла).
  • Задайте <ExternalLocation> абсолютный путь к каталогу установки приложения (без имен исполняемых файлов).

Чтобы отменить регистрацию пакета идентификаций во время удаления пользователя:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Get-AppxPackage <PackageName> | Remove-AppxPackage"
  • Задайте <PackageName> имя пакета, определенное в манифесте пакета удостоверений (атрибут Name элемента Identity )

Per-Machine (PowerShell)

Чтобы зарегистрировать пакет идентификации во время установки для всего компьютера:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Stage <PackagePath> -ExternalLocation <ExternalLocation>; Add-AppxProvisionedPackage -Online -PackagePath <PackagePath>"
  • Задайте <PackagePath> абсолютный путь к подписанному пакету удостоверений, создаваемому на предыдущем шаге (с именем файла).
  • Задайте <ExternalLocation> абсолютный путь к каталогу установки приложения (без имен исполняемых файлов).

Чтобы отменить регистрацию пакета удостоверений во время удаления на уровне компьютера:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "$packages = Get-AppxPackage <PackageName>; foreach ($package in $packages) { Remove-AppxProvisionedPackage -PackageName $package.PackageFullName -Online }; foreach ($package in $packages) { Remove-AppxPackage -Package $package.PackageFullName -AllUsers }
  • Задайте <PackageName> имя пакета, определенное в манифесте пакета удостоверений (атрибут Name элемента Identity )

API-интерфейсы PackageManager

Если вы предпочитаете вызывать API ОС для регистрации и отмены регистрации пакета удостоверений, API PackageManager предоставляет эквивалентные функциональные возможности PowerShell. Рекомендации отличаются для установок на пользователя и на всю систему.

Ниже приведены фрагменты кода, демонстрирующие API. Готовый к работе код в C# и C++см. в разделе "Примеры приложений".

Per-User (PackageManager)

Приведенный ниже код демонстрирует регистрацию пакета удостоверений с помощью метода AddPackageByUriAsync и отмены регистрации пакета удостоверений с помощью метода RemovePackageAsync .

using Windows.Management.Deployment;

...

// Register the identity package during install

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);

...

// Unregister the identity package during uninstall

var packageManager = new PackageManager();
var packages = packageManager.FindPackagesForUserWithPackageTypes("", "<IdentityPackageFamilyName>", PackageType.Main);
foreach (var package in packages)
{
  await packageManager.RemovePackageAsync(package.Id.FamilyName);
}

Обратите внимание на следующие важные сведения об этом коде:

  • Задайте externalLocation абсолютный путь к каталогу установки приложения (без имен исполняемых файлов)
  • Задайте packagePath абсолютный путь к подписанному пакету удостоверений, создаваемому на предыдущем шаге (с именем файла)
  • <IdentityPackageFamilyName> можно найти, выполнив команду PowerShell Get-AppxPackage <IdentityPackageName> на системе, где зарегистрирован пакет идентификации. Свойство PackageFamilyName содержит значение, используемое здесь.

Per-Machine (PackageManager)

Приведенный ниже код демонстрирует регистрацию пакета удостоверений с помощью методов StagePackageByUriAsync и ProvisionPackageForAllUsersAsync и отмены регистрации пакета удостоверений с помощью методов DeprovisionPackageForAllUsersAsync и RemovePackageAsync .

// Register the identity package during install

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

var packageManager = new PackageManager();

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

await packageManager.StagePackageByUriAsync(packageUri, options);
await packageManager.ProvisionPackageForAllUsersAsync(packageFamilyName);

...

// Unregister the identity package during uninstall

var packageManager = new PackageManager();

var packages = packageManager.FindPackagesForUserWithPackageTypes("", "<IdentityPackageFamilyName>", PackageType.Main);
foreach (var package in packages)
{
  await packageManager.DeprovisionPackageForAllUsersAsync(package.Id.FamilyName);
  await packageManager.RemovePackageAsync(package.Id.FamilyName, RemovalOptions.RemoveForAllUsers);
}

Обратите внимание на следующие важные сведения об этом коде:

  • Задайте externalLocation абсолютный путь к каталогу установки приложения (без имен исполняемых файлов)
  • Задайте packagePath абсолютный путь к подписанному пакету удостоверений, создаваемому на предыдущем шаге (с именем файла)
  • Его <IdentityPackageFamilyName> можно найти, выполнив команду в PowerShell в системе, где зарегистрирован пакет идентификации. Свойство PackageFamilyName содержит значение, используемое здесь.

Примеры приложений

Примеры PackageWithExternalLocation см. в полнофункциональных приложениях C# и C++, демонстрирующих регистрацию и отмену регистрации пакета удостоверений.

Другие необязательные шаги

Локализация и визуальные ресурсы

Некоторые функции, которые понимают идентификатор пакета, могут привести к строкам и изображениям, отображаемым в ОС Windows, из манифеста идентификатора пакета. Рассмотрим пример.

  • Приложение, использующее API камеры, микрофона или расположения, будет иметь выделенный элемент управления в параметрах конфиденциальности Windows, а также запрос на согласие с брокером, который пользователи могут использовать для предоставления или запрета доступа к этим конфиденциальным ресурсам.
  • Приложение, которое регистрирует цель для общего доступа, будет отображаться в диалоговом окне общего доступа.

Сведения о локализации строк в манифесте пакета удостоверений см. в разделе "Локализация манифеста".

При указании путей к изображениям в атрибутах VisualElements в манифесте пакета удостоверений, указанные пути должны быть относительными путями в каталоге установки вашего приложения, которые разрешаются к изображениям типа .png, .jpgили .jpeg. Имена атрибутов указывают ожидаемые размеры изображений (150x150 и 40x40).