パッケージ化されていないデスクトップ アプリに ID を付与するGrant identity to non-packaged desktop apps

Windows 10 の拡張機能の多くは、バックグラウンド タスク、通知、ライブ タイル、共有ターゲットなど、UWP 以外のデスクトップ アプリから使用するためにパッケージ ID を必要とします。Many Windows 10 extensibility features require package identity to be used from non-UWP desktop apps, including background tasks, notifications, live tiles, and share targets. これらのシナリオでは、OS は、対応する API の呼び出し元を識別できるようにするために ID を必要とします。For these scenarios, the OS requires identity so that it can identify the caller of the corresponding API.

Windows 10 バージョン 2004 より前の OS リリースでは、デスクトップ アプリに ID を付与する唯一の方法は、署名済みの MSIX パッケージでパッケージ化することです。In OS releases before Windows 10, version 2004, the only way to grant identity to a desktop app is to package it in a signed MSIX package. これらのアプリの場合、ID はパッケージ マニフェストに指定され、ID 登録はマニフェストの情報に基づいて MSIX 展開パイプラインによって処理されます。For these apps, identity is specified in the package manifest and identity registration is handled by the MSIX deployment pipeline based on the information in the manifest. パッケージ マニフェストで参照されるすべてのコンテンツは、MSIX パッケージ内に存在します。All content referenced in the package manifest is present inside the MSIX package.

Windows 10 バージョン 2004 以降では、アプリでスパース パッケージをビルドして登録することで、MSIX パッケージにパッケージ化されていないデスクトップ アプリにパッケージ ID を付与できます。Starting in Windows 10, version 2004, you can grant package identity to desktop apps that are not packaged in an MSIX package by building and registering a sparse package with your app. このサポートにより、展開のために MSIX パッケージをまだ導入できないデスクトップ アプリで、パッケージ ID を必要とする Windows 10 拡張機能を使用できるようになります。This support enables desktop apps that are not yet able to adopt MSIX packaging for deployment to use Windows 10 extensibility features that require package identity. 詳細な背景情報については、このブログ投稿を参照してください。For more background info, see this blog post.

デスクトップ アプリにパッケージ ID を付与するスパース パッケージをビルドして登録するには、次の手順に従います。To build and register a sparse package that grants package identity to your desktop app, follow these steps.

  1. スパース パッケージのパッケージ マニフェストを作成するCreate a package manifest for the sparse package
  2. スパース パッケージをビルドして署名するBuild and sign the sparse package
  3. デスクトップ アプリケーション マニフェストにパッケージ ID メタデータを追加するAdd the package identity metadata to your desktop application manifest
  4. 実行時にスパース パッケージを登録するRegister your sparse package at run time

重要な概念Important concepts

次の機能を使用すると、パッケージ化されていないデスクトップ アプリでパッケージ ID を取得できます。The following features enable non-packaged desktop apps to acquire package identity.

スパース パッケージSparse packages

スパース パッケージにはパッケージ マニフェストが含まれていますが、他のアプリ バイナリやコンテンツは含まれていません。A sparse package contains a package manifest but no other app binaries and content. スパース パッケージのマニフェストでは、事前に定義された外部の場所で、パッケージ外部のファイルを参照できます。The manifest of a sparse package can reference files outside the package in a predetermined external location. これにより、アプリ全体に対して MSIX パッケージをまだ導入できないアプリケーションで、一部の Windows 10 拡張機能によって必要とされるパッケージ ID を取得できるようになります。This allows applications that are not yet able to adopt MSIX packaging for their entire app to acquire package identity as required by some Windows 10 extensibility features.

注意

スパース パッケージを使用するデスクトップ アプリでは、MSIX パッケージを使用して完全に展開される場合の一部の利点が得られません。A desktop app that uses a sparse package does not receive some benefits of being fully deployed via an MSIX package. これらの利点には、改ざん防止、ロックダウンされた場所へのインストール、展開、実行時、およびアンインストール時の OS による完全な管理などがあります。These benefits include tamper protection, installation in a locked-down location, and full management by the OS at deployment, run time, and uninstall.

パッケージ外部の場所Package external location

スパース パッケージをサポートするために、パッケージ マニフェスト スキーマでは、Properties 要素の下にある省略可能な uap10:AllowExternalContent 要素がサポートされるようになりました。To support sparse packages, the package manifest schema now supports an optional uap10:AllowExternalContent element under the Properties element. これにより、パッケージ マニフェストでは、ディスク上の特定の場所にあるパッケージ外部のコンテンツを参照できます。This allows your package manifest to reference content outside the package, in a specific location on disk.

