Pacchetti facoltativi e creazione di set correlati

  • Articolo

I pacchetti facoltativi includono contenuto che può essere integrato con un pacchetto principale. Questi sono utili per il contenuto scaricabile (DLC), dividendo un'app di grandi dimensioni per restrizioni di dimensioni o per la spedizione di qualsiasi contenuto aggiuntivo separato dalla tua app originale. Per altre informazioni sui pacchetti facoltativi, vedere post di blog: Estendere l'applicazione usando pacchetti facoltativi.

I set correlati sono un'estensione di pacchetti facoltativi. I set correlati consentono di applicare un set rigoroso di versioni in pacchetti principali e facoltativi. I set correlati possono avere autori diversi dall'app principale se vengono distribuiti all'esterno dello Store. Per altre informazioni sui set correlati, vedere Post di blog: Strumenti per creare un set correlato.

Pacchetti facoltativi e set correlati vengono eseguiti tutti all'interno del contenitore MSIX dell'app principale.

Prerequisiti

  • Visual Studio 2019 o Visual Studio 2017 (versione 15.1 o successiva)
  • Windows 10, versione 1703 o successiva
  • Windows 10, versione 1703 SDK o successiva

Per ottenere tutti gli strumenti di sviluppo più recenti, vedi Download e strumenti per Windows 10.

Nota

Per inviare un'app che usa pacchetti facoltativi e/o set correlati a Microsoft Store, è necessaria l'autorizzazione. I pacchetti facoltativi e i set correlati possono essere usati per le app line-of-business (LOB) o aziendali senza l'autorizzazione del Centro per i partner se non vengono inviate allo Store. Vedi Supporto per sviluppatori Windows per ottenere l'autorizzazione per inviare un'app che usa pacchetti facoltativi e set correlati.

Esempio di codice

Durante la lettura di questo articolo, è consigliabile seguire l'esempio di codice del pacchetto facoltativo in GitHub per una comprensione pratica del funzionamento dei pacchetti facoltativi e dei set correlati in Visual Studio.

Pacchetti facoltativi

Per creare un pacchetto facoltativo in Visual Studio, è necessario:

  1. Assicurarsi che la versione minima della piattaforma di destinazione dell'app sia impostata su: 10.0.15063.0 o versione successiva.
  2. Dal progetto di pacchetto principale aprire il Package.appxmanifest file. Passare alla scheda "Creazione pacchetti" e prendere nota del nome della famiglia di pacchetti, ovvero tutto prima del carattere "_".
  3. Dal progetto di pacchetto facoltativo fare clic con il pulsante destro del Package.appxmanifest mouse e scegliere Apri con > editor XML (testo).
  4. Individua l'elemento <Dependencies> nel file. Aggiungere quanto segue e sostituire [MainPackageDependency] con il nome della famiglia di pacchetti del passaggio 2. In questo modo si specifica che il pacchetto facoltativo dipende dal pacchetto principale. 
    <uap3:MainPackageDependency Name="[MainPackageDependency]"/>

Nota

Se si vuole creare un pacchetto facoltativo da un server di pubblicazione diverso, sarà necessario specificare l'autore dell'applicazione principale se sono diversi. Analogamente a uap4 <:MainPackageDependency Name="Main_app" Publisher="CN=Contoso..." />. Questo non funzionerà se stai pubblicando nello Store.

Dopo aver configurato le dipendenze dei pacchetti dai passaggi da 1 a 4, è possibile continuare a sviluppare come normalmente. Per altre informazioni, vedere Post di blog: Compilare il primo pacchetto facoltativo.

Visual Studio può essere configurato per ridribuire il pacchetto principale ogni volta che si distribuisce un pacchetto facoltativo. Per impostare la dipendenza di compilazione in Visual Studio, è necessario:

  1. Fare clic con il pulsante destro del mouse sul progetto di pacchetto facoltativo e selezionare Compila dipendenze progetto dipendenze > ...
  2. Controllare il progetto di pacchetto principale e selezionare "OK".

A questo punto, ogni volta che si immette F5 o si compila un progetto di pacchetto facoltativo, Visual Studio compilerà prima il progetto di pacchetto principale. In questo modo si garantisce che il progetto principale e i progetti facoltativi siano sincronizzati.

