Delen via

Pakketidentiteit verlenen door pakketten handmatig te verpakken met externe locatie

Zie Overzicht voor de motivaties achter het toevoegen van pakketidentiteit, evenals de verschillen tussen het bouwen van identiteitspakketten in Visual Studio en het handmatig bouwen ervan.

In dit onderwerp wordt beschreven hoe u handmatig een identiteitspakket bouwt en registreert. Zie Pakketidentiteit verlenen door pakketten te verpakken met een externe locatie in Visual Studio voor meer informatie over het bouwen van een identiteitspakket in Visual Studio.

Dit zijn de stappen (die in dit onderwerp in detail worden beschreven) om handmatig een identiteitspakket te bouwen en te registreren:

  1. Een pakketmanifest maken voor het identiteitspakket
  2. Het identiteitspakket bouwen en ondertekenen
  3. Identiteitsmetagegevens toevoegen aan uw bureaubladtoepassingsmanifesten
  4. Het identiteitspakket registreren in uw installatieprogramma
  5. Optionele stappen

Een pakketmanifest maken voor het identiteitspakket

De eerste stap bij het maken van een identiteitspakket is het maken van een pakketmanifest op basis van de onderstaande sjabloon. Dit is een MSIX-manifest, maar wordt alleen gebruikt voor identiteit en wijzigt het runtimegedrag van de app niet.

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

Let op de onderstaande belangrijke details over dit manifest:

  • Vul de Identity elementkenmerken in met de details van uw toepassing
    • Name is de gewenste naam van het identiteitspakket
    • Publisher moet overeenkomen met het Subject certificaat dat wordt gebruikt om de toepassing te ondertekenen
    • Version is de gewenste versie van het identiteitspakket. Een veelvoorkomende procedure is het afstemmen van de versie van het identiteitspakket met de toepassingsversie. U kunt geen versie van een identiteitspakket registreren op een systeem als die versie van het pakket al is geregistreerd. U moet eerst de registratie van het bestaande pakket ongedaan maken om een pakket opnieuw te installeren met dezelfde versie.
    • ProcessorArchitecture moet neutral zijn zoals getoond, zodat het identiteitspakket werkt op alle architectuurtypen (x86, x64 en ARM64)
  • Vul de DisplayName en PublisherDisplayName elementen in met de details van uw toepassing
    • Tenzij u extra functies aan het manifest toevoegt buiten een eenvoudige identiteit, worden deze waarden nergens weergegeven
  • Werk het Logo element bij naar een relatief pad in de installatiemap van uw applicatie dat verwijst naar een .png, .jpgof .jpeg afbeelding.
  • Zorg ervoor dat het AllowExternalContent element is ingesteld zoals wordt weergegeven op true, zodat uw bestaande installatieprogramma opnieuw gebruikt kan worden.
  • Stel TargetDeviceFamilyMinVersion en MaxVersionTested in zoals hieronder.
    • Ingesteld MinVersion op 10.0.19041.0 zoals wordt weergegeven voor maximale bereik en uniformiteit in windows 10- en Windows 11-besturingssysteemversies
    • Stel MinVersion in op 10.0.26100.0 om het identiteitspakket te beperken tot Windows 11, versie 24H2 en later
    • Ingesteld MaxVersionTested op 10.0.26100.0 zoals weergegeven
    • Opmerking: de AllowExternalContent functie die hier wordt gebruikt, is geïntroduceerd in Windows build 10.0.19041.0. Als uw toepassing verder omlaag wordt uitgevoerd, moet u een besturingssysteemversiecontrole uitvoeren in uw installatieprogramma en het identiteitspakket niet registreren op besturingssysteemversies ouder dan 10.0.19041.0. Zie Het identiteitspakket registreren in uw installatieprogramma.
  • Zorg ervoor dat de runFullTrust- en unvirtualizedResources-functionaliteiten worden gedeclareerd zoals weergegeven voor de Win32-compatibiliteit.
  • Application Een element toevoegen zoals wordt weergegeven voor elk uitvoerbaar bestand dat is gekoppeld aan uw toepassing
    • Zorg ervoor dat TrustLevel is mediumIL en RuntimeBehavior is win32App zoals aangegeven voor Win32-compatibiliteit.
  • Het VisualElements kindelement is vereist, maar het AppListEntry="none" kenmerk zorgt ervoor dat het identiteitspakket niet wordt weergegeven bij de geïnstalleerde apps.
    • Werk de DisplayName en Description attributen bij met relevante details en laat de andere attributen zoals getoond (de verwijzende afbeeldingpaden hoeven niet te worden opgelost)
    • Zie Lokalisatie en visuele assets voor scenario's waarin lokalisatie en afbeeldingen mogelijk hier nodig zijn.

