外部の場所でパッケージ化してパッケージ ID を付与する

[アーティクル]
10/13/2023

既存のデスクトップアプリがあり、独自のインストーラーがある場合は、パッケージ ID を利用するために変更する必要はほとんどありません。

バックグラウンドタスク、通知、ライブタイル、カスタムコンテキストメニュー拡張機能、共有ターゲットなど、Windows 拡張機能の多くは、実行時にデスクトップアプリにパッケージ ID が指定されている場合にのみ、そのアプリで使用できます。これは、オペレーティングシステム (OS) で対応する API の呼び出し元を識別できる必要があるためです。「パッケージ ID が必要な機能」を参照してください。

パッケージアプリにのみ、実行時にパッケージ ID が含まれます。パッケージアプリ、非パッケージアプリ、および外部の場所でパッケージ化されたアプリの定義については、「展開の概要」を参照してください。

Windows 10 バージョン 2004 以前では、パッケージ ID をアプリに付与する唯一の方法は、署名済みの MSIX パッケージでパッケージ化することです (「コードからの MSIX パッケージの構築」を参照)。この場合、ID はパッケージマニフェストに指定され、ID 登録はマニフェストの情報に基づいて MSIX 展開パイプラインによって処理されます。パッケージマニフェストで参照されるすべてのコンテンツは、MSIX パッケージ内に存在します。
一方、Windows 10 バージョン 2004 以降では、アプリで "外部の場所のパッケージ" をビルドして登録するだけで、アプリにパッケージ ID を付与できます。これにより、パッケージアプリになります。具体的には、"外部の場所でパッケージ化されたアプリ" です。これは、一部のデスクトップアプリでは、すべてのコンテンツが MSIX パッケージ内に存在する準備ができていないためです。そのため、このサポートにより、このようなアプリはパッケージ ID を持つことができ、結果としてパッケージ ID を必要とする Windows 拡張機能を使用できるようになります。背景情報の詳細については、ブログ記事「非パッケージ Win32 アプリの ID、登録、アクティブ化」を参照してください。

外部の場所のパッケージをビルドして登録する (アプリにパッケージ ID を付与する) には、次の手順に従います。

外部の場所のパッケージのパッケージマニフェストを作成する
外部の場所のパッケージをビルドして署名する
デスクトップアプリケーションマニフェストにパッケージ ID メタデータを追加する
実行時に外部の場所のパッケージを登録する

重要な概念

次の機能を使用すると、非パッケージデスクトップアプリでパッケージ ID を取得できます。

外部の場所のパッケージ

"外部の場所のパッケージ" にはパッケージマニフェストが含まれていますが、他のアプリバイナリやコンテンツは含まれていません。外部の場所のパッケージのマニフェストでは、事前に定義された外部の場所で、パッケージ外部のファイルを参照できます。前述のように、このサポートにより、すべてのコンテンツが MSIX パッケージ内に存在する準備ができていないアプリで、パッケージ ID を必要とする Windows 拡張機能を使用できます。

注意

外部の場所のパッケージを使用するデスクトップアプリでは、MSIX パッケージを使用して完全に展開される場合の利点の一部が得られません。これらの利点には、改ざん防止、ロックダウンされた場所へのインストール、展開、実行時、およびアンインストール時の OS による完全な管理などがあります。

外部コンテンツの許可

外部の場所のパッケージをサポートするために、パッケージマニフェストスキーマでは、Properties 要素の下にある省略可能な uap10:AllowExternalContent 要素がサポートされるようになりました。これにより、パッケージマニフェストでは、ディスク上の特定の場所にあるパッケージ外部のコンテンツを参照できます。

たとえば、アプリの実行可能ファイルとその他のコンテンツを C:\Program Files\MyDesktopApp にインストールする、既存の非パッケージデスクトップアプリがある場合は、マニフェスト内に uap10:AllowExternalContent 要素を含む外部の場所のパッケージを作成できます。ご自分のアプリのインストール中、またはアプリの初回起動時に、外部の場所のパッケージをインストールし、アプリで使用する外部の場所として C:\Program Files\MyDesktopApp\ を宣言することができます。

外部の場所のパッケージのパッケージマニフェストを作成する

外部の場所のパッケージをビルドするには、まず、デスクトップアプリのパッケージ ID メタデータとその他の必要な詳細を宣言するパッケージマニフェスト (AppxManifest.xml という名前のファイル) を作成する必要があります。外部の場所のパッケージのパッケージマニフェストを作成する最も簡単な方法は、下の例を用いて、スキーマ参照を使用してアプリ用にカスタマイズすることです。

パッケージマニフェストに次の項目が含まれることを確認してください。