Un set correlato è costituito da un pacchetto principale e da un pacchetto facoltativo strettamente accoppiato tramite metadati specificati nel file con estensione appxbundle o msixbundle del pacchetto principale. Questi metadati collega il pacchetto principale al pacchetto facoltativo (usando il nome del file con estensione appxbundle + versione) e il pacchetto facoltativo al pacchetto principale (usando il nome indipendente dalla versione). Visual Studio consente di ottenere i metadati corretti nei file.

Il controllo delle versioni dei pacchetti in un set correlato viene sincronizzato in modo che non consenta l'uso della versione più recente di alcun pacchetto fino a quando non vengono installati tutti i pacchetti set correlati (specificati dalla versione nel pacchetto principale). I pacchetti vengono gestiti in modo indipendente, ma i pacchetti specificati nel set potrebbero non essere utilizzati fino a quando non vengono aggiornati tutti. Per altre informazioni sui set correlati, vedere Post di blog: Strumenti per creare un set correlato.

Per configurare la soluzione dell'app per i set correlati, seguire questa procedura:

  1. Fare clic con il pulsante destro del mouse sul progetto di pacchetto principale, selezionare Aggiungi > nuovo elemento...
  2. Nella finestra cercare ".txt" nei modelli installati e aggiungere un nuovo file di testo.

    Importante

    Il nuovo file di testo deve essere denominato : Bundle.Mapping.txt.

  3. Bundle.Mapping.txt Nel file immettere la stringa "[OptionalProjects]" seguita dai percorsi relativi ai progetti di pacchetto facoltativi. Ecco un file di esempio Bundle.Mapping.txt : 
    [OptionalProjects]
"..\ActivatableOptionalPackage1\ActivatableOptionalPackage1.vcxproj"
"..\ActivatableOptionalPackage2\ActivatableOptionalPackage2.vcxproj"

Quando la soluzione è configurata in questo modo, Visual Studio creerà un manifesto del bundle denominato AppxBundleManifest.xml per il pacchetto principale con tutti i metadati necessari per i set correlati.

Si noti che, come i pacchetti facoltativi, un Bundle.Mapping.txt file per i set correlati funzionerà solo in Windows 10 versione 1703 o successiva. Inoltre, la versione minima della piattaforma di destinazione dell'app deve essere impostata su 10.0.15063.0 o versione successiva.

Rimozione di pacchetti facoltativi

Gli utenti possono accedere all'app Impostazioni e rimuovere i pacchetti facoltativi. Analogamente, gli sviluppatori possono usare RemoveOptionalPackageAsync per rimuovere un elenco di pacchetti facoltativi.

PackageCatalog catalog = PackageCatalog.OpenForCurrentPackage();
List<string> optionalList = new List<string>();
optionalList.Add("FabrikamAgeAnalysis_kwpnjs8c36mz0");
    
// Warn user that application will be restarted. 
var result = await catalog.RemoveOptionalPackagesAsync(optionalList);
if (result.ExtendedError != null)
{
    throw removalResult.ExtendedError;
}

Nota

Nel caso di un set correlato, la piattaforma dovrà riavviare l'applicazione principale per finalizzare la rimozione per evitare situazioni in cui l'app dispone di contenuto caricato dal pacchetto che viene rimosso. Le app devono notificare agli utenti che l'applicazione dovrà essere riavviata prima che l'app chiami l'API.

Se il pacchetto facoltativo è solo contenuto, lo sviluppatore deve indicare in modo esplicito alla piattaforma che il pacchetto che sta per rimuovere è "non in uso" dall'applicazione prima che lo sviluppatore rimuova il pacchetto facoltativo. In questo modo lo sviluppatore può anche rimuovere il pacchetto senza riavviare.

Problemi noti

Il debug di un progetto facoltativo del set correlato non è attualmente supportato in Visual Studio. Per risolvere questo problema, è possibile distribuire e avviare l'attivazione (CTRL+ F5) e collegare manualmente il debugger a un processo. Per collegare il debugger, passare al menu "Debug" in Visual Studio, selezionare "Collega a processo..." e collegare il debugger al processo principale dell'app.