パッケージ ID の追加の動機と、Visual Studio での ID パッケージのビルドと手動でのビルドの違いについては、「 概要」を参照してください。
このトピックでは、ID パッケージを手動でビルドして登録する方法について説明します。 Visual Studio で ID パッケージをビルドする方法については、「Visual Studio の 外部の場所でパッケージ化してパッケージ ID を付与する」を参照してください。
ID パッケージを手動でビルドして登録する手順 (このトピックでは詳しく説明します) を次に示します。
- ID パッケージのパッケージ マニフェストを作成する
- ID パッケージをビルドして署名する
- デスクトップ アプリケーション マニフェストに ID メタデータを追加する
- インストーラーに ID パッケージを登録する
- 省略可能な手順
ID パッケージのパッケージ マニフェストを作成する
ID パッケージを作成する最初の手順は、次のテンプレートに基づいてパッケージ マニフェストを作成することです。 これは MSIX マニフェストですが、ID にのみ使用され、アプリのランタイム動作は変更されません。
<?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
は、ID パッケージの目的の名前ですPublisher
は、アプリケーションの署名に使用する証明書のSubject
と一致する必要がありますVersion
は、ID パッケージの目的のバージョンです。 一般的な方法は、ID パッケージのバージョンをアプリケーションのバージョンに合わせることです。 そのバージョンのパッケージが既に登録されている場合、システムに ID パッケージのバージョンを登録することはできません。 同じバージョンのパッケージを再インストールするには、まず既存のパッケージの登録を解除する必要があります。ProcessorArchitecture
ID パッケージがすべてのアーキテクチャ (x86、x64、ARM64) で動作するように、次のようにneutral
する必要があります
DisplayName
要素とPublisherDisplayName
要素にアプリケーションの詳細を入力します- 単純な ID を超えてマニフェストに機能を追加しない限り、これらの値はどこにも表示されません
- アプリケーションのインストールディレクトリ内で .png、.jpg、または .jpeg イメージに解決されるように、
Logo
要素を相対パスに更新します。 AllowExternalContent
要素がtrue
に設定されていることを確認します。これにより、既存のインストーラーを再利用できます- 次のように
TargetDeviceFamily
MinVersion
とMaxVersionTested
を設定します。- Windows 10 および Windows 11 OS のバージョン全体で最大限のリーチと均一性を得るために、
MinVersion
を10.0.19041.0
に設定します - ID パッケージを Windows 11 バージョン 24H2 以降に制限するには、
MinVersion
を10.0.26100.0
に設定します MaxVersionTested
を次のように10.0.26100.0
に設定します- 注: ここで使用する
AllowExternalContent
機能は、Windows ビルド 10.0.19041.0 で導入されました。 アプリケーションがそれ以上のダウンレベルで実行される場合は、インストーラーで OS バージョンのチェックを実行し、10.0.19041.0 より前のバージョンの OS に ID パッケージを登録しないでください。 「インストーラーに ID パッケージを登録する」を参照してください。
- Windows 10 および Windows 11 OS のバージョン全体で最大限のリーチと均一性を得るために、
- Win32 の互換性のために、
runFullTrust
とunvirtualizedResources
の機能が示されているように宣言されていることを確認します - アプリケーションに関連付けられている実行可能ファイルごとに示すように、
Application
要素を追加しますTrustLevel
がmediumIL
され、Win32 の互換性のために示されているようにRuntimeBehavior
がwin32App
されていることを確認します
VisualElements
子要素が必要ですが、AppListEntry="none"
属性を使用すると、インストールされているアプリ間で ID パッケージが表示されないようにしますDisplayName
属性とDescription
属性を関連する詳細で更新し、他の属性はそのままにしておきます(参照された画像パスは解決する必要がありません)- ローカライズとイメージが必要になる可能性があるシナリオについては、「 ローカリゼーションとビジュアルアセット 」を参照してください。
このマニフェストから作成された ID パッケージは、後の手順でパッケージを登録すると、アプリケーションのインストール ディレクトリに接続されます。
ID パッケージをビルドして署名する
ID パッケージ マニフェストを作成したら、Windows SDK の MakeAppx.exe ツール を使用して ID パッケージをビルドします。
MakeAppx.exe pack /o /d <path to directory that contains manifest> /nv /p <output path>\MyPackage.msix
注: マニフェスト内の参照ファイル パスの検証をバイパスするには、 /nv
フラグが必要です。
エンド ユーザー コンピューターにインストールするには、ターゲット コンピューターで信頼されている証明書を使用して ID パッケージに署名する必要があります。 開発目的で新しい自己署名証明書を作成し、Windows SDK で入手できる SignTool を使用して ID パッケージに署名できますが、エンド ユーザー コンピューターにパッケージを登録するには、IT 部門または Azure Trusted Signing などのサービスの運用証明書が必要になります。
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 パイプライン内で ID パッケージをビルドして署名する方法については、 例として MSIX と CI/CD パイプラインの概要 を参照してください。
デスクトップ アプリケーション マニフェストに ID メタデータを追加する
ID パッケージをアプリケーション実行可能ファイルに接続するには、 アプリケーション マニフェスト (サイド バイ サイド マニフェストまたは Fusion マニフェスト) を、ID パッケージ マニフェストのメタデータと一致するメタデータに含めます。
Visual Studio では、アプリケーション マニフェスト を実行可能プロジェクトに追加するには、[ プロジェクト ] コンテキスト メニューを開き、[ 追加>新しい項目>アプリケーション マニフェスト ファイル] を選択します。
バイナリを ID パッケージのメタデータに接続するために必要な 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
要素の属性は、ID パッケージ マニフェストの次の値と一致する必要があります。
packageName
属性とpublisher
属性は、ID パッケージ マニフェストのName
要素のPublisher
属性とIdentity
属性にそれぞれ一致する必要がありますapplicationId
属性は、ID パッケージ マニフェスト内の対応するId
要素のApplication
属性と一致する必要があります
インストーラーに ID パッケージを登録する
ID をアプリケーションに関連付ける最後の手順は、インストーラーに ID パッケージを登録し、それをアプリケーションのインストール ディレクトリに関連付けます。
PowerShell
適切なパラメーターを使用して powershell.exe を実行することは、パッケージを登録する最も簡単な方法です。 このガイダンスは、ユーザーごとのインストールとマシン全体のインストールで異なります。
ユーザーごと (PowerShell)
ユーザーごとのインストール中に ID パッケージを登録するには:
powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Path <PackagePath> -ExternalLocation <ExternalLocation>"
<PackagePath>
を、前の手順で生成した署名付き ID パッケージの絶対パス (ファイル名) に設定します。<ExternalLocation>
アプリケーションのインストール ディレクトリの絶対パスに設定します (実行可能ファイル名は指定しません)。
ユーザーごとのアンインストール中に ID パッケージの登録を解除するには:
powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Get-AppxPackage <PackageName> | Remove-AppxPackage"
<PackageName>
を、ID パッケージ マニフェストで定義したパッケージ名 (Identity 要素の Name 属性) に設定します。
マシンごと (PowerShell)
マシン全体のインストール中に ID パッケージを登録するには:
powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Stage <PackagePath> -ExternalLocation <ExternalLocation>; Add-AppxProvisionedPackage -Online -PackagePath <PackagePath>"
<PackagePath>
を、前の手順で生成した署名付き ID パッケージの絶対パス (ファイル名) に設定します。<ExternalLocation>
アプリケーションのインストール ディレクトリの絶対パスに設定します (実行可能ファイル名は指定しません)。
マシン全体のアンインストール中に ID パッケージの登録を解除するには:
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>
を、ID パッケージ マニフェストで定義したパッケージ名 (Identity 要素の Name 属性) に設定します。
PackageManager API
OS API を呼び出して ID パッケージを登録および登録解除する場合、PackageManager API は PowerShell と同等の機能を提供します。 このガイダンスは、ユーザーごとのインストールとマシン全体のインストールで異なります。
API を示すスニペットを次に示します。 C# と C++ の運用対応コードについては、 サンプル アプリに関するページを参照してください。
ユーザーごと (PackageManager)
次のコードリストは、 AddPackageByUriAsync メソッドを使用して ID パッケージを登録し、 RemovePackageAsync メソッドを使用して ID パッケージの登録を解除する方法を示しています。
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
を、前の手順で生成した署名付き ID パッケージの絶対パス (ファイル名) に設定します<IdentityPackageFamilyName>
は、ID パッケージが登録されているシステムでGet-AppxPackage <IdentityPackageName>
PowerShell コマンドを実行することで確認できます。PackageFamilyName
プロパティには、ここで使用する値が含まれています。
マシンごと (PackageManager)
次のコードリストは、 StagePackageByUriAsync メソッドと ProvisionPackageForAllUsersAsync メソッドを使用して ID パッケージを登録し、 DeprovisionPackageForAllUsersAsync メソッドと RemovePackageAsync メソッドを使用して ID パッケージの登録を解除する方法を示しています。
// 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
を、前の手順で生成した署名付き ID パッケージの絶対パス (ファイル名) に設定します<IdentityPackageFamilyName>
は、ID パッケージが登録されているシステムでGet-AppxPackage <IdentityPackageName>
PowerShell コマンドを実行することで確認できます。PackageFamilyName
プロパティには、ここで使用する値が含まれています。
サンプル アプリ
ID パッケージを登録および登録解除する方法を示す完全に機能する C# および C++ アプリについては、 PackageWithExternalLocation のサンプルを参照してください。
省略可能な手順
ローカライズとビジュアルアセット
パッケージ ID を理解する一部の機能では、ID パッケージ マニフェストの文字列とイメージが Windows OS に表示される可能性があります。 例えば次が挙げられます。
- カメラ、マイク、または場所の API を使用するアプリケーションでは、Windows プライバシー設定で専用の制御トグルと、ユーザーがこれらの機密性の高いリソースへのアクセスを許可または拒否するために使用できる仲介型の同意プロンプトが表示されます。
- 共有ターゲットを登録するアプリケーションが共有ダイアログに表示されます。
ID パッケージ マニフェスト内の文字列をローカライズするには、「マニフェストを ローカライズする」を参照してください。
ID パッケージ マニフェストの VisualElements
属性でイメージへのパスを指定する場合、指定されたパスは、.png、.jpg、または.jpegイメージに解決されるアプリケーションのインストール ディレクトリ内の相対パスである必要があります。 属性名は、イメージの予想される寸法 (150 x 150 および 40 x 40) を示します。
Windows developer