Udostępnij za pośrednictwem

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

Aby uzyskać motywacje dotyczące dodawania tożsamości pakietu, a także różnic między tworzeniem pakietów tożsamości w programie Visual Studio i tworzeniem ich ręcznie, zobacz Omówienie.

W tym temacie opisano sposób ręcznego kompilowania i rejestrowania pakietu tożsamości. Aby uzyskać informacje o tworzeniu pakietu identyfikacji w programie Visual Studio, zobacz Nadawanie tożsamości pakietu za pomocą lokalizacji zewnętrznej w programie 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 odpowiadać Subject certyfikatowi użytemu 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:
    • Ustaw MinVersion na 10.0.19041.0 zgodnie z pokazanymi ustawieniami dla maksymalnego zasięgu i jednolitości w wersjach systemu operacyjnego Windows 10 i Windows 11
    • Ustaw MinVersion na 10.0.26100.0, aby ograniczyć pakiet tożsamości do Windows 11 w wersji 24H2 lub nowszej.
    • Ustaw MaxVersionTested wartość na 10.0.26100.0 , jak pokazano
    • Uwaga: funkcja użyta AllowExternalContent tutaj została wprowadzona w kompilacji systemu 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ędziaMakeAppx.exe w zestawie WINDOWS SDK.

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 utworzyć nowy certyfikat z podpisem własnym na potrzeby programowania i podpisać pakiet tożsamości przy użyciu narzędzia SignTool, który jest dostępny w zestawie SDK systemu Windows, ale certyfikat produkcyjny z działu IT lub usługi, takiej jak Zaufane podpisywanie platformy Azure , 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

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 programie Visual Studio można dodać manifest aplikacji do projektu wykonywalnego, otwierając menu kontekstowe projektu i wybierając pozycję Dodaj>nowy 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:

  • Odpowiednie atrybuty packageName i publisher muszą być zgodne z atrybutami Name i Publisher w elemencie 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 pełną ścieżkę podpisanego pakietu tożsamości, który został utworzony 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 <PackageName>; foreach ($package in $packages) { Remove-AppxProvisionedPackage -PackageName $package.PackageFullName -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.

Per-User (PackageManager)

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;

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);
}

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.

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);
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);
}

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)
  • Określ packagePath ścieżkę bezwzględną podpisanego pakietu identyfikacji utworzonego w poprzednim kroku, włącznie z nazwą pliku
  • Element <IdentityPackageFamilyName> można znaleźć, uruchamiając komendę Get-AppxPackage <IdentityPackageName> PowerShell w systemie, w którym zarejestrowano pakiet tożsamości. Właściwość PackageFamilyName zawiera wartość, która ma być używana tutaj.

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 API aparatu, mikrofonu lub lokalizacji będzie mieć dedykowany przełącznik kontrolny w ustawieniach prywatności systemu Windows, wraz z monitem o wyrażenie zgody zarządzanym przez brokera, który umożliwia użytkownikom udzielanie lub odmowę 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).