Pacchetti facoltativi e creazione di set correlatiOptional packages and related set authoring

I pacchetti facoltativi includono contenuto che può essere integrato con un pacchetto principale.Optional packages contain content that can be integrated with a main package. Sono utili per contenuti scaricabili (DLC), per dividere un'app di grandi dimensioni per i vincoli di dimensione o per la distribuzione di qualsiasi contenuto aggiuntivo separato dall'app originale.These are useful for downloadable content (DLC), dividing a large app for size restraints, or for shipping any additional content separate from your original app. Per altre informazioni sui pacchetti facoltativi, vedere il post di Blog relativo all'estensione dell'applicazione con i pacchetti facoltativi.For more information about optional packages, see Blog post: Extend your application using optional packages.

I set correlati sono un'estensione dei pacchetti facoltativi.Related sets are an extension of optional packages. I set correlati consentono di applicare un set di versioni rigorose nei pacchetti principali e facoltativi.Related sets allow you to enforce a strict set of versions across main and optional packages. I set correlati possono avere Publisher diversi dall'app principale se vengono distribuiti all'esterno dell'archivio.Related sets can have different publishers from the main app if it is deployed outside of the Store. Per ulteriori informazioni sui set correlati, vedere il post di Blog relativo agli strumenti per creare un set correlato.For more information about related sets, see Blog post: Tooling to create a related set.

I pacchetti facoltativi e i set correlati vengono eseguiti tutti all'interno del contenitore MSIX dell'applicazione principale.Optional packages and related sets all run inside the main app's MSIX container.

PrerequisitiPrerequisites

  • Visual Studio 2019 o Visual Studio 2017 (versione 15,1 o successiva)Visual Studio 2019 or Visual Studio 2017 (version 15.1 or later)
  • Windows 10, versione 1703 o successivaWindows 10, version 1703 or later
  • Windows 10, versione 1703 SDK o versione successivaWindows 10, version 1703 SDK or later

Per ottenere tutti gli strumenti di sviluppo più recenti, vedere download e strumenti per Windows 10.To get all of the latest development tools, see Downloads and tools for Windows 10.

Nota

Per inviare all'Microsoft Store un'app che usa pacchetti facoltativi e/o set correlati, sarà necessaria l'autorizzazione.To submit an app that uses optional packages and/or related sets to the Microsoft Store, you will need permission. I pacchetti facoltativi e i set correlati possono essere usati per le app line-of-business (LOB) o aziendali senza autorizzazione del centro per i partner se non vengono inviati all'archivio.Optional packages and related sets can be used for Line of Business (LOB) or enterprise apps without Partner Center permission if they are not submitted to the Store. Vedere supporto per sviluppatori Windows per ottenere l'autorizzazione per inviare un'app che usa pacchetti facoltativi e set correlati.See Windows developer support to get permission to submit an app that uses optional packages and related sets.

Esempio di codiceCode sample

Durante la lettura di questo articolo, è consigliabile seguire l' esempio di codice di pacchetto facoltativo su GitHub per una conoscenza pratica del funzionamento di pacchetti facoltativi e set correlati in Visual Studio.While you're reading this article, it's recommended that you follow along with the optional package code sample on GitHub for a hands-on understanding of how optional packages and related sets work within Visual Studio.

Pacchetti facoltativiOptional packages

Per creare un pacchetto facoltativo in Visual Studio, è necessario:To create an optional package in Visual Studio, you'll need to:

  1. Verificare che la versione minima della piattaforma di destinazione dell'app sia impostata su: 10.0.15063.0 o superiore.Make sure your app's Target Platform Min Version is set to: 10.0.15063.0 or higher.
  2. Dal progetto di pacchetto principale aprire il Package.appxmanifest file.From your main package project, open the Package.appxmanifest file. Passare alla scheda "packaging" e prendere nota del nome della famiglia di pacchetti, che corrisponde a tutti gli elementi prima del carattere "".Navigate to the "Packaging" tab and make a note of your package family name, which is everything before the "" character.
  3. Dal progetto di pacchetto facoltativo , fare clic con il pulsante destro del mouse su Package.appxmanifest e scegliere Apri con > editor XML (testo).From your optional package project, right click the Package.appxmanifest and select Open with > XML (Text) Editor.
  4. Individua l'elemento <Dependencies> nel file.Locate the <Dependencies> element in the file. Aggiungere quanto segue e sostituire [MainPackageDependency] con il nome della famiglia di pacchetti dal passaggio 2.Add the following, and replace [MainPackageDependency] with your package family name from Step 2. Ciò consente di specificare che il pacchetto facoltativo dipende dal pacchetto principale.This will specify that your optional package is dependent on your main package.
    <uap3:MainPackageDependency Name="[MainPackageDependency]"/>
    

Una volta configurate le dipendenze dei pacchetti dai passaggi da 1 a 4, è possibile continuare a sviluppare normalmente.After you have your package dependencies set up from Steps 1 through 4, you can continue developing as you normally would. Per altre informazioni, vedere il post di Blog: compilare il primo pacchetto facoltativo.For more information, see Blog post: Build your first optional package.

È possibile configurare Visual Studio per ridistribuire il pacchetto principale ogni volta che si distribuisce un pacchetto facoltativo.Visual Studio can be configured to re-deploy your main package each time you deploy an optional package. Per impostare la dipendenza di compilazione in Visual Studio, è necessario:To set the build dependency in Visual Studio, you should:

  1. Fare clic con il pulsante destro del mouse sul progetto di pacchetto facoltativo e selezionare dipendenze di compilazione > dipendenze progetto.Right click the optional package project and select Build Dependencies > Project Dependencies...
  2. Controllare il progetto di pacchetto principale e selezionare "OK".Check the main package project and select "OK".

