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 pacchetti di dimensioni ridotte o per la spedizione di qualsiasi contenuto aggiuntivo separato dall'app originale. Per altre informazioni sui pacchetti facoltativi, vedere il 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 distribuita all'esterno dello Store. Per altre informazioni sui set correlati, vedere il post di blog Sugli 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 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 l'esempio di codice del pacchetto facoltativo in GitHub per comprendere il funzionamento dei pacchetti facoltativi e dei set correlati all'interno di Visual Studio.

Pacchetti facoltativi

Per creare un pacchetto facoltativo 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 di pacchetto Package.appxmanifest principale. Passare alla scheda "Packaging" (Creazione pacchetti) e prendere nota del nome della famiglia di pacchetti, ovvero tutti gli elementi prima del carattere "_".
  3. Nel progetto di pacchetto facoltativo fare clic con il pulsante destro del Package.appxmanifest mouse su e > Apri con editor XML (testo).
  4. Individua l'elemento <Dependencies> nel file. Aggiungere quanto segue e sostituire con il [MainPackageDependency] 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 desidera creare un pacchetto facoltativo da un editore diverso, è necessario specificare l'autore dell'applicazione principale se sono diversi. Come per <uap4:MainPackageDependency Name="Main_app" Publisher="CN=Contoso..." />. Questa operazione non funziona se si pubblica in Store.

Dopo aver configurato le dipendenze dei pacchetti dai passaggi 1 a 4, è possibile continuare a sviluppare come di consueto. Per altre informazioni, vedere il post di blog: Build your first optional package (Creare 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 Project 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 compila prima il progetto di pacchetto principale. Ciò garantisce che il progetto principale e i progetti facoltativi siano sincronizzati.

Un set correlato è costituito da un pacchetto principale e 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 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 set correlati (specificati dalla versione nel pacchetto principale). I pacchetti vengono usati in modo indipendente, ma i pacchetti specificati nel set potrebbero non essere usati fino a quando non sono stati aggiornati tutti. Per altre informazioni sui set correlati, vedere il post di blog Sugli 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 e 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. Bundle.Mapping.txt Nel file immettere la stringa "[OptionalProjects]" seguita dai percorsi relativi dei 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 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, Bundle.Mapping.txt un 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 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 riavviarlo.

Problemi noti

Il debug di un progetto facoltativo 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.