Pacchetti facoltativi e creazione di set correlati

I pacchetti facoltativi includono contenuto che può essere integrato con un pacchetto principale. Sono utili per il contenuto scaricabile( DLC), la divisione di un'app di grandi dimensioni per i vincoli di dimensioni o per la spedizione di qualsiasi contenuto aggiuntivo separato dall'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 tra i pacchetti principali e facoltativi. I set correlati possono avere editori diversi dall'app principale se viene distribuito all'esterno dello Store. Per altre informazioni sui set correlati, vedere Post di blog: Strumenti per creare un set correlato.

I pacchetti facoltativi e i set correlati vengono tutti eseguiti 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, vedere Download e strumenti per Windows 10.

Nota

Per inviare un'app che usa pacchetti facoltativi e/o set correlati al 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 Partner Center se non vengono inviati allo Store. Vedere Windows per gli sviluppatori 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 insieme all'esempio di codice del pacchetto facoltativo in GitHub per una comprensione approfondita del funzionamento dei pacchetti facoltativi e dei set correlati all'interno di 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. Aprire il file dal progetto del Package.appxmanifest pacchetto principale. Passare alla scheda "Packaging" (Creazione pacchetti) e prendere nota del nome della famiglia di pacchetti, che è tutto prima del carattere "_".
  3. Nel progetto di pacchetto facoltativo fare clic con il pulsante destro del mouse su Package.appxmanifest e 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, è necessario specificare l'autore dell'applicazione principale se sono diversi. Analogamente, <uap4:MainPackageDependency Name="Main_app" Publisher="CN=Contoso..." />. Questa operazione non funzionerà se si sta pubblicando in Store.

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

Visual Studio possibile configurare per ridistribuire 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 scegliere Compila > Project dipendenze...
  2. Controllare il progetto del pacchetto principale e selezionare "OK".

A questo punto, ogni volta che si immette F5 o si compila un progetto di pacchetto facoltativo, Visual Studio 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 associati tramite metadati specificati nel file con estensione appxbundle o msixbundle del pacchetto principale. Questi metadati collegano 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 da non consentire l'uso della versione più recente di qualsiasi pacchetto fino a quando non vengono installati tutti i pacchetti di set correlati (specificati dalla versione nel pacchetto principale). I pacchetti vengono usati in modo indipendente, ma i pacchetti specificati nel set non possono essere usati fino a quando non sono stati 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 del pacchetto principale, scegliere Aggiungi > nuovo elemento...
  2. Nella finestra cercare ".txt" in Modelli installati e aggiungere un nuovo file di testo.

    Importante

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

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

Quando la soluzione viene configurata in questo modo, Visual Studio 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 file per i set correlati funzionerà solo Windows 10 Bundle.Mapping.txt 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 include 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 essere rimosso non è in uso dall'applicazione prima che lo sviluppatore rimova il pacchetto facoltativo. In questo modo lo sviluppatore può anche rimuovere il pacchetto senza un riavvio.

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 dell'app principale.