Nadawanie tożsamości pakietowi poprzez ręczne pakowanie z lokalizacją zewnętrzną.

Dlaczego to zrobić? Udzielanie aplikacji tożsamości pakietu (nazywanej również pakietem sparse lub pakowanie z lokalizacją zewnętrzną) odblokowuje funkcje platformy Windows, które są inaczej niedostępne dla niezapakowanych aplikacji: powiadomienia typu toast i push, zadania w tle, rozszerzenia aplikacji, docelowe aplikacje dla funkcji udostępniania, skojarzenia plików, zadania uruchamiania, monity o zgodę na prywatność oraz interfejsy API Windows AI Foundry — wszystko to bez przełączania się na pełne pakowanie MSIX lub zmiany istniejącego instalatora.

Aby uzyskać więcej informacji na temat motywacji do dodawania tożsamości pakietu, a także różnic między tworzeniem pakietów tożsamości w Visual Studio i tworzeniem ich ręcznie, zobacz Overview.

W tym temacie opisano sposób ręcznego kompilowania i rejestrowania pakietu tożsamości. Aby uzyskać informacje o tworzeniu pakietu tożsamości w Visual Studio, zobacz Nadawanie tożsamości pakietowi poprzez pakowanie z lokalizacją zewnętrzną w Visual Studio.

Poniżej przedstawiono kroki opisane szczegółowo w tym temacie, aby utworzyć i zarejestrować pakiet tożsamości ręcznie:

1. Utwórz manifest dla pakietu tożsamości
2. Kompilowanie i podpisywanie pakietu tożsamości
3. Dodaj metadane tożsamości do manifestów aplikacji komputerowych
4. Rejestrowanie pakietu tożsamości w instalatorze
5. Kroki opcjonalne

Utwórz manifest pakietu dla pakietu tożsamości

Pierwszym krokiem tworzenia pakietu tożsamości jest utworzenie manifestu pakietu na podstawie poniższego szablonu. Jest to manifest MSIX, ale jest używany tylko do obsługi tożsamości i nie zmienia zachowania środowiska uruchomieniowego aplikacji.

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

Zwróć uwagę na poniższe ważne szczegóły dotyczące tego manifestu:

• Identity Wypełnij atrybuty elementu szczegółami aplikacji
  • Name to żądana nazwa pakietu tożsamości
  • Publisher musi być zgodna z Subject certyfikatu użytego do podpisania aplikacji
  • Version to żądana wersja pakietu tożsamości. Typowym rozwiązaniem jest dostosowanie wersji pakietu tożsamości do wersji aplikacji. Nie będzie można zarejestrować wersji pakietu tożsamości w systemie, jeśli ta wersja pakietu jest już zarejestrowana. Należy najpierw wyrejestrować istniejący pakiet, aby ponownie zainstalować pakiet z tą samą wersją.
  • ProcessorArchitecture powinien być neutral tak, jak pokazano, aby pakiet tożsamości działał we wszystkich architekturach (x86, x64 i ARM64)
• Wypełnij elementy DisplayName i PublisherDisplayName szczegółami swojej aplikacji
  • Jeśli nie dodasz dodatkowych funkcji do manifestu poza prostą tożsamością, te wartości nie są wyświetlane nigdzie
• Zaktualizuj element Logo do ścieżki względnej w katalogu instalacyjnym aplikacji, aby prowadziła do obrazu .png, .jpglub .jpeg.
• Upewnij się, że element AllowExternalContent jest ustawiony na true, jak pokazano, co umożliwia ponowne użycie istniejącego instalatora.
• Ustaw TargetDeviceFamily, MinVersion oraz MaxVersionTested zgodnie z poniższymi:
  • Wybierz wartość na podstawie MinVersion minimalnego obsługiwanego systemu operacyjnego:
    • 10.0.19041.0 — zalecane dla maksymalnego zasięgu w systemach Windows 10 i Windows 11
    • 10.0.26100.0 — użyj tego tylko wtedy, gdy aplikacja jest przeznaczona dla Windows 11, wersja 24H2 lub nowsza, wyłącznie
  • Ustaw MaxVersionTested wartość na 10.0.26100.0 , jak pokazano
  • Uwaga: funkcja AllowExternalContent użyta tutaj została wprowadzona w wersji Windows 10.0.19041.0. Jeśli aplikacja działa dalej w dół, należy przeprowadzić sprawdzanie wersji systemu operacyjnego w instalatorze i nie zarejestrować pakietu tożsamości w wersjach systemu operacyjnego starszych niż 10.0.19041.0. Zobacz Rejestrowanie pakietu tożsamości w instalatorze.