たとえば、アプリの実行可能ファイルとその他のコンテンツを C:\Program Files\MyDesktopApp, にインストールする、パッケージ化されていない既存のデスクトップ アプリがある場合は、マニフェスト内に uap10:AllowExternalContent 要素を含むスパース パッケージを作成できます。For example, if you have your existing non-packaged desktop app that installs the app executable and other content in C:\Program Files\MyDesktopApp, you can create a sparse package that includes the uap10:AllowExternalContent element in the manifest. アプリのインストール プロセス中、またはアプリの初回起動時に、スパース パッケージをインストールし、アプリで使用する外部の場所として C:\Program Files\MyDesktopApp\ を宣言することができます。During the install process for your app or the first time your apps, you can install the sparse package and declare C:\Program Files\MyDesktopApp\ as the external location your app will use.

スパース パッケージのパッケージ マニフェストを作成するCreate a package manifest for the sparse package

スパース パッケージをビルドするには、まず、デスクトップ アプリのパッケージ ID メタデータとその他の必要な詳細を宣言するパッケージ マニフェスト (AppxManifest.xml という名前のファイル) を作成する必要があります。Before you can build a sparse package, you must first create a package manifest (a file named AppxManifest.xml) that declares package identity metadata for your desktop app and other required details. スパース パッケージのパッケージ マニフェストを作成する最も簡単な方法は、次の例を用いて、スキーマ参照を使用してアプリ用にカスタマイズすることです。The easiest way to create a package manifest for the sparse package is to use the example below and customize it for your app by using the schema reference.

パッケージ マニフェストに次の項目が含まれることを確認してください。Make sure the package manifest includes these items:

  • デスクトップ アプリの ID 属性を記述する Identity 要素。An Identity element that describes the identity attributes for your desktop app.
  • Properties 要素の下にある uap10:AllowExternalContent 要素。An uap10:AllowExternalContent element under the Properties element. この要素には値 true を割り当てる必要があります。これにより、パッケージ マニフェストでは、ディスク上の特定の場所にあるパッケージ外部のコンテンツを参照できます。This element should be assigned the value true, which allows your package manifest to reference content outside the package, in a specific location on disk. 後の手順で、インストーラーまたはアプリで実行されるコードからスパース パッケージを登録するときに、外部の場所のパスを指定します。In a later step, you'll specify the path of the external location when you register your sparse package from code that runs in your installer or your app. パッケージ自体には存在しないマニフェスト内で参照するすべてのコンテンツは、外部の場所にインストールする必要があります。Any content that you reference in the manifest that isn’t located in the package itself should be installed to the external location.
  • TargetDeviceFamily 要素の MinVersion 属性は、10.0.19000.0 以降のバージョンに設定する必要があります。The MinVersion attribute of the TargetDeviceFamily element should be set to 10.0.19000.0 or a later version.
  • Application 要素の TrustLevel=mediumIL 属性と RuntimeBehavior=Win32App 属性では、スパース パッケージに関連付けられているデスクトップ アプリが、レジストリとファイル システムの仮想化やその他の実行時の変更なしに、パッケージ化されていない標準のデスクトップ アプリと同様に動作することが宣言されます。The TrustLevel=mediumIL and RuntimeBehavior=Win32App attributes of the Application element declare that the desktop app associated with the sparse package will run similar to a standard unpackaged desktop app, without registry and file system virtualization and other run time changes.

次の例は、スパース パッケージ マニフェスト (AppxManifest.xml) の完全な内容を示しています。The following example shows the complete contents of a sparse package manifest (AppxManifest.xml). このマニフェストには、パッケージ ID を必要とする windows.sharetarget 拡張機能が含まれます。This manifest includes a windows.sharetarget extension, which requires package identity.

<?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>

スパース パッケージをビルドして署名するBuild and sign the sparse package

パッケージ マニフェストを作成したら、Windows SDK の MakeAppx.exe ツールを使用して、スパース パッケージをビルドします。After you create your package manifest, build the sparse package by using the MakeAppx.exe tool in the Windows SDK. スパース パッケージにはマニフェストで参照されるファイルが含まれていないため、パッケージのセマンティック検証をスキップする /nv オプションを指定する必要があります。Because the sparse package doesn’t contain the files referenced in the manifest, you must specify the /nv option, which skips semantic validation for the package.

次の例は、コマンド ラインからスパース パッケージを作成する方法を示しています。The following example demonstrates how to create a sparse package from the command line.

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

スパース パッケージがターゲット コンピューターに正常にインストールされるようにするには、ターゲット コンピューター上で信頼されている証明書を使用してそのパッケージに署名する必要があります。Before your sparse package can be successfully installed on a target computer, you must sign it with a certificate that is trusted on the target computer. 開発目的の新しい自己署名証明書を作成し、Windows SDK で使用できる SignTool を使用してスパース パッケージに署名することができます。You can create a new self-signed certificate for development purposes and sign your sparse package using SignTool, which is available in the Windows SDK.

次の例は、コマンド ラインからスパース パッケージに署名する方法を示しています。The following example demonstrates how to sign a sparse package from the command line.

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

デスクトップ アプリケーション マニフェストにパッケージ ID メタデータを追加するAdd the package identity metadata to your desktop application manifest

