Selezionare la versione di .NET Core da usareSelect the .NET Core version to use

Questo articolo illustra i criteri usati dagli strumenti di .NET Core, dall'SDK e dal Common Language Runtime per selezionare le versioni.This article explains the policies used by the .NET Core tools, SDK, and runtime for selecting versions. Questi criteri consentono di bilanciare tra l'esecuzione di applicazioni con le versioni specificate e la possibilità di aggiornare i computer sia degli sviluppatori che degli utenti finali.These policies provide a balance between running applications using the specified versions and enabling ease of upgrading both developer and end-user machines. Questi criteri consentono le azioni seguenti:These policies perform the following actions:

  • Distribuzione facile e veloce di .NET Core, inclusi gli aggiornamenti alla sicurezza e all'affidabilità.Easy and efficient deployment of .NET Core, including security and reliability updates.
  • Utilizzo degli strumenti e dei comandi più recenti indipendentemente dal runtime di destinazione.Use the latest tools and commands independent of target runtime.

La selezione della versione si verifica nei seguenti casi:Version selection occurs:

Il resto di questo documento esamina questi quattro scenari.The rest of this document examines those four scenarios.

L'SDK usa la versione installata più recenteThe SDK uses the latest installed version

I comandi dell'SDK includono dotnet new e dotnet run.SDK commands include dotnet new and dotnet run. L'interfaccia della riga di comando di .NET Core deve scegliere una versione dell'SDK per ogni comando dotnet.The .NET Core CLI must choose an SDK version for every dotnet command. Per impostazione predefinita, l'interfaccia della riga di comando usa l'SDK più recente installato nel computer, anche se:It uses the latest SDK installed on the machine by default, even if:

  • Il progetto è destinato a una versione precedente del runtime di .NET Core.The project targets an earlier version of the .NET Core runtime.
  • La versione più recente di .NET Core SDK è una versione di anteprima.The latest version of the .NET Core SDK is a preview version.

È possibile usufruire delle funzionalità e dei miglioramenti più recenti dell'SDK anche se si punta a versioni meno recenti di .NET Core Runtime.You can take advantage of the latest SDK features and improvements while targeting earlier .NET Core runtime versions. È possibile assegnare più versioni di runtime di .NET Core a progetti diversi, usando gli stessi strumenti dell'SDK per tutti i progetti.You can target multiple runtime versions of .NET Core on different projects, using the same SDK tools for all projects.

In casi rari potrebbe essere necessario usare una versione meno recente dell'SDK.On rare occasions, you may need to use an earlier version of the SDK. La versione deve essere specificata in un file global.json.You specify that version in a global.json file. I criteri dell'"uso della versione più recente" indicano che si usa solo il file global.json per specificare una versione di .NET Core SDK antecedente a quella installata, che è la più recente.The "use latest" policy means you only use global.json to specify a .NET Core SDK version earlier than the latest installed version.

Il file global.json può essere memorizzato in un punto qualsiasi della gerarchia di file.global.json can be placed anywhere in the file hierarchy. L'interfaccia della riga di comando cerca a ritroso il primo file global.json che trova partendo dalla directory di progetto.The CLI searches upward from the project directory for the first global.json it finds. Si controlla a quali progetti si applica un determinato file global.json in base alla sua posizione nel file system.You control which projects a given global.json applies to by its place in the file system. L'interfaccia della riga di comando .NET cerca ripetutamente un file global.json esplorando il percorso a ritroso partendo dalla directory di lavoro corrente.The .NET CLI searches for a global.json file iteratively navigating the path upward from the current working directory. Il primo file global.json trovato specifica la versione usata.The first global.json file found specifies the version used. Se la versione dell'SDK è installata, verrà usata la versione.If that SDK version is installed, that version is used. Se l'SDK specificato nel file Global. JSON non viene trovato, l'interfaccia della riga di comando di .NET usa le regole di corrispondenza per selezionare un SDK compatibile oppure ha esito negativo se non ne viene trovato nessuno.If the SDK specified in the global.json is not found, the .NET CLI uses matching rules to select a compatible SDK, or fails if none is found.

L'esempio seguente mostra la sintassi del file global.json:The following example shows the global.json syntax:

{
  "sdk": {
    "version": "2.0.0"
  }
}

Il processo per la selezione di una versione dell'SDK è il seguente:The process for selecting an SDK version is:

  1. dotnet cerca ripetutamente un file global.json risalendo il percorso a partire dalla directory di lavoro corrente.dotnet searches for a global.json file iteratively reverse-navigating the path upward from the current working directory.
  2. dotnet usa l'SDK specificato nel file global.json trovato.dotnet uses the SDK specified in the first global.json found.
  3. dotnet usa l'SDK installato più recente se non viene trovato alcun file global.json.dotnet uses the latest installed SDK if no global.json is found.