デスクトップアプリの ID 属性を記述する Identity 要素。
Properties 要素の下にある uap10:AllowExternalContent 要素。この要素には値 true を割り当てる必要があります。これにより、パッケージマニフェストでは、ディスク上の特定の場所にあるパッケージ外部のコンテンツを参照できます。後の手順で、インストーラーまたはアプリで実行されるコードから外部の場所のパッケージを登録するときに、外部の場所のパスを指定します。パッケージ自体には存在しないマニフェスト内で参照するすべてのコンテンツは、外部の場所にインストールする必要があります。
TargetDeviceFamily 要素の MinVersion 属性は、10.0.19000.0 以降のバージョンに設定する必要があります。
Application 要素の TrustLevel=mediumIL 属性と RuntimeBehavior=Win32App 属性では、外部の場所のパッケージに関連付けられているデスクトップアプリが、レジストリとファイルシステムの仮想化やその他の実行時の変更なしに、パッケージ化されていない標準のデスクトップアプリと同様に動作することが宣言されます。

次の例は、外部の場所のパッケージマニフェスト (AppxManifest.xml) の完全な内容を示しています。このマニフェストには、パッケージ ID を必要とする windows.sharetarget 拡張機能が含まれます。

<?xml version="1.0" encoding="utf-8"?>
<Package 
  xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
  xmlns:uap="http://schemas.microsoft.com/appx/manifest/uap/windows10"
  xmlns:uap2="http://schemas.microsoft.com/appx/manifest/uap/windows10/2"
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  xmlns:rescap="http://schemas.microsoft.com/appx/manifest/foundation/windows10/restrictedcapabilities"
  xmlns:desktop="http://schemas.microsoft.com/appx/manifest/desktop/windows10"
  xmlns:uap10="http://schemas.microsoft.com/appx/manifest/uap/windows10/10"
  IgnorableNamespaces="uap uap2 uap3 rescap desktop uap10">
  <Identity Name="ContosoPhotoStore" ProcessorArchitecture="x64" Publisher="CN=Contoso" Version="1.0.0.0" />
  <Properties>
    <DisplayName>ContosoPhotoStore</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.19000.0" MaxVersionTested="10.0.19000.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="Demonstrate photo app" BackgroundColor="transparent" Square150x150Logo="Assets\Square150x150Logo.png" Square44x44Logo="Assets\Square44x44Logo.png">
        <uap:DefaultTile Wide310x150Logo="Assets\Wide310x150Logo.png" Square310x310Logo="Assets\LargeTile.png" Square71x71Logo="Assets\SmallTile.png"></uap:DefaultTile>
        <uap:SplashScreen Image="Assets\SplashScreen.png" />
      </uap:VisualElements>
      <Extensions>
        <uap:Extension Category="windows.shareTarget">
          <uap:ShareTarget Description="Send to ContosoPhotoStore">
            <uap:SupportedFileTypes>
              <uap:FileType>.jpg</uap:FileType>
              <uap:FileType>.png</uap:FileType>
              <uap:FileType>.gif</uap:FileType>
            </uap:SupportedFileTypes>
            <uap:DataFormat>StorageItems</uap:DataFormat>
            <uap:DataFormat>Bitmap</uap:DataFormat>
          </uap:ShareTarget>
        </uap:Extension>
      </Extensions>
    </Application>
  </Applications>
</Package>

外部の場所のパッケージをビルドして署名する

パッケージマニフェストを作成したら、Windows SDK の MakeAppx.exe ツールを使用して、外部の場所のパッケージをビルドします。外部の場所のパッケージにはマニフェストで参照されるファイルが含まれていないため、パッケージのセマンティック検証をスキップする /nv オプションを指定する必要があります。

次の例は、コマンドラインから外部の場所のパッケージを作成する方法を示しています。

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

外部の場所のパッケージがターゲットコンピューターに正常にインストールされるようにするには、ターゲットコンピューター上で信頼されている証明書を使用してそのパッケージに署名する必要があります。開発目的の新しい自己署名証明書を作成し、Windows SDK で使用できる SignTool を使用して外部の場所のパッケージに署名することができます。

次の例は、コマンドラインから外部の場所のパッケージに署名する方法を示しています。

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

デスクトップアプリケーションマニフェストにパッケージ ID メタデータを追加する

デスクトップアプリケーションにサイドバイサイドアプリケーションマニフェストを含める必要もあります。「アプリケーションマニフェスト」を参照してください (これは DPI 認識などを宣言するファイルで、ビルド中にアプリの .exe に埋め込まれます)。このファイルに、アプリの ID 属性を宣言する属性を持つ msix 要素を含めます。これらの属性の値は、実行可能ファイルの起動時にアプリの ID を決定するために OS によって使用されます。

