Memberikan identitas paket dengan mengemas dengan lokasi eksternal

  • Artikel

Jika Anda memiliki aplikasi desktop yang sudah ada, dengan alat penginstalnya sendiri, sangat sedikit yang perlu Anda ubah untuk mendapatkan manfaat dari identitas paket.

Banyak fitur ekstensibilitas Windows—termasuk tugas latar belakang, pemberitahuan, petak peta langsung, ekstensi menu konteks kustom, dan target berbagi—dapat digunakan oleh aplikasi desktop hanya jika aplikasi tersebut memiliki identitas paket saat runtime. Itu karena sistem operasi (OS) harus dapat mengidentifikasi pemanggil API yang sesuai. Lihat Fitur yang memerlukan identitas paket.

Hanya aplikasi paket yang memiliki identitas paket saat runtime. Untuk definisi aplikasi yang dikemas, tidak dikemas, dan dikemas dengan lokasi eksternal, lihat Gambaran umum penyebaran.

  • Di Windows 10, versi 2004, dan sebelumnya satu-satunya cara untuk memberikan identitas paket ke aplikasi adalah dengan mengemasnya dalam paket MSIX yang ditandatangani (lihat Membangun paket MSIX dari kode Anda). Dalam hal ini, identitas ditentukan dalam manifes paket, dan pendaftaran identitas ditangani oleh alur penyebaran MSIX berdasarkan informasi dalam manifes. Semua konten yang dirujuk dalam manifes paket ada di dalam paket MSIX.
  • Tetapi mulai dari Windows 10, versi 2004, Anda dapat memberikan identitas paket ke aplikasi hanya dengan membangun dan mendaftarkan paket dengan lokasi eksternal dengan aplikasi Anda. Melakukannya mengubahnya menjadi aplikasi yang dipaketkan; khususnya, aplikasi yang dipaketkan dengan lokasi eksternal. Itu karena beberapa aplikasi desktop belum siap untuk semua kontennya ada di dalam paket MSIX. Jadi dukungan ini memungkinkan aplikasi tersebut untuk memiliki identitas paket; sehingga dapat menggunakan fitur ekstensibilitas Windows yang memerlukan identitas paket. Untuk informasi latar belakang selengkapnya, lihat posting blog Identitas, Pendaftaran, dan Aktivasi Aplikasi Win32 Non-paket.

Untuk membangun dan mendaftarkan paket dengan lokasi eksternal (yang memberikan identitas paket ke aplikasi Anda), ikuti langkah-langkah berikut.

  1. Membuat manifes paket untuk paket dengan lokasi eksternal
  2. Membangun dan menandatangani paket dengan lokasi eksternal
  3. Menambahkan metadata identitas paket ke manifes aplikasi desktop Anda
  4. Daftarkan paket Anda dengan lokasi eksternal pada waktu proses

Konsep penting

Fitur berikut memungkinkan aplikasi desktop yang tidak dikemas untuk memperoleh identitas paket.

Paket dengan lokasi eksternal

Paket dengan lokasi eksternal berisi manifes paket, tetapi tidak ada biner dan konten aplikasi lainnya. Manifes paket dengan lokasi eksternal dapat mereferensikan file di luar paket di lokasi eksternal yang telah ditentukan. Seperti disebutkan di atas, dukungan ini memungkinkan aplikasi yang belum siap untuk semua konten mereka hadir di dalam paket MSIX untuk menggunakan fitur ekstensibilitas Windows yang memerlukan identitas paket.

Catatan

Aplikasi desktop yang menggunakan paket dengan lokasi eksternal tidak menerima beberapa manfaat disebarkan sepenuhnya melalui paket MSIX. Manfaat ini termasuk perlindungan perubahan, penginstalan di lokasi terkunci, dan manajemen penuh oleh OS saat penyebaran, run time, dan penghapusan instalasi.

Memperbolehkan konten eksternal

Untuk mendukung paket dengan lokasi eksternal, skema manifes paket sekarang mendukung elemen uap10:AllowExternalContent opsional di bawah elemen Properti. Ini memungkinkan manifes paket Anda untuk mereferensikan konten di luar paket, di lokasi tertentu pada disk.

Misalnya, jika Anda memiliki aplikasi desktop unpackaged yang sudah ada yang menginstal aplikasi yang dapat dieksekusi dan konten lain di C:\Program Files\MyDesktopApp, Anda dapat membuat paket dengan lokasi eksternal yang menyertakan elemen uap10:AllowExternalContent dalam manifes. Selama proses penginstalan untuk aplikasi Anda, atau saat pertama kali aplikasi berjalan, Anda dapat menginstal paket dengan lokasi eksternal dan mendeklarasikan C:\Program Files\MyDesktopApp\ sebagai lokasi eksternal yang akan digunakan aplikasi Anda.

Membuat manifes paket untuk paket dengan lokasi eksternal

Sebelum dapat membuat paket dengan lokasi eksternal, Anda harus terlebih dahulu membuat manifes paket (file bernama AppxManifest.xml) yang mendeklarasikan metadata identitas paket untuk aplikasi desktop Anda dan detail lain yang diperlukan. Cara term mudah untuk membuat manifes paket untuk paket dengan lokasi eksternal adalah dengan menggunakan contoh di bawah ini dan menyesuaikannya untuk aplikasi Anda dengan menggunakan referensi skema.

