Assegnare l'identità del pacchetto tramite impacchettamento con localizzazione esterna

Articolo
2025-04-30

Molte funzionalità di Windows possono essere usate da un'app desktop solo se l'app dispone dell'identità del pacchetto in fase di esecuzione. Vedere Funzionalità che richiedono l'identità del pacchetto. Se si dispone di un'app desktop esistente, con il proprio programma di installazione, c'è molto poco da cambiare per trarre vantaggio dall'identità del pacchetto.

A partire da Windows 10, versione 2004, puoi concedere l'identità del pacchetto a un'app semplicemente compilando e registrando un pacchetto con posizione esterna con la tua app. La creazione di pacchetti con posizione esterna consente di registrare un pacchetto di identità semplice nel programma di installazione esistente senza modificare la modalità o la posizione in cui si installa l'applicazione. Se hai familiarità con i pacchetti MSIX completi, questa è un'opzione molto più leggera, come descritto di seguito.

Per compilare e registrare un pacchetto di identità, seguire questa procedura:

Creare un manifesto del pacchetto per il pacchetto identity
Compilare e firmare il pacchetto di identità
Aggiungere metadati di identità ai manifesti dell'applicazione desktop
Registrare il pacchetto di identità nel programma di installazione

Creare un manifesto del pacchetto per il pacchetto identity

Il primo passaggio per creare un pacchetto identity consiste nel creare un manifesto del pacchetto basato sul modello seguente. Si tratta di un manifesto MSIX, ma viene usato solo per l'identità e non modifica il comportamento di runtime dell'app.

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

Si notino i dettagli importanti seguenti su questo manifesto:

Compilare gli attributi dell'elemento Identity con i dettagli dell'applicazione
- Publisher deve corrispondere al Subject del certificato usato per firmare l'applicazione
Riempire gli elementi DisplayName e PublisherDisplayName con i dettagli della tua applicazione
- A meno che non si aggiungono funzionalità aggiuntive al manifesto oltre alla semplice identità, questi valori non vengono visualizzati ovunque
Aggiornare l'elemento Logo a un percorso relativo all'interno della directory di installazione dell'applicazione in modo che si risolva in un'immagine in formato .png, .jpgo .jpeg
Assicurarsi che l'elemento AllowExternalContent sia impostato su true come illustrato, che consente di riutilizzare il programma di installazione esistente
Impostare TargetDeviceFamilyMinVersion e MaxVersionTested come indicato di seguito:
- Impostare MinVersion su 10.0.19041.0 come illustrato per la massima omogeneità nelle versioni del sistema operativo Windows 10 e Windows 11
- Imposta MinVersion a 10.0.26100.0 per limitare il pacchetto di identità a versioni di Windows 11, versione 24H2 e successive
- Imposta MaxVersionTested su 10.0.26100.0 come illustrato
Verificare che le funzionalità runFullTrust e unvirtualizedResources siano dichiarate come illustrato per la compatibilità Win32
Aggiungere un Application elemento come illustrato per ogni eseguibile associato all'applicazione
- Assicurarsi che TrustLevel sia mediumIL e che RuntimeBehavior sia win32App come mostrato per la compatibilità Win32
L'elemento VisualElements figlio è obbligatorio, ma l'attributo AppListEntry="none" garantisce che il pacchetto di identità non venga visualizzato tra le app installate
- Aggiornare gli attributi DisplayName e Description con i dettagli pertinenti e lasciare gli altri attributi come illustrato (non è necessario risolvere i percorsi di immagine a cui si fa riferimento)

Il pacchetto di identità creato da questo manifesto verrà connesso alla directory di installazione dell'applicazione quando si registra il pacchetto in un passaggio successivo.

Compilare e firmare il pacchetto di identità

Dopo aver creato il manifesto del pacchetto di identità, crea il pacchetto di identità usando lo strumentoMakeAppx.exe nel Windows SDK.

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

Nota: il /nv flag è necessario per ignorare la convalida dei percorsi di file a cui si fa riferimento nel manifesto.

Per essere installato nei computer degli utenti finali, il pacchetto di identità deve essere firmato con un certificato attendibile nel computer di destinazione. È possibile creare un nuovo certificato autofirmato a scopo di sviluppo e firmare il pacchetto di identità usando SignTool, disponibile in Windows SDK, ma sarà necessario registrare il pacchetto nei computer degli utenti finali un certificato di produzione di un reparto IT o un servizio come Firma attendibile di Azure .

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

Nota: per informazioni su come compilare e firmare il pacchetto di identità all'interno di una pipeline CI/CD con certificati di produzione, vedere la panoramica della pipeline MSIX e CI/CD per esempi.

Aggiungere metadati di identità ai manifesti dell'applicazione desktop

È possibile connettere il pacchetto di identità con i file eseguibili dell'applicazione includendo manifesti dell'applicazione (ad esempio manifesti side-by-side o fusion) con metadati corrispondenti ai metadati del manifesto del pacchetto di identità.

In Visual Studio è possibile aggiungere un manifesto dell'applicazione a un progetto eseguibile aprendo il menu di scelta rapida Progetto e selezionando Aggiungi>nuovo>file manifesto dell'applicazione.

Di seguito è riportato un frammento di manifesto dell'applicazione di esempio che illustra l'elemento msix necessario per connettere i file binari con i metadati del pacchetto identity.

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

Gli attributi dell'elemento msix devono corrispondere a questi valori dal manifesto del pacchetto di identità:

Gli attributi packageName e publisher devono corrispondere rispettivamente agli attributi Name e Publisher nell'elemento nel manifesto del pacchetto di identità Identity.
L'attributo applicationId deve corrispondere all'attributo Id dell'elemento corrispondente Application nel manifesto del pacchetto di identità

Registrare il pacchetto di identità nel programma di installazione

L'ultimo passaggio per associare l'identità all'applicazione consiste nel registrare il pacchetto di identità nel programma di installazione e associarlo alla directory di installazione dell'applicazione.

Il frammento di codice seguente illustra l'uso del PackageManager.AddPackageByUriAsync metodo per registrare il pacchetto identity.

using Windows.Management.Deployment;

...

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

Si notino i dettagli importanti seguenti su questo codice:

Impostare externalLocation sul percorso assoluto della directory di installazione dell'applicazione (senza nomi eseguibili)
Impostare packagePath sul percorso assoluto del pacchetto di identità prodotto nel passaggio precedente (con il nome del file)

Per il codice pronto all'uso in produzione in C# e C++, vedere le applicazioni di esempio seguenti. Gli esempi illustrano anche come annullare la registrazione del pacchetto identity durante la disinstallazione.

App di esempio

Vedere gli esempi packageWithExternalLocation per app C# e C++ completamente funzionali che illustrano come registrare un pacchetto di identità.

Condividi tramite