Altre informazioni sulla selezione di una versione dell'SDK sono disponibili nella sezione sulle regole di corrispondenza nell'articolo relativo a global.json.You can learn more about selecting an SDK version in the Matching rules section of the article on global.json.

Definizione delle API della fase di compilazione tramite i moniker del framework di destinazioneTarget Framework Monikers define build time APIs

Il progetto viene compilato con le API definite in un moniker del framework di destinazione (TFM).You build your project against APIs defined in a Target Framework Moniker (TFM). Il framework di destinazione deve essere specificato nel file di progetto.You specify the target framework in the project file. Impostare l'elemento TargetFramework nel file di progetto come illustrato nell'esempio seguente:Set the TargetFramework element in your project file as shown in the following example:

<TargetFramework>netcoreapp2.0</TargetFramework>

È possibile compilare il progetto usando più TFM.You may build your project against multiple TFMs. L'impostazione di più framework di destinazione è una pratica più comune per le librerie, ma può essere usata anche con le applicazioni.Setting multiple target frameworks is more common for libraries but can be done with applications as well. Occorre specificare una proprietà TargetFrameworks (plurale di TargetFramework).You specify a TargetFrameworks property (plural of TargetFramework). I framework di destinazione sono delimitati da punto e virgola come illustrato nell'esempio seguente:The target frameworks are semicolon-delimited as shown in the following example:

<TargetFrameworks>netcoreapp2.0;net47</TargetFrameworks>

Una determinata versione di SDK supporta un set fisso di framework, inclusivo del framework di destinazione del runtime con cui viene offerto.A given SDK supports a fixed set of frameworks, capped to the target framework of the runtime it ships with. .NET Core 2.0 SDK, ad esempio, include il runtime .NET Core 2.0, che è un'implementazione del framework di destinazione netcoreapp2.0.For example, the .NET Core 2.0 SDK includes the .NET Core 2.0 runtime, which is an implementation of the netcoreapp2.0 target framework. .NET Core 2.0 SDK supporta netcoreapp1.0, netcoreapp1.1 e netcoreapp2.0 ma non netcoreapp2.1 (o versione superiore).The .NET Core 2.0 SDK supports netcoreapp1.0, netcoreapp1.1, and netcoreapp2.0 but not netcoreapp2.1 (or higher). Occorre installare .NET Core 2.1 SDK per compilare netcoreapp2.1.You install the .NET Core 2.1 SDK to build for netcoreapp2.1.

I framework di destinazione .NET Standard sono anche limitati al framework di destinazione del runtime fornito con SDK..NET Standard target frameworks are also capped to the target framework of the runtime the SDK ships with. .NET Core 2.0 SDK è limitato a netstandard2.0.The .NET Core 2.0 SDK is capped to netstandard2.0.

Roll forward delle app dipendenti dal frameworkFramework-dependent apps roll forward

Quando si esegue un'applicazione dall'origine con dotnet run, da una distribuzione dipendente dal framework con dotnet myapp.dll o da un file eseguibile dipendente dal framework con myapp.exe, il file eseguibile dotnet è l'host dell'applicazione.When you run an application from source with dotnet run, from a framework-dependent deployment with dotnet myapp.dll, or from a framework-dependent executable with myapp.exe, the dotnet executable is the host for the application.

L'host sceglie la versione di patch più recente installata nel computer.The host chooses the latest patch version installed on the machine. Se ad esempio è stato specificato netcoreapp2.0 nel file di progetto e 2.0.4 è il runtime .NET più recente installato, viene usato il runtime 2.0.4.For example, if you specified netcoreapp2.0 in your project file, and 2.0.4 is the latest .NET runtime installed, the 2.0.4 runtime is used.

Se non viene trovata alcuna versione 2.0.* accettabile, viene usata una nuova versione 2.*.If no acceptable 2.0.* version is found, a new 2.* version is used. Se ad esempio è stato specificato netcoreapp2.0 ed è installata solo la versione 2.1.0, l'applicazione viene eseguita usando il runtime 2.1.0.For example, if you specified netcoreapp2.0 and only 2.1.0 is installed, the application runs using the 2.1.0 runtime. Questo comportamento è detto "roll forward della versione secondaria".This behavior is referred to as "minor version roll-forward." Le versioni minori non verranno prese in considerazione.Lower versions also won't be considered. Se non è installato alcun runtime accettabile, l'applicazione non viene eseguita.When no acceptable runtime is installed, the application won't run.