また、デスクトップ アプリと共にサイドバイサイド アプリケーション マニフェストを追加し、アプリの ID 属性を宣言する属性と共に msix 要素を含める必要があります。You must also include a side-by-side application manifest with your desktop app and include an msix element with attributes that declare the identity attributes of your app. これらの属性の値は、実行可能ファイルの起動時にアプリの ID を決定するために OS によって使用されます。The values of these attributes are used by the OS to determine your app's identity when the executable is launched.

次の例は、msix 要素を含むサイドバイサイド アプリケーション マニフェストを示しています。The following example shows a side-by-side application manifest with an msix element.

<?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 要素の属性は、スパース パッケージのパッケージ マニフェストの次の値と一致する必要があります。The attributes of the msix element must match these values in the package manifest for your sparse package:

  • packageName 属性と publisher 属性はそれぞれ、パッケージ マニフェストの Identity 要素の Name 属性と Publisher 属性と一致する必要があります。The packageName and publisher attributes must match the Name and Publisher attributes in the Identity element in your package manifest, respectively.
  • applicationId 属性は、パッケージ マニフェストの Application 要素の Id 属性と一致する必要があります。The applicationId attribute must match the Id attribute of the Application element in your package manifest.

サイドバイサイド アプリケーション マニフェストは、デスクトップ アプリの実行可能ファイルと同じディレクトリに存在する必要があります。また、規則により、これはアプリの実行可能ファイルと同じ名前で、.manifest 拡張子を付加する必要があります。The side-by-side application manifest must exist in the same directory as the executable file for your desktop app, and by convention it should have the same name as your app's executable file with the .manifest extension appended to it. たとえば、アプリの実行可能ファイル名が ContosoPhotoStore の場合、アプリケーション マニフェスト ファイル名は ContosoPhotoStore.exe.manifest である必要があります。For example, if your app's executable name is ContosoPhotoStore, the application manifest filename should be ContosoPhotoStore.exe.manifest.

実行時にスパース パッケージを登録するRegister your sparse package at run time

デスクトップ アプリにパッケージ ID を付与するには、PackageManager クラスの AddPackageByUriAsync メソッドを使用して、スパース パッケージを登録する必要があります。To grant package identity to your desktop app, your app must register the sparse package by using the AddPackageByUriAsync method of the PackageManager class. このメソッドは、Windows 10 バージョン 2004 以降で使うことができます。This method is available starting in Windows 10, version 2004. アプリを初めて実行するときにスパース パッケージを登録するコードをアプリに追加したり、デスクトップ アプリのインストール中にパッケージを登録するコードを実行したりできます (たとえば、MSI を使用してデスクトップ アプリをインストールする場合、カスタム アクションからこのコードを実行できます)。You can add code to your app to register the sparse package when your app is run for the first time, or you can run code to register the package while your desktop app is installed (for example, if you're using MSI to install your desktop app, you can run this code from a custom action).

次の例は、スパース パッケージを登録する方法を示しています。The following example demonstrates how to register a sparse package. このコードでは AddPackageOptions オブジェクトが作成されます。このオブジェクトには、パッケージ マニフェストがパッケージ外部のコンテンツを参照できる外部の場所へのパスが含まれています。This code creates an AddPackageOptions object that contains the path to the external location where your package manifest can reference content outside the package. 次に、このオブジェクトが AddPackageByUriAsync メソッドに渡されて、スパース パッケージが登録されます。Then, the code passes this object to the AddPackageByUriAsync method to register the sparse package. また、このメソッドは、署名されたスパース パッケージの場所を URI として受け取ります。This method also receives the location of your signed sparse package as a URI. 詳細な例については、関連するサンプルStartUp.cs コードファイルを参照してください。For a more complete example, see the StartUp.cs code file in the related sample.

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

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

        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...
    }
}

[サンプル]Sample

スパース パッケージを使用してデスクトップ アプリにパッケージ ID を付与する方法を示す、完全な機能を備えたサンプル アプリについては、SparesePackages のサンプルを参照してください。See the SparesePackages sample for a fully functional sample app that demonstrates how to grant package identity to a desktop app using a sparse package. サンプルのビルドと実行の詳細については、このブログ投稿を参照してください。More information about building and running the sample is provided in this blog post.

このサンプルには、次の項目が含まれます。This sample includes the following:

  • PhotoStoreDemo という名前の WPF アプリのソース コード。The source code for a WPF app named PhotoStoreDemo. 起動時に、アプリが ID を使用して実行されているかどうかが確認されます。During startup, the app checks to see whether it is running with identity. ID を使用して実行されていない場合は、スパース パッケージが登録され、アプリが再起動されます。If it is not running with identity, it registers the sparse package and then restarts the app. これらの手順を実行するコードについては、StartUp.cs を参照してください。See StartUp.cs for the code that performs these steps.
  • PhotoStoreDemo.exe.manifest という名前のサイドバイサイド アプリケーション マニフェスト。A side-by-side application manifest named PhotoStoreDemo.exe.manifest.
  • AppxManifest.xml という名前のパッケージ マニフェスト。A package manifest named AppxManifest.xml.