A questo punto, ogni volta che si immette F5 o si compila un progetto di pacchetto facoltativo, in Visual Studio verrà compilato prima il progetto di pacchetto principale.Now, every time you enter F5 or build an optional package project, Visual Studio will build the main package project first. In questo modo si garantisce che il progetto principale e i progetti facoltativi siano sincronizzati.This will ensure that your main project and optional projects are in sync.

Un set correlato è costituito da un pacchetto principale e da un pacchetto facoltativo strettamente accoppiato tramite i metadati specificati nel file con estensione appxbundle o msixbundle del pacchetto principale.A related set consists of a main package and an optional package that are tightly coupled via metadata that is specified in the .appxbundle or .msixbundle file of the main package. Questi metadati collegano il pacchetto principale al pacchetto facoltativo (usando il nome del file con estensione appxbundle + Version) e il pacchetto facoltativo al pacchetto principale (usando il nome indipendente dalla versione).This metadata links the main package to the optional package (using the name of the .appxbundle file + version), and the optional package to the main package (using the version independent name). Visual Studio consente di ottenere i metadati corretti nei file.Visual Studio helps you get the correct metadata in your files.

Il controllo delle versioni dei pacchetti in un set correlato viene sincronizzato in modo da non consentire l'utilizzo della versione più recente di un pacchetto finché non vengono installati tutti i pacchetti set correlati (specificati dalla versione nel pacchetto principale).The versioning of packages in a related set is synchronized in a way that won't allow the latest version of any package to be used until all of the related set packages (specified by version in the main package) are installed. I pacchetti vengono serviti in modo indipendente, ma i pacchetti specificati nel set non possono essere usati fino a quando non sono stati aggiornati tutti.Packages are serviced independently, but packages specified in the set may not be used until all of them have been updated. Per ulteriori informazioni sui set correlati, vedere il post di Blog relativo agli strumenti per creare un set correlato.For more information about related sets, see Blog post: Tooling to create a related set.

Per configurare la soluzione dell'app per i set correlati, seguire questa procedura:To configure your app's solution for related sets, use the following steps:

  1. Fare clic con il pulsante destro del mouse sul progetto di pacchetto principale, scegliere aggiungi > nuovo elemento...Right click the main package project, select Add > New Item...
  2. Dalla finestra, cercare ". txt" nei modelli installati e aggiungere un nuovo file di testo.From the window, search the Installed Templates for ".txt" and add a new text file.

    Importante

    Il nuovo file di testo deve essere denominato: Bundle.Mapping.txt .The new text file must be named: Bundle.Mapping.txt.

  3. Nel Bundle.Mapping.txt file immettere la stringa "[OptionalProjects]" seguita dai percorsi relativi dei progetti di pacchetto facoltativi.In the Bundle.Mapping.txt file enter the string "[OptionalProjects]" followed by the relative paths to your optional package projects. Ecco un file Bundle.Mapping.txt di esempio:Here is an example Bundle.Mapping.txt file:
    [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.When your solution is configured this way, Visual Studio will create a bundle manifest named AppxBundleManifest.xml for the main package with all of the required metadata for related sets.

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.Note that like optional packages, a Bundle.Mapping.txt file for related sets will only work on Windows 10, version 1703 or higher. Inoltre, la versione minima della piattaforma di destinazione dell'app deve essere impostata su 10.0.15063.0 o su un valore superiore.Additionally, your app's Target Platform Min Version should be set to 10.0.15063.0 or higher.

Rimozione di pacchetti facoltativiRemoving Optional Packages

Gli utenti possono accedere all'app Impostazioni e rimuovere i pacchetti facoltativi.Users can go into their Settings app and remove the optional packages. Analogamente, gli sviluppatori possono utilizzare RemoveOptionalPackageAsync per rimuovere un elenco di pacchetti facoltativi.Similarly, developers can use the RemoveOptionalPackageAsync to remove a list of optional packages.

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, in modo da evitare situazioni in cui l'app dispone di contenuto caricato dal pacchetto da rimuovere.In the case of a related set the platform will need to restart the main application to finalize the removal to avoid situations where the app has content that is loaded from the package that is being removed. Le app devono notificare agli utenti che l'applicazione deve essere riavviata prima che l'app chiami l'API.The apps must notify the users that the application will need to be restarted before the app calls the 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 rimuova il pacchetto facoltativo.If the optional package is content only then, the developer should explicitly tell the platform that the package that is about to remove is 'not in use' by the application before the developer removes the optional package. Questo consente anche allo sviluppatore di rimuovere il pacchetto senza un riavvio.This also allows the developer to remove the package without a restart.

Problemi notiKnown issues

Il debug di un progetto di set correlato facoltativo non è attualmente supportato in Visual Studio.Debugging a related set optional project is not currently supported in Visual Studio. Per risolvere questo problema, è possibile distribuire e avviare l'attivazione (CTRL + F5) e alleghire manualmente il debugger a un processo.To work around this issue, you can deploy and launch the activation (Ctrl + F5) and manually attach the debugger to a process. Per connettersi al debugger, passare al menu "debug" in Visual Studio, selezionare "Connetti a processo..." e il debugger viene collegato al processo dell'app principale.To attach the debugger, go the "Debug" menu in Visual Studio, select "Attach to Process...", and attach the debugger to the main app process.