Pastikan manifes paket menyertakan item ini:

  • Elemen Identitas yang menjelaskan atribut identitas untuk aplikasi desktop Anda.
  • Elemen uap10:AllowExternalContent di bawah elemen Properti. Elemen ini harus diberi nilai true, yang memungkinkan manifes paket Anda untuk mereferensikan konten di luar paket, di lokasi tertentu pada disk. Di langkah selanjutnya, Anda akan menentukan jalur lokasi eksternal saat mendaftarkan paket dengan lokasi eksternal dari kode yang berjalan di penginstal atau aplikasi Anda. Konten apa pun yang Anda referensikan dalam manifes yang tidak terletak di paket itu sendiri harus diinstal ke lokasi eksternal.
  • Atribut MinVersion dari elemen TargetDeviceFamily harus diatur ke 10.0.19000.0 atau versi yang lebih baru.
  • Atribut TrustLevel=mediumIL dan RuntimeBehavior=Win32App dari elemen Aplikasi menyatakan bahwa aplikasi desktop yang terkait dengan paket dengan lokasi eksternal akan berjalan mirip dengan aplikasi desktop standar yang tidak dikemas, tanpa registri dan virtualisasi sistem file dan perubahan run time lainnya.

Contoh berikut menunjukkan konten lengkap paket dengan manifes lokasi eksternal (AppxManifest.xml). Manifes ini mencakup windows.sharetarget ekstensi, yang memerlukan identitas paket.

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

Membangun dan menandatangani paket dengan lokasi eksternal

Setelah Anda membuat manifes paket, buat paket dengan lokasi eksternal dengan menggunakan alat MakeAppx.exe di Windows SDK. Karena paket dengan lokasi eksternal tidak berisi file yang dirujuk dalam manifes, Anda harus menentukan /nv opsi , yang melewati validasi semantik untuk paket.

Contoh berikut menunjukkan cara membuat paket dengan lokasi eksternal dari baris perintah.

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

Sebelum paket Anda dengan lokasi eksternal berhasil diinstal pada komputer target, Anda harus menandatanganinya dengan sertifikat yang tepercaya pada komputer target. Anda dapat membuat sertifikat baru yang ditandatangani sendiri untuk tujuan pengembangan dan menandatangani paket Anda dengan lokasi eksternal menggunakan SignTool, yang tersedia di Windows SDK.

Contoh berikut menunjukkan cara menandatangani paket dengan lokasi eksternal dari baris perintah.

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

Menambahkan metadata identitas paket ke manifes aplikasi desktop Anda

Anda juga harus menyertakan manifes aplikasi berdampingan dengan aplikasi desktop Anda. Lihat Manifes aplikasi (ini adalah file yang mendeklarasikan hal-hal seperti kesadaran DPI, dan disematkan ke dalam aplikasi .exe Anda selama build). Dalam file tersebut, sertakan elemen msix dengan atribut yang mendeklarasikan atribut identitas aplikasi Anda. Nilai atribut ini digunakan oleh OS untuk menentukan identitas aplikasi Anda saat executable diluncurkan.

Contoh berikut menunjukkan manifes aplikasi berdampingan dengan elemen 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>

Atribut elemen msix harus cocok dengan nilai-nilai ini dalam manifes paket untuk paket Anda dengan lokasi eksternal:

  • Atribut packageName dan publisher harus sesuai dengan atribut Name dan Publisher di elemen Identity dalam manifes paket Anda.
  • Atribut applicationId harus cocok dengan atribut Id elemen Aplikasi dalam manifes paket Anda.

Daftarkan paket Anda dengan lokasi eksternal pada waktu proses

Untuk memberikan identitas paket ke aplikasi desktop Anda, aplikasi Anda harus mendaftarkan paket dengan lokasi eksternal dengan menggunakan metode AddPackageByUriAsync dari kelas PackageManager. Metode ini tersedia mulai windows 10, versi 2004. Anda dapat menambahkan kode ke aplikasi untuk mendaftarkan paket dengan lokasi eksternal saat aplikasi dijalankan untuk pertama kalinya, atau Anda dapat menjalankan kode untuk mendaftarkan paket saat aplikasi desktop diinstal (misalnya, jika Anda menggunakan MSI untuk menginstal aplikasi desktop, Anda dapat menjalankan kode ini dari tindakan kustom).

Contoh berikut menunjukkan cara mendaftarkan paket dengan lokasi eksternal. Kode ini membuat objek AddPackageOptions yang berisi jalur ke lokasi eksternal tempat manifes paket Anda dapat mereferensikan konten di luar paket. Kemudian, kode meneruskan objek ini ke metode AddPackageByUriAsync untuk mendaftarkan paket dengan lokasi eksternal. Metode ini juga menerima lokasi paket anda yang ditandatangani dengan lokasi eksternal sebagai URI. Untuk contoh yang lebih lengkap, lihat StartUp.cs file kode di aplikasi sampel terkait (lihat bagian Aplikasi sampel dalam topik ini).

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

Aplikasi sampel

Lihat sampel SparsePackages untuk aplikasi sampel yang berfungsi penuh yang menunjukkan cara memberikan identitas paket ke aplikasi desktop menggunakan paket dengan lokasi eksternal. Informasi selengkapnya tentang membangun dan menjalankan sampel disediakan dalam posting blog Identitas, Pendaftaran, dan Aktivasi Aplikasi Win32 non-paket.

Sampel ini mencakup hal-hal berikut:

  • Kode sumber untuk aplikasi WPF bernama PhotoStoreDemo. Selama startup, aplikasi memeriksa untuk melihat apakah aplikasi berjalan dengan identitas. Jika tidak berjalan dengan identitas, ia mendaftarkan paket dengan lokasi eksternal, lalu memulai ulang aplikasi. Lihat StartUp.cs untuk kode yang melakukan langkah-langkah ini.
  • Manifes aplikasi berdampingan bernama PhotoStoreDemo.exe.manifest.
  • Manifes paket bernama AppxManifest.xml.