• Upewnij się, że runFullTrust i unvirtualizedResources możliwości są zadeklarowane zgodnie ze zgodnością z Win32.
• Application Dodaj element, jak pokazano dla każdego pliku wykonywalnego skojarzonego z aplikacją
  • Upewnij się TrustLevel jest mediumIL i RuntimeBehavior jest win32App zgodnie z przedstawionym dla zgodności z Win32
• Element VisualElements podrzędny jest wymagany, ale AppListEntry="none" atrybut zapewnia, że pakiet tożsamości nie jest wyświetlany wśród zainstalowanych aplikacji
  • Zaktualizuj atrybuty DisplayName i Description za pomocą odpowiednich szczegółów, a pozostałe atrybuty pozostaw bez zmian, jak pokazano (przywołane ścieżki obrazów nie muszą być rozpoznawane)
  • Zobacz Lokalizacje i zasoby wizualne , aby zapoznać się ze scenariuszami, w których lokalizacja i obrazy mogą być potrzebne tutaj.

Pakiet tożsamości utworzony na podstawie tego manifestu zostanie połączony z katalogiem instalacyjnym aplikacji podczas rejestrowania pakietu w późniejszym kroku.

Tworzenie i podpisywanie pakietu tożsamości

Po utworzeniu manifestu pakietu tożsamości skompiluj pakiet tożsamości przy użyciu narzędzia MakeAppx.exe w zestawie SDK Windows.

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

Uwaga: Flaga /nv jest wymagana do ominięcia weryfikacji przywoływanych ścieżek plików w manifeście.

Aby można je było zainstalować na komputerach użytkowników końcowych, pakiet tożsamości musi być podpisany przy użyciu certyfikatu zaufanego na komputerze docelowym. Możesz tworzeć nowy certyfikat z podpisem własnym do celów programistycznych i podpisać pakiet tożsamości przy użyciu SignTool, który jest dostępny w zestawie SDK Windows, ale certyfikat produkcyjny z działu IT lub usługi, takiej jak Azure Trusted Signing będzie wymagany do zarejestrowania pakietu na komputerach użytkowników końcowych.

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