Alcuni esempi d'uso dimostrano il comportamento quando la destinazione è 2.0:A few usage examples demonstrate the behavior, if you target 2.0:

  • È specificata la versione 2.0.2.0 is specified. 2.0.5 è la versione di patch più recente installata.2.0.5 is the highest patch version installed. Viene usata la versione 2.0.5.2.0.5 is used.
  • È specificata la versione 2.0.2.0 is specified. Non è installata alcuna versione 2.0.*.No 2.0.* versions are installed. 1.1.1 è il runtime più recente installato.1.1.1 is the highest runtime installed. Viene visualizzato un messaggio di errore.An error message is displayed.
  • È specificata la versione 2.0.2.0 is specified. Non è installata alcuna versione 2.0.*.No 2.0.* versions are installed. 2.2.2 è la versione di runtime 2.x più recente installata.2.2.2 is the highest 2.x runtime version installed. Viene usata la versione 2.2.2.2.2.2 is used.
  • È specificata la versione 2.0.2.0 is specified. Non è installata alcuna versione 2.x.No 2.x versions are installed. È installata la versione 3.0.0.3.0.0 is installed. Viene visualizzato un messaggio di errore.An error message is displayed.

Il roll forward della versione secondaria presenta un effetto collaterale che può interessare gli utenti finali.Minor version roll-forward has one side-effect that may affect end users. Si consideri lo scenario seguente:Consider the following scenario:

  1. L'applicazione specifica che è necessaria la versione 2.0.The application specifies that 2.0 is required.
  2. Al momento dell'esecuzione non è installata la versione 2.0.* ma la versione 2.2.2.When run, version 2.0.* is not installed, however, 2.2.2 is. Verrà usata la versione 2.2.2.Version 2.2.2 will be used.
  3. In un secondo momento, l'utente installerà la versione 2.0.5 ed eseguirà nuovamente l'applicazione, dopodiché verrà usata la versione 2.0.5.Later, the user installs 2.0.5 and runs the application again, 2.0.5 will now be used.

È possibile che le versioni 2.0.5 e 2.2.2 si comportino diversamente, in particolare per gli scenari come la serializzazione dei dati binari.It's possible that 2.0.5 and 2.2.2 behave differently, particularly for scenarios like serializing binary data.

Distribuzioni autonome con runtime selezionatoSelf-contained deployments include the selected runtime

È possibile pubblicare un'applicazione come distribuzione autonoma.You can publish an application as a self-contained distribution. Questo approccio raggruppa il runtime e le librerie di .NET Core con l'applicazione.This approach bundles the .NET Core runtime and libraries with your application. Le distribuzioni autonome non hanno dipendenze dagli ambienti di runtime.Self-contained deployments don't have a dependency on runtime environments. La scelta della versione di runtime avviene al momento della pubblicazione non in base di esecuzione.Runtime version selection occurs at publishing time, not run time.

Il processo di pubblicazione seleziona la versione di patch più recente della famiglia di runtime specificata.The publishing process selects the latest patch version of the given runtime family. Il comando dotnet publish ad esempio selezionerà .NET Core 2.0.4 se è la versione di patch più recente nella famiglia di runtime .NET Core 2.0.For example, dotnet publish will select .NET Core 2.0.4 if it is the latest patch version in the .NET Core 2.0 runtime family. Il framework di destinazione (incluse le patch di sicurezza più recenti) viene fornito con l'applicazione.The target framework (including the latest installed security patches) is packaged with the application.

Se la versione minima specificata per un'applicazione non viene soddisfatta, si verifica un errore.It's an error if the minimum version specified for an application isn't satisfied. dotnet publish esegue l'associazione alla versione di patch di runtime più recente (nella famiglia di versioni principale.secondaria specificata).dotnet publish binds to the latest runtime patch version (within a given major.minor version family). dotnet publish non supporta la semantica del roll forward di dotnet run.dotnet publish doesn't support the roll-forward semantics of dotnet run. Per altre informazioni su patch e distribuzioni autonome, vedere l'articolo sulla selezione della patch di runtime nella distribuzione di applicazioni .NET Core.For more information about patches and self-contained deployments, see the article on runtime patch selection in deploying .NET Core applications.

Le distribuzioni autonome potrebbero richiedere una versione di patch specifica.Self-contained deployments may require a specific patch version. È possibile sostituire la versione di patch di runtime minima (per versioni superiori o inferiori) nel file di progetto, come illustrato nell'esempio seguente:You can override the minimum runtime patch version (to higher or lower versions) in the project file, as shown in the following example:

<RuntimeFrameworkVersion>2.0.4</RuntimeFrameworkVersion>

L'elemento RuntimeFrameworkVersion sostituisce i criteri di versione predefiniti.The RuntimeFrameworkVersion element overrides the default version policy. Per le distribuzioni autonome, l'elemento RuntimeFrameworkVersion specifica l'esatta versione del framework di runtime.For self-contained deployments, the RuntimeFrameworkVersion specifies the exact runtime framework version. Per le applicazioni dipendenti dal framework, l'elemento RuntimeFrameworkVersion specifica la versione di framework di runtime minima richiesta.For framework-dependent applications, the RuntimeFrameworkVersion specifies the minimum required runtime framework version.