Het identiteitspakket dat is gemaakt op basis van dit manifest, wordt verbonden met de installatiemap van uw toepassing wanneer u het pakket in een latere stap registreert.

Het identiteitspakket bouwen en ondertekenen

Nadat u uw identiteitspakketmanifest hebt gemaakt, maakt u het identiteitspakket met behulp van het hulpprogrammaMakeAppx.exe in de Windows SDK.

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

Opmerking: de /nv vlag is vereist om validatie van bestandspaden waarnaar wordt verwezen, over te slaan in het manifest.

Om te kunnen worden geïnstalleerd op computers van eindgebruikers, moet het identiteitspakket worden ondertekend met een certificaat dat wordt vertrouwd op de doelcomputer. U kunt een nieuw zelfondertekend certificaat maken voor ontwikkelingsdoeleinden en uw identiteitspakket ondertekenen met SignTool, dat beschikbaar is in de Windows SDK, maar een productiecertificaat van een IT-afdeling of een service zoals Vertrouwde Ondertekening van Azure moet het pakket registreren op computers van eindgebruikers.

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

Opmerking: Zie het MSIX- en CI/CD-pijplijnoverzicht voor voorbeelden van het bouwen en ondertekenen van het identiteitspakket in een CI/CD-pijplijn met productiecertificaten.

Identiteitsmetagegevens toevoegen aan uw bureaubladtoepassingsmanifesten

U verbindt het identiteitspakket met uitvoerbare bestanden van uw toepassing door toepassingsmanifesten toe te voegen (ook wel bekend als side-by-side of fusion manifests) met metagegevens die overeenkomen met metagegevens uit het manifest van het identiteitspakket.

In Visual Studio kunt u een toepassingsmanifest toevoegen aan een uitvoerbaar project door het Project contextmenu te openen en Toevoegen>Nieuw Item>Applicatiemanifestbestand te selecteren.

Hieronder ziet u een voorbeeld van een toepassingsmanifestfragment waarin het msix element wordt gedemonstreerd dat nodig is om uw binaire bestanden te verbinden met metagegevens uit uw identiteitspakket.

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

De kenmerken van het element moeten overeenkomen met deze waarden uit het manifest van het msix identiteitspakket:

  • De packageName- en publisher-kenmerken moeten respectievelijk overeenkomen met de Name- en Publisher-kenmerken in het Identity-element van het manifest van uw identiteitspakket.
  • Het applicationId kenmerk moet overeenkomen met het Id kenmerk van het bijbehorende Application element in uw identiteitspakketmanifest

Het identiteitspakket registreren in uw installatieprogramma

De laatste stap voor het koppelen van identiteit aan uw toepassing is door het identiteitspakket in uw installatieprogramma te registreren en het te koppelen aan de installatiemap van uw toepassing.

PowerShell

Het uitvoeren van powershell.exe met de juiste parameters is de eenvoudigste manier om het pakket te registreren. De richtlijnen verschillen voor installaties per gebruiker versus machinebrede installaties.

Per-User (PowerShell)

Het identiteitspakket registreren tijdens een installatie per gebruiker:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Path <PackagePath> -ExternalLocation <ExternalLocation>"
  • Stel <PackagePath> in op het absolute pad van het ondertekende identiteitspakket dat in de vorige stap werd geproduceerd (met de bestandsnaam).
  • Stel <ExternalLocation> in op het absolute pad van de installatiemap van uw toepassing (zonder uitvoerbare bestanden).

De registratie van het identiteitspakket ongedaan maken tijdens het verwijderen per gebruiker:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Get-AppxPackage <PackageName> | Remove-AppxPackage"
  • Stel <PackageName> in op de pakketnaam die u hebt gedefinieerd in uw identiteitspakketmanifest (het kenmerk Naam van het element Identiteit)

Per-Machine (PowerShell)