$cert = Get-PfxCertificate -FilePath "<path>\MyCertificate.pfx"
Export-Certificate -Cert $cert -FilePath "<path>\MyCertificate.cer"
Import-Certificate -FilePath "<path>\MyCertificate.cer" `
    -CertStoreLocation Cert:\CurrentUser\TrustedPeople

Uwaga: Aby dowiedzieć się, jak skompilować i podpisać pakiet tożsamości w potoku CI/CD przy użyciu certyfikatów produkcyjnych, zobacz przykłady w MSIX i CI/CD Pipeline Overview.

Dodawanie metadanych tożsamości do manifestów aplikacji desktopowych

Łączysz pakiet tożsamości z plikami wykonywalnymi aplikacji, dołączając manifesty aplikacji (znane również jako manifesty równoległe lub manifesty łączenia) zawierające metadane, które odpowiadają metadanym z manifestu pakietu tożsamości.

W Visual Studio można dodać manifest application do project wykonywalnego, otwierając menu kontekstowe Project i wybierz Dodaj>Nowy element>Plik manifestu aplikacji.

Poniżej znajduje się przykładowy fragment manifestu aplikacji pokazujący element msix, który jest wymagany do połączenia binarek z metadanymi z pakietu tożsamości.

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

Atrybuty msix elementu muszą być zgodne z tymi wartościami z manifestu pakietu tożsamości:

• Atrybuty packageName i publisher muszą być zgodne odpowiednio z atrybutami Name i Publisher w elemfeście Identity w manifeście pakietu tożsamości
• Atrybut applicationId musi być zgodny z atrybutem Id odpowiedniego Application elementu w manifeście pakietu tożsamości

Zarejestruj pakiet tożsamości w instalatorze

Ostatnim krokiem do skojarzenia tożsamości z aplikacją jest zarejestrowanie pakietu tożsamości w instalatorze i skojarzenie go z katalogiem instalacyjnym aplikacji.

PowerShell

Wykonywanie powershell.exe z odpowiednimi parametrami jest najprostszym sposobem zarejestrowania pakietu. Wskazówki różnią się w przypadku instalacji poszczególnych użytkowników w porównaniu z instalacjami w całym komputerze.

Per-User (PowerShell)

Aby zarejestrować pakiet tożsamości podczas instalacji dla pojedynczego użytkownika:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Path <PackagePath> -ExternalLocation <ExternalLocation>"

• Ustaw <PackagePath> na ścieżkę bezwzględną podpisanego pakietu tożsamości utworzonego w poprzednim kroku (wraz z nazwą pliku).
• Ustaw <ExternalLocation> jako pełną ścieżkę do katalogu, w którym zainstalowana jest aplikacja (bez żadnych nazw plików wykonywalnych).

Aby usunąć rejestrację pakietu tożsamości podczas odinstalowywania dla poszczególnych użytkowników:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Get-AppxPackage <PackageName> | Remove-AppxPackage"

• Ustaw <PackageName> nazwę pakietu zdefiniowaną w manifeście pakietu tożsamości (atrybut Name elementu Identity )

Per-Machine (PowerShell)

Aby zarejestrować pakiet tożsamości podczas instalacji całej maszyny:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "Add-AppxPackage -Stage <PackagePath> -ExternalLocation <ExternalLocation>; Add-AppxProvisionedPackage -Online -PackagePath <PackagePath>"

• Ustaw <PackagePath> na ścieżkę bezwzględną podpisanego pakietu tożsamości utworzonego w poprzednim kroku (wraz z nazwą pliku).
• Ustaw <ExternalLocation> jako pełną ścieżkę do katalogu, w którym zainstalowana jest aplikacja (bez żadnych nazw plików wykonywalnych).

Aby wyrejestrować pakiet tożsamości podczas odinstalowywania całej maszyny:

powershell.exe -NoLogo -NoProfile -NonInteractive -WindowStyle Hidden -ExecutionPolicy Bypass -Command "$packages = Get-AppxPackage -AllUsers -Name <PackageName>; $provisioned = Get-AppxProvisionedPackage -Online | Where-Object { $_.DisplayName -eq '<PackageName>' }; foreach ($p in $provisioned) { Remove-AppxProvisionedPackage -PackageName $p.PackageName -Online }; foreach ($package in $packages) { Remove-AppxPackage -Package $package.PackageFullName -AllUsers }"

• Ustaw <PackageName> nazwę pakietu zdefiniowaną w manifeście pakietu tożsamości (atrybut Name elementu Identity )

Interfejsy API narzędzia PackageManager

Jeśli wolisz wywołać interfejsy API systemu operacyjnego w celu zarejestrowania i wyrejestrowania pakietu tożsamości, interfejs API PackageManager zapewnia równoważne funkcje programu PowerShell. Wskazówki różnią się w przypadku instalacji poszczególnych użytkowników w porównaniu z instalacjami w całym komputerze.

Poniżej przedstawiono fragmenty kodu, które demonstrują interfejs API. Aby uzyskać kod gotowy do produkcji w językach C# i C++, zobacz Przykładowe aplikacje.

Dla użytkownika (Menedżer pakietów)

Poniższy kod przedstawia rejestrowanie pakietu tożsamości przy użyciu metody AddPackageByUriAsync i wyrejestrowywanie pakietu tożsamości przy użyciu metody 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;

var result = await packageManager.AddPackageByUriAsync(packageUri, options);
if (result.ExtendedErrorCode != 0)
{
    throw new Exception($"Package registration failed: {result.ErrorText} (0x{result.ExtendedErrorCode:X8})");
}

...

// Unregister the identity package during uninstall

var packageManager = new PackageManager();
var packages = packageManager.FindPackagesForUserWithPackageTypes("", "<IdentityPackageFamilyName>", PackageTypes.Main);
foreach (var package in packages)
{
  await packageManager.RemovePackageAsync(package.Id.FullName);
}

Zwróć uwagę na poniższe ważne szczegóły dotyczące tego kodu:

• Ustaw externalLocation na ścieżkę bezwzględną katalogu instalacyjnego aplikacji (bez żadnych nazw wykonywalnych). new Uri(somePath) tworzy file:/// identyfikator URI zgodnie z wymaganiami interfejsu API.
• Ustaw packagePathścieżkę bezwzględną podpisanego pakietu tożsamości utworzonego w poprzednim kroku (z nazwą pliku)
• Można znaleźć <IdentityPackageFamilyName> uruchamiając polecenie Get-AppxPackage <IdentityPackageName> w programie PowerShell na systemie, w którym pakiet tożsamości jest zarejestrowany. Właściwość PackageFamilyName zawiera wartość, która ma być używana tutaj.
• Sprawdź result.ExtendedErrorCode po rejestracji, aby wyświetlić szczegóły błędu, które można naprawić. Zobacz Rozwiązywanie problemów dotyczące typowych kodów błędów.

Per-Machine (PackageManager)

Poniższy kod przedstawia rejestrowanie pakietu tożsamości przy użyciu metod StagePackageByUriAsync i ProvisionPackageForAllUsersAsync oraz wyrejestrowywania pakietu tożsamości przy użyciu metod DeprovisionPackageForAllUsersAsync i 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);
var packageFamilyName = "<IdentityPackageFamilyName>";
await packageManager.ProvisionPackageForAllUsersAsync(packageFamilyName);

...

// Unregister the identity package during uninstall

var packageManager = new PackageManager();

var packages = packageManager.FindPackagesForUserWithPackageTypes("", "<IdentityPackageFamilyName>", PackageTypes.Main);
foreach (var package in packages)
{
  await packageManager.DeprovisionPackageForAllUsersAsync(package.Id.FullName);
  await packageManager.RemovePackageAsync(package.Id.FullName, RemovalOptions.RemoveForAllUsers);
}

Zwróć uwagę na poniższe ważne szczegóły dotyczące tego kodu:

• Ustaw externalLocation na ścieżkę bezwzględną folderu instalacyjnego aplikacji (bez żadnych nazw wykonywalnych)
• Ustaw wartość packagePath na ścieżkę bezwzględną podpisanego pakietu tożsamości utworzonego w poprzednim kroku wraz z nazwą pliku.
• Można znaleźć <IdentityPackageFamilyName> uruchamiając polecenie Get-AppxPackage <IdentityPackageName> w programie PowerShell na systemie, w którym pakiet tożsamości jest zarejestrowany. Właściwość PackageFamilyName zawiera wartość, która ma być używana tutaj.

Troubleshooting

W poniższej tabeli wymieniono najczęstsze błędy podczas rejestrowania pakietu tożsamości i sposoby ich naprawiania.

Przykładowe aplikacje

Zobacz przykłady packageWithExternalLocation , aby zapoznać się z w pełni funkcjonalnymi aplikacjami języka C# i C++, które pokazują, jak zarejestrować i wyrejestrować pakiet tożsamości.

Kroki opcjonalne

Lokalizacja i zasoby wizualne

Niektóre funkcje, które rozumieją tożsamość pakietu, mogą powodować wyświetlanie ciągów i obrazów z manifestu pakietu tożsamości w systemie operacyjnym Windows. Przykład:

• Aplikacja korzystająca z interfejsów API aparatu, mikrofonu lub lokalizacji będzie miała dedykowany przełącznik w ustawieniach prywatności Windows, wraz z monitem o pośrednictwie zgody, którego użytkownicy mogą używać do zezwalania lub odmowy dostępu do tych poufnych zasobów.
• Aplikacja, która rejestruje docelowy punkt udostępniania, zostanie wyświetlona w oknie udostępniania.

Aby zlokalizować ciągi w manifeście pakietu tożsamości, zobacz Lokalizowanie manifestu.

W przypadku podawania ścieżek do obrazów w atrybutach VisualElements manifestu pakietu tożsamości, podane ścieżki powinny być ścieżkami względnymi w katalogu instalacyjnym aplikacji, które rozpoznawane są jako obrazy w formacie .png, .jpglub .jpeg. Nazwy atrybutów wskazują oczekiwane wymiary obrazów (150x150 i 40x40).