次の例は、msix 要素を含むサイドバイサイドアプリケーションマニフェストを示しています。

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

msix 要素の属性は、外部の場所のパッケージのパッケージマニフェストの次の値と一致する必要があります。

packageName 属性と publisher 属性はそれぞれ、パッケージマニフェストの Identity 要素の Name 属性と Publisher 属性と一致する必要があります。
applicationId 属性は、パッケージマニフェストの Application 要素の Id 属性と一致する必要があります。

実行時に外部の場所のパッケージを登録する

デスクトップアプリにパッケージ ID を付与するには、PackageManager クラスの AddPackageByUriAsync メソッドを使用して、外部の場所のパッケージを登録する必要があります。このメソッドは、Windows 10 バージョン 2004 以降で使うことができます。アプリを初めて実行するときに外部の場所のパッケージを登録するコードをアプリに追加したり、デスクトップアプリのインストール中にパッケージを登録するコードを実行したりできます (たとえば、MSI を使用してデスクトップアプリをインストールする場合、カスタムアクションからこのコードを実行できます)。

次の例では、外部の場所のパッケージを登録する方法を示します。このコードでは AddPackageOptions オブジェクトが作成されます。このオブジェクトには、パッケージマニフェストがパッケージ外部のコンテンツを参照できる外部の場所へのパスが含まれています。次に、このオブジェクトが AddPackageByUriAsync メソッドに渡されて、外部の場所のパッケージが登録されます。また、このメソッドは、署名された外部の場所のパッケージの場所を URI として受け取ります。より完全な例については、関連するサンプルアプリの StartUp.cs コードファイルを参照してください (このトピックの「サンプルアプリ」セクションを参照してください)。

private static bool registerPackageWithExternalLocation(string externalLocation, string pkgPath)
{
    bool registration = false;
    try
    {
        Uri externalUri = new Uri(externalLocation);
        Uri packageUri = new Uri(pkgPath);

        Console.WriteLine("exe Location {0}", externalLocation);
        Console.WriteLine("msix Address {0}", pkgPath);

        Console.WriteLine("  exe Uri {0}", externalUri);
        Console.WriteLine("  msix Uri {0}", packageUri);

        PackageManager packageManager = new PackageManager();

        // Declare use of an external location
        var options = new AddPackageOptions();
        options.ExternalLocationUri = externalUri;

        Windows.Foundation.IAsyncOperationWithProgress<DeploymentResult, DeploymentProgress> deploymentOperation = packageManager.AddPackageByUriAsync(packageUri, options);

        // Other progress and error-handling code omitted for brevity...
    }
}

サンプルアプリ

外部ロケーションがあるパッケージを使用してパッケージ ID をデスクトップアプリに付与する方法を示す完全な機能を完備したサンプルアプリの詳細については、「SparsePackages (外部ロケーションがあるパッケージ)」を参照してください。このトピックのチュートリアルでは、パッケージ化されていないアプリにパッケージ ID を付与する主な手順について説明しますが、サンプルアプリでは、参照として使用できる完全な例を示します。サンプルのビルドと実行の詳細については、ブログ記事「非パッケージ Win32 アプリの ID、登録、アクティブ化」を参照してください。

このサンプルには、次の項目が含まれます。

PhotoStoreDemo という名前の WPF アプリのソースコード。起動時に、アプリが ID を使用して実行されているかどうかが確認されます。 ID を使用して実行されていない場合は、外部の場所のパッケージが登録され、アプリが再起動されます。これらの手順を実行するコードについては、StartUp.cs を参照してください。
PhotoStoreDemo.exe.manifest という名前のサイドバイサイドアプリケーションマニフェスト。
AppxManifest.xml という名前のパッケージマニフェスト。

次の方法で共有

外部の場所でパッケージ化してパッケージ ID を付与する

重要な概念

外部の場所のパッケージ

外部コンテンツの許可

外部の場所のパッケージのパッケージマニフェストを作成する

外部の場所のパッケージをビルドして署名する

デスクトップアプリケーションマニフェストにパッケージ ID メタデータを追加する

実行時に外部の場所のパッケージを登録する

サンプルアプリ

その他のリソース

次の方法で共有

外部の場所でパッケージ化してパッケージ ID を付与する

重要な概念

外部の場所のパッケージ

外部コンテンツの許可

外部の場所のパッケージのパッケージ マニフェストを作成する

外部の場所のパッケージをビルドして署名する

デスクトップ アプリケーション マニフェストにパッケージ ID メタデータを追加する

実行時に外部の場所のパッケージを登録する

サンプル アプリ

その他のリソース

外部の場所のパッケージのパッケージマニフェストを作成する

デスクトップアプリケーションマニフェストにパッケージ ID メタデータを追加する

サンプルアプリ