Het identiteitspakket registreren tijdens een computerbrede installatie:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Stage <PackagePath> -ExternalLocation <ExternalLocation>; Add-AppxProvisionedPackage -Online -PackagePath <PackagePath>"
  • Stel <PackagePath> in op het absolute pad van het ondertekend identiteitspakket dat in de vorige stap is geproduceerd (met de bestandsnaam).
  • Stel <ExternalLocation> in op het absolute pad van de installatiemap van uw toepassing (zonder uitvoerbare bestanden).

De registratie van het identiteitspakket ongedaan maken tijdens het verwijderen van een computer:

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 }
  • Stel <PackageName> in op de pakketnaam die je hebt gedefinieerd in je identiteitspakketmanifest (het kenmerk Naam van het element Identiteit)

PackageManager API's

Als u liever OS-API's aanroept om het identiteitspakket te registreren en de registratie ervan ongedaan te maken, biedt de PackageManager-API equivalente functionaliteit voor PowerShell. De richtlijnen verschillen voor installaties per gebruiker versus machinebrede installaties.

Hieronder ziet u codefragmenten die de API demonstreren. Zie Voorbeeld-apps voor code die gereed is voor productie in C# en C++.

Per-User (PackageManager)

In de onderstaande codevermelding ziet u hoe u het identiteitspakket registreert met behulp van de methode AddPackageByUriAsync en de registratie van het identiteitspakket ongedaan maakt met behulp van de methode 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);
}

Let op de onderstaande belangrijke details over deze code:

  • Stel externalLocation in op het absolute pad van uw toepassingsinstallatiemap (zonder uitvoerbare bestandsnamen)
  • Stel packagePath in op het absolute pad van het ondertekende identiteitspakket dat in de vorige stap is geproduceerd, inclusief de bestandsnaam.
  • Je kunt de <IdentityPackageFamilyName> vinden door het Get-AppxPackage <IdentityPackageName> PowerShell-opdracht uit te voeren op een systeem waar het identiteitspakket is geregistreerd. De PackageFamilyName eigenschap bevat de waarde die hier moet worden gebruikt.

Per-Machine (PackageManager)

De onderstaande codevermelding laat zien hoe u het identiteitspakket registreert met behulp van de methoden StagePackageByUriAsync en ProvisionPackageForAllUsersAsync en de registratie van het identiteitspakket opheffen met behulp van de methoden DeprovisionPackageForAllUsersAsync en 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);
}

Let op de onderstaande belangrijke details over deze code:

  • Stel externalLocation in op het absolute pad van uw toepassingsinstallatiemap (zonder uitvoerbare bestandsnamen)
  • Stel packagePath naar het absolute pad van het ondertekende identiteitspakket dat in de vorige stap is geproduceerd (met de bestandsnaam)
  • De <IdentityPackageFamilyName> kan worden gevonden door de Get-AppxPackage <IdentityPackageName> PowerShell-opdracht uit te voeren op een systeem waar het identiteitspakket is geregistreerd. De PackageFamilyName eigenschap bevat de waarde die hier moet worden gebruikt.

Voorbeeld-apps

Zie de PackageWithExternalLocation-voorbeelden voor volledig functionele C# en C++-apps die laten zien hoe u een identiteitspakket registreert en de registratie ervan ongedaan maakt.

Optionele stappen

Lokalisatie en visuele elementen

Sommige functies die de pakketidentiteit begrijpen, kunnen ertoe leiden dat tekenreeksen en afbeeldingen uit uw identiteitspakketmanifest worden weergegeven in het Windows-besturingssysteem. Voorbeeld:

  • Een toepassing die gebruikmaakt van camera-, microfoon- of locatie-API's heeft een speciale schakelaar in de privacyinstellingen van Windows, samen met een toestemmingsprompt die gebruikers kunnen gebruiken om toegang tot deze gevoelige middelen te verlenen of te weigeren.
  • Een toepassing die een sharedoel registreert, wordt weergegeven in het dialoogvenster Delen.

Zie Het manifest lokaliseren om de tekenreeksen in het manifest van het identiteitspakket te lokaliseren.

Wanneer u paden naar afbeeldingen opgeeft in de VisualElements attributen van het manifest van het identiteitspakket, moeten deze relatieve paden zijn binnen de installatiemap van uw toepassing die moeten resulteren in een .png, .jpgof .jpeg afbeelding. De kenmerknamen geven de verwachte afmetingen van de afbeeldingen aan (150x150 en 40x40).