Usare assembly di avvio dell'hosting in ASP.NET CoreUse hosting startup assemblies in ASP.NET Core

Di Luke Latham e Pavel KrymetsBy Luke Latham and Pavel Krymets

Un'implementazione IHostingStartup (avvio dell'hosting) consente l'aggiunta di miglioramenti a un'app all'avvio da un assembly esterno.An IHostingStartup (hosting startup) implementation adds enhancements to an app at startup from an external assembly. Una libreria esterna può ad esempio usare un'implementazione di avvio dell'hosting per offrire servizi o provider di configurazione aggiuntivi a un'app.For example, an external library can use a hosting startup implementation to provide additional configuration providers or services to an app.

Visualizzare o scaricare il codice di esempio (procedura per il download)View or download sample code (how to download)

Attributo HostingStartupHostingStartup attribute

Un attributo HostingStartup indica la presenza di un assembly di avvio dell'hosting da attivare in fase di runtime.A HostingStartup attribute indicates the presence of a hosting startup assembly to activate at runtime.

L'assembly di ingresso o l'assembly contenente la classe Startup viene analizzato automaticamente per la ricerca dell'attributo HostingStartup.The entry assembly or the assembly containing the Startup class is automatically scanned for the HostingStartup attribute. L'elenco di assembly in cui cercare gli attributi HostingStartup viene caricato in fase di runtime dalla configurazione in WebHostDefaults.HostingStartupAssembliesKey.The list of assemblies to search for HostingStartup attributes is loaded at runtime from configuration in the WebHostDefaults.HostingStartupAssembliesKey. L'elenco di assembly da escludere dalla ricerca viene caricato da WebHostDefaults.HostingStartupExcludeAssembliesKey.The list of assemblies to exclude from discovery is loaded from the WebHostDefaults.HostingStartupExcludeAssembliesKey. Per altre informazioni, vedere Host Web: assembly di avvio dell'hosting e Host Web: assembly di avvio dell'hosting da escludere.For more information, see Web Host: Hosting Startup Assemblies and Web Host: Hosting Startup Exclude Assemblies.

Nell'esempio seguente lo spazio dei nomi dell'assembly di avvio dell'hosting è StartupEnhancement.In the following example, the namespace of the hosting startup assembly is StartupEnhancement. La classe che contiene il codice di avvio dell'hosting è StartupEnhancementHostingStartup:The class containing the hosting startup code is StartupEnhancementHostingStartup:

[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]

L'attributo HostingStartup si trova in genere nel file della classe di implementazione IHostingStartup dell'assembly di avvio dell'hosting.The HostingStartup attribute is typically located in the hosting startup assembly's IHostingStartup implementation class file.

Individuare gli assembly di avvio dell'hosting caricatiDiscover loaded hosting startup assemblies

Per individuare gli assembly di avvio dell'hosting caricati, abilitare la registrazione e controllare i log dell'app.To discover loaded hosting startup assemblies, enable logging and check the app's logs. Gli errori che si verificano durante il caricamento degli assembly vengono registrati.Errors that occur when loading assemblies are logged. Gli assembly di avvio dell'hosting caricati vengono registrati a livello di debug e tutti gli errori vengono registrati.Loaded hosting startup assemblies are logged at the Debug level, and all errors are logged.

Disabilitare il caricamento automatico di assembly di avvio dell'hostingDisable automatic loading of hosting startup assemblies

Per disabilitare il caricamento automatico degli assembly di avvio dell'hosting, usare uno degli approcci seguenti:To disable automatic loading of hosting startup assemblies, use one of the following approaches:

  • Per evitare il caricamento di tutti gli assembly di avvio dell'hosting, impostare uno degli elementi seguenti su true o 1:To prevent all hosting startup assemblies from loading, set one of the following to true or 1:
  • Per impedire il caricamento di specifici assembly di avvio dell'hosting, impostare uno degli elementi seguenti su una stringa delimitata da punti e virgola di assembly di avvio dell'hosting da escludere all'avvio:To prevent specific hosting startup assemblies from loading, set one of the following to a semicolon-delimited string of hosting startup assemblies to exclude at startup:

Se l'impostazione di configurazione host e la variabile di ambiente sono entrambe impostate, l'impostazione host controlla il comportamento.If both the host configuration setting and the environment variable are set, the host setting controls the behavior.

La disabilitazione degli assembly di avvio dell'hosting tramite l'impostazione host o la variabile di ambiente ne determina la disabilitazione globale e la possibile disabilitazione di diverse caratteristiche di un'app.Disabling hosting startup assemblies using the host setting or environment variable disables the assembly globally and may disable several characteristics of an app.

ProgettoProject

Creare l'avvio dell'hosting con uno dei tipi di progetto seguenti:Create a hosting startup with either of the following project types:

Libreria di classiClass library

È possibile includere un miglioramento di avvio dell'hosting in una libreria di classi.A hosting startup enhancement can be provided in a class library. La libreria contiene un attributo HostingStartup.The library contains a HostingStartup attribute.

Il codice di esempio include un'app Razor Pages, HostingStartupApp, e una libreria di classi, HostingStartupLibrary.The sample code includes a Razor Pages app, HostingStartupApp, and a class library, HostingStartupLibrary. La libreria di classi:The class library:

  • Contiene una classe di avvio dell'hosting, ServiceKeyInjection, che implementa IHostingStartup.Contains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection aggiunge una coppia di stringhe di servizio alla configurazione dell'app tramite il provider di configurazione in memoria (AddInMemoryCollection).ServiceKeyInjection adds a pair of service strings to the app's configuration using the in-memory configuration provider (AddInMemoryCollection).
  • Include un attributo HostingStartup che identifica lo spazio dei nomi e la classe di avvio dell'hosting.Includes a HostingStartup attribute that identifies the hosting startup's namespace and class.

Il metodo Configure della classe ServiceKeyInjection usa IWebHostBuilder per aggiungere miglioramenti a un'app.The ServiceKeyInjection class's Configure method uses an IWebHostBuilder to add enhancements to an app.

HostingStartupLibrary/ServiceKeyInjection.cs:HostingStartupLibrary/ServiceKeyInjection.cs:

[assembly: HostingStartup(typeof(HostingStartupLibrary.ServiceKeyInjection))]

namespace HostingStartupLibrary
{
    public class ServiceKeyInjection : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            builder.ConfigureAppConfiguration(config =>
            {
                var dict = new Dictionary<string, string>
                {
                    {"DevAccount_FromLibrary", "DEV_1111111-1111"},
                    {"ProdAccount_FromLibrary", "PROD_2222222-2222"}
                };

                config.AddInMemoryCollection(dict);
            });
        }
    }
}

La pagina Indice dell'app legge ed esegue il rendering dei valori di configurazione per le due chiavi impostate dall'assembly di avvio dell'hosting della libreria di classi:The app's Index page reads and renders the configuration values for the two keys set by the class library's hosting startup assembly:

HostingStartupApp/Pages/Index.cshtml.cs:HostingStartupApp/Pages/Index.cshtml.cs:

public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
        ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
        ServiceKey_Development_Package = config["DevAccount_FromPackage"];
        ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
    }

    public string ServiceKey_Development_Library { get; private set; }
    public string ServiceKey_Production_Library { get; private set; }
    public string ServiceKey_Development_Package { get; private set; }
    public string ServiceKey_Production_Package { get; private set; }

    public void OnGet()
    {
    }
}

Il codice di esempio include anche un progetto di pacchetto NuGet che offre un avvio dell'hosting separato, HostingStartupPackage.The sample code also includes a NuGet package project that provides a separate hosting startup, HostingStartupPackage. Il pacchetto ha le stesse caratteristiche della libreria di classi descritta in precedenza.The package has the same characteristics of the class library described earlier. Il pacchetto:The package:

  • Contiene una classe di avvio dell'hosting, ServiceKeyInjection, che implementa IHostingStartup.Contains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection aggiunge una coppia di stringhe di servizio alla configurazione dell'app.ServiceKeyInjection adds a pair of service strings to the app's configuration.
  • Include un attributo HostingStartup.Includes a HostingStartup attribute.

HostingStartupPackage/ServiceKeyInjection.cs:HostingStartupPackage/ServiceKeyInjection.cs:

[assembly: HostingStartup(typeof(HostingStartupPackage.ServiceKeyInjection))]

namespace HostingStartupPackage
{
    public class ServiceKeyInjection : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            builder.ConfigureAppConfiguration(config =>
            {
                var dict = new Dictionary<string, string>
                {
                    {"DevAccount_FromPackage", "DEV_3333333-3333"},
                    {"ProdAccount_FromPackage", "PROD_4444444-4444"}
                };

                config.AddInMemoryCollection(dict);
            });
        }
    }
}

La pagina Indice dell'app legge ed esegue il rendering dei valori di configurazione per le due chiavi impostate dall'assembly di avvio dell'hosting del pacchetto:The app's Index page reads and renders the configuration values for the two keys set by the package's hosting startup assembly:

HostingStartupApp/Pages/Index.cshtml.cs:HostingStartupApp/Pages/Index.cshtml.cs:

public class IndexModel : PageModel
{
    public IndexModel(IConfiguration config)
    {
        ServiceKey_Development_Library = config["DevAccount_FromLibrary"];
        ServiceKey_Production_Library = config["ProdAccount_FromLibrary"];
        ServiceKey_Development_Package = config["DevAccount_FromPackage"];
        ServiceKey_Production_Package = config["ProdAccount_FromPackage"];
    }

    public string ServiceKey_Development_Library { get; private set; }
    public string ServiceKey_Production_Library { get; private set; }
    public string ServiceKey_Development_Package { get; private set; }
    public string ServiceKey_Production_Package { get; private set; }

    public void OnGet()
    {
    }
}

App console senza un punto di ingressoConsole app without an entry point

Questo approccio è disponibile solo per le app .NET Core, non .NET Framework.This approach is only available for .NET Core apps, not .NET Framework.

Un miglioramento di avvio dell'hosting dinamico che non richiede un riferimento in fase di compilazione per l'attivazione può essere fornito in un'app console senza un punto di ingresso che contiene un attributo HostingStartup.A dynamic hosting startup enhancement that doesn't require a compile-time reference for activation can be provided in a console app without an entry point that contains a HostingStartup attribute. La pubblicazione dell'app console produce un assembly di avvio dell'hosting che può essere utilizzato dall'archivio di runtime.Publishing the console app produces a hosting startup assembly that can be consumed from the runtime store.

In questo processo viene usata un'app console senza un punto di ingresso perché:A console app without an entry point is used in this process because:

  • È necessario un file di dipendenze per utilizzare l'avvio dell'hosting nell'assembly di avvio dell'hosting.A dependencies file is required to consume the hosting startup in the hosting startup assembly. Un file di dipendenze è una risorsa di app eseguibile prodotta dalla pubblicazione di un'app, non una libreria.A dependencies file is a runnable app asset that's produced by publishing an app, not a library.
  • Una libreria non può essere aggiunta direttamente all'archivio dei pacchetti di runtime che richiede un progetto eseguibile indirizzato al runtime condiviso.A library can't be added directly to the runtime package store, which requires a runnable project that targets the shared runtime.

Durante la creazione di un avvio dell'hosting dinamico:In the creation of a dynamic hosting startup:

  • Viene creato un assembly di avvio dell'hosting dall'app console senza un punto di ingresso che:A hosting startup assembly is created from the console app without an entry point that:
    • Include una classe che contiene l'implementazione IHostingStartup.Includes a class that contains the IHostingStartup implementation.
    • Include un attributo HostingStartup per identificare la classe di implementazione IHostingStartup.Includes a HostingStartup attribute to identify the IHostingStartup implementation class.
  • L'app console viene pubblicata per ottenere le dipendenze dell'avvio dell'hosting.The console app is published to obtain the hosting startup's dependencies. Una conseguenza della pubblicazione dell'app console è che le dipendenze non usate vengono eliminate dal file di dipendenze.A consequence of publishing the console app is that unused dependencies are trimmed from the dependencies file.
  • Il file delle dipendenze viene modificato per impostare il percorso di runtime dell'assembly di avvio dell'hosting.The dependencies file is modified to set the runtime location of the hosting startup assembly.
  • L'assembly di avvio dell'hosting e il relativo file di dipendenze vengono posizionati nell'archivio dei pacchetti di runtime.The hosting startup assembly and its dependencies file is placed into the runtime package store. Per individuare l'assembly di avvio dell'hosting e il relativo file di dipendenze, questi elementi sono elencati in una coppia di variabili di ambiente.To discover the hosting startup assembly and its dependencies file, they're listed in a pair of environment variables.

L'app console fa riferimento al pacchetto Microsoft.AspNetCore.Hosting.Abstractions:The console app references the Microsoft.AspNetCore.Hosting.Abstractions package:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Hosting.Abstractions" 
                      Version="2.1.1" />
  </ItemGroup>

</Project>

Un attributo HostingStartup identifica una classe come un'implementazione di IHostingStartup per il caricamento e l'esecuzione al momento della compilazione di IWebHost.A HostingStartup attribute identifies a class as an implementation of IHostingStartup for loading and execution when building the IWebHost. Nell'esempio seguente, lo spazio dei nomi è StartupEnhancement e la classe è StartupEnhancementHostingStartup:In the following example, the namespace is StartupEnhancement, and the class is StartupEnhancementHostingStartup:

[assembly: HostingStartup(typeof(StartupEnhancement.StartupEnhancementHostingStartup))]

Una classe implementa IHostingStartup.A class implements IHostingStartup. Il metodo Configure della classe usa un'interfaccia IWebHostBuilder per aggiungere miglioramenti a un'app.The class's Configure method uses an IWebHostBuilder to add enhancements to an app. Nell'assembly di avvio dell'hosting IHostingStartup.Configure viene chiamato dal runtime prima di Startup.Configure nel codice utente, il che consente al codice utente di sovrascrivere qualsiasi configurazione fornita dall'assembly di avvio dell'hosting.IHostingStartup.Configure in the hosting startup assembly is called by the runtime before Startup.Configure in user code, which allows user code to overwrite any configuration provided by the hosting startup assembly.

namespace StartupEnhancement
{
    public class StartupEnhancementHostingStartup : IHostingStartup
    {
        public void Configure(IWebHostBuilder builder)
        {
            // Use the IWebHostBuilder to add app enhancements.
        }
    }
}

Quando si compila un progetto IHostingStartup, il file delle dipendenze ( .deps.json) imposta il percorso di runtime dell'assembly sulla cartella bin:When building an IHostingStartup project, the dependencies file (.deps.json) sets the runtime location of the assembly to the bin folder:

"targets": {
  ".NETCoreApp,Version=v2.1": {
    "StartupEnhancement/1.0.0": {
      "dependencies": {
        "Microsoft.AspNetCore.Hosting.Abstractions": "2.1.1"
      },
      "runtime": {
        "StartupEnhancement.dll": {}
      }
    }
  }
}

Viene visualizzata solo una parte del file.Only part of the file is shown. Il nome dell'assembly nell'esempio è StartupEnhancement.The assembly name in the example is StartupEnhancement.

Configurazione fornita dall'avvio dell'hostingConfiguration provided by the hosting startup

Esistono due approcci per la gestione di configurazione, a seconda che si voglia dare la precedenza alla configurazione d avvio dell'hosting o alla configurazione dell'app:There are two approaches to handling configuration depending on whether you want the hosting startup's configuration to take precedence or the app's configuration to take precedence:

  1. Fornire la configurazione all'app usando ConfigureAppConfiguration per caricare la configurazione dopo l'esecuzione dei delegati ConfigureAppConfiguration dell'app.Provide configuration to the app using ConfigureAppConfiguration to load the configuration after the app's ConfigureAppConfiguration delegates execute. La configurazione di avvio dell'hosting ha la priorità rispetto alla configurazione dell'app con questo approccio.Hosting startup configuration takes priority over the app's configuration using this approach.
  2. Fornire la configurazione all'app usando UseConfiguration per caricare la configurazione prima dell'esecuzione dei delegati ConfigureAppConfiguration dell'app.Provide configuration to the app using UseConfiguration to load the configuration before the app's ConfigureAppConfiguration delegates execute. I valori di configurazione dell'app hanno la priorità rispetto a quelli forniti dall'avvio dell'hosting usando questo approccio.The app's configuration values take priority over those provided by the hosting startup using this approach.
public class ConfigurationInjection : IHostingStartup
{
    public void Configure(IWebHostBuilder builder)
    {
        Dictionary<string, string> dict;

        builder.ConfigureAppConfiguration(config =>
        {
            dict = new Dictionary<string, string>
            {
                {"ConfigurationKey1", 
                    "From IHostingStartup: Higher priority than the app's configuration."},
            };

            config.AddInMemoryCollection(dict);
        });

        dict = new Dictionary<string, string>
        {
            {"ConfigurationKey2", 
                "From IHostingStartup: Lower priority than the app's configuration."},
        };

        var builtConfig = new ConfigurationBuilder()
            .AddInMemoryCollection(dict)
            .Build();

        builder.UseConfiguration(builtConfig);
    }
}

Specificare l'assembly di avvio dell'hostingSpecify the hosting startup assembly

Per un avvio dell'hosting fornito da una libreria di classi o da un'app console, specificare il nome dell'assembly di avvio dell'hosting nella variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.For either a class library- or console app-supplied hosting startup, specify the hosting startup assembly's name in the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable. La variabile di ambiente è un elenco di assembly delimitato da punto e virgola.The environment variable is a semicolon-delimited list of assemblies.

L'attributo HostingStartup viene cercato solo negli assembly di avvio dell'hosting.Only hosting startup assemblies are scanned for the HostingStartup attribute. Per l'app di esempio HostingStartupApp, per individuare gli avvii dell'hosting descritti in precedenza, la variabile di ambiente viene impostata sul valore seguente:For the sample app, HostingStartupApp, to discover the hosting startups described earlier, the environment variable is set to the following value:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

È possibile impostare l'assembly di avvio dell'hosting anche tramite l'impostazione di configurazione host Assembly di avvio dell'hosting.A hosting startup assembly can also be set using the Hosting Startup Assemblies host configuration setting.

Quando sono presenti più assembly di avvio dell'hosting, i relativi metodi Configure vengono eseguiti nell'ordine in cui sono elencati gli assembly.When multiple hosting startup assembles are present, their Configure methods are executed in the order that the assemblies are listed.

AttivazioneActivation

Le opzioni di attivazione dell'avvio dell'hosting sono:Options for hosting startup activation are:

  • Archivio di runtime – L'attivazione non richiede un riferimento in fase di compilazione.Runtime store – Activation doesn't require a compile-time reference for activation. L'app di esempio inserisce l'assembly di avvio dell'hosting e i file di dipendenze in una cartella deployment per facilitare la distribuzione dell'avvio dell'hosting in un ambiente con più computer.The sample app places the hosting startup assembly and dependencies files into a folder, deployment, to facilitate deployment of the hosting startup in a multimachine environment. La cartella deployment include anche uno script PowerShell che crea o modifica le variabili di ambiente nel sistema di distribuzione per abilitare l'avvio dell'hosting.The deployment folder also includes a PowerShell script that creates or modifies environment variables on the deployment system to enable the hosting startup.
  • Riferimento in fase di compilazione richiesto per l'attivazioneCompile-time reference required for activation

Archivio di runtimeRuntime store

L'implementazione dell'avvio dell'hosting viene inserita nell'archivio di runtime.The hosting startup implementation is placed in the runtime store. L'app migliorata non richiede un riferimento in fase di compilazione all'assembly.A compile-time reference to the assembly isn't required by the enhanced app.

Dopo la compilazione dell'avvio dell'hosting, viene generato un archivio di runtime usando il file di progetto del manifesto e il comando dotnet store.After the hosting startup is built, a runtime store is generated using the manifest project file and the dotnet store command.

dotnet store --manifest {MANIFEST FILE} --runtime {RUNTIME IDENTIFIER} --output {OUTPUT LOCATION} --skip-optimization

Nell'app di esempio (progetto RuntimeStore) viene usato il comando seguente:In the sample app (RuntimeStore project) the following command is used:

dotnet store --manifest store.manifest.csproj --runtime win7-x64 --output ./deployment/store --skip-optimization

Per consentire al runtime di individuare l'archivio di runtime, il percorso dell'archivio di runtime viene aggiunto alla variabile di ambiente DOTNET_SHARED_STORE.For the runtime to discover the runtime store, the runtime store's location is added to the DOTNET_SHARED_STORE environment variable.

Modificare e inserire il file di dipendenze dell'avvio dell'hostingModify and place the hosting startup's dependencies file

Per attivare il miglioramento senza un riferimento al pacchetto per il miglioramento, specificare le dipendenze aggiuntive per il runtime con additionalDeps.To activate the enhancement without a package reference to the enhancement, specify additional dependencies to the runtime with additionalDeps. additionalDeps consente di:additionalDeps allows you to:

  • Estendere il grafo della libreria dell'app fornendo un set di file .deps.json aggiuntivi da unire al file .deps.json proprio dell'app all'avvio.Extend the app's library graph by providing a set of additional .deps.json files to merge with the app's own .deps.json file on startup.
  • Rendere l'assembly di avvio dell'hosting individuabile e caricabile.Make the hosting startup assembly discoverable and loadable.

L'approccio consigliato per la generazione del file delle dipendenze aggiuntive è:The recommended approach for generating the additional dependencies file is to:

  1. Eseguire dotnet publish sul file manifesto dell'archivio di runtime indicato nella sezione precedente.Execute dotnet publish on the runtime store manifest file referenced in the previous section.
  2. Rimuovere il riferimento al manifesto dalle librerie e dalla sezione runtime del file .deps.json risultante.Remove the manifest reference from libraries and the runtime section of the resulting .deps.json file.

Nel progetto di esempio la proprietà store.manifest/1.0.0 viene rimossa da targets e dalla sezione libraries:In the example project, the store.manifest/1.0.0 property is removed from the targets and libraries section:

{
  "runtimeTarget": {
    "name": ".NETCoreApp,Version=v2.1",
    "signature": "4ea77c7b75ad1895ae1ea65e6ba2399010514f99"
  },
  "compilationOptions": {},
  "targets": {
    ".NETCoreApp,Version=v2.1": {
      "store.manifest/1.0.0": {
        "dependencies": {
          "StartupDiagnostics": "1.0.0"
        },
        "runtime": {
          "store.manifest.dll": {}
        }
      },
      "StartupDiagnostics/1.0.0": {
        "runtime": {
          "lib/netcoreapp2.1/StartupDiagnostics.dll": {
            "assemblyVersion": "1.0.0.0",
            "fileVersion": "1.0.0.0"
          }
        }
      }
    }
  },
  "libraries": {
    "store.manifest/1.0.0": {
      "type": "project",
      "serviceable": false,
      "sha512": ""
    },
    "StartupDiagnostics/1.0.0": {
      "type": "package",
      "serviceable": true,
      "sha512": "sha512-oiQr60vBQW7+nBTmgKLSldj06WNLRTdhOZpAdEbCuapoZ+M2DJH2uQbRLvFT8EGAAv4TAKzNtcztpx5YOgBXQQ==",
      "path": "startupdiagnostics/1.0.0",
      "hashPath": "startupdiagnostics.1.0.0.nupkg.sha512"
    }
  }
}

Posizionare il file .deps.json nel percorso seguente:Place the .deps.json file into the following location:

{ADDITIONAL DEPENDENCIES PATH}/shared/{SHARED FRAMEWORK NAME}/{SHARED FRAMEWORK VERSION}/{ENHANCEMENT ASSEMBLY NAME}.deps.json
  • {ADDITIONAL DEPENDENCIES PATH} – Percorso aggiunto alla variabile di ambiente DOTNET_ADDITIONAL_DEPS.{ADDITIONAL DEPENDENCIES PATH} – Location added to the DOTNET_ADDITIONAL_DEPS environment variable.
  • {SHARED FRAMEWORK NAME} – Framework condiviso necessario per questo file di dipendenze aggiuntive.{SHARED FRAMEWORK NAME} – Shared framework required for this additional dependencies file.
  • {SHARED FRAMEWORK VERSION} – Versione minima del framework condiviso.{SHARED FRAMEWORK VERSION} – Minimum shared framework version.
  • {ENHANCEMENT ASSEMBLY NAME} – Nome dell'assembly del miglioramento.{ENHANCEMENT ASSEMBLY NAME} – The enhancement's assembly name.

Nell'app di esempio (progetto RuntimeStore), il file di dipendenze aggiuntive viene posizionato nel percorso seguente:In the sample app (RuntimeStore project), the additional dependencies file is placed into the following location:

additionalDeps/shared/Microsoft.AspNetCore.App/2.1.0/StartupDiagnostics.deps.json

Affinché il runtime possa individuare il percorso dell'archivio di runtime, il percorso del file di dipendenze aggiuntive viene aggiunto alla variabile di ambiente DOTNET_ADDITIONAL_DEPS.For runtime to discover the runtime store location, the additional dependencies file location is added to the DOTNET_ADDITIONAL_DEPS environment variable.

Nell'app di esempio (progetto RuntimeStore), la creazione dell'archivio di runtime e la generazione del file di dipendenze aggiuntive vengono eseguite tramite uno script di PowerShell.In the sample app (RuntimeStore project), building the runtime store and generating the additional dependencies file is accomplished using a PowerShell script.

Per esempi che illustrano come impostare le variabili di ambiente per diversi sistemi operativi, vedere Usare più ambienti.For examples of how to set environment variables for various operating systems, see Use multiple environments.

DistribuzioneDeployment

Per facilitare la distribuzione di un avvio dell'hosting in un ambiente con più computer, l'app di esempio crea una cartella deplyment nell'output pubblicato che contiene:To facilitate the deployment of a hosting startup in a multimachine environment, the sample app creates a deployment folder in published output that contains:

  • L'archivio di runtime dell'avvio dell'hosting.The hosting startup runtime store.
  • Il file di dipendenze dell'avvio dell'hosting.The hosting startup dependencies file.
  • Uno script di PowerShell che crea o modifica ASPNETCORE_HOSTINGSTARTUPASSEMBLIES, DOTNET_SHARED_STORE e DOTNET_ADDITIONAL_DEPS per supportare l'attivazione dell'avvio dell'hosting.A PowerShell script that creates or modifies the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES, DOTNET_SHARED_STORE, and DOTNET_ADDITIONAL_DEPS to support the activation of the hosting startup. Eseguire lo script da un prompt dei comandi di PowerShell amministrativo del sistema di distribuzione.Run the script from an administrative PowerShell command prompt on the deployment system.

Pacchetto NuGetNuGet package

È possibile includere un miglioramento di avvio dell'hosting in un pacchetto NuGet.A hosting startup enhancement can be provided in a NuGet package. Il pacchetto include un attributo HostingStartup.The package has a HostingStartup attribute. I tipi di avvio dell'hosting offerti dal pacchetto vengono resi disponibili all'app usando uno degli approcci seguenti:The hosting startup types provided by the package are made available to the app using either of the following approaches:

  • Il file di progetto dell'app migliorata crea un riferimento al pacchetto per l'avvio dell'hosting nel file di progetto dell'app (un riferimento in fase di compilazione).The enhanced app's project file makes a package reference for the hosting startup in the app's project file (a compile-time reference). Dopo aver inserito il riferimento in fase di compilazione, l'assembly di avvio dell'hosting e tutte le relative dipendenze vengono incorporate nel file delle dipendenze dell'app ( .deps.json).With the compile-time reference in place, the hosting startup assembly and all of its dependencies are incorporated into the app's dependency file (.deps.json). Questo approccio si applica a un pacchetto di assembly di avvio dell'hosting pubblicato in nuget.org.This approach applies to a hosting startup assembly package published to nuget.org.
  • Il file di dipendenze dell'avvio dell'hosting viene reso disponibile all'app migliorata come descritto nella sezione Archivio di runtime (senza un riferimento in fase di compilazione).The hosting startup's dependencies file is made available to the enhanced app as described in the Runtime store section (without a compile-time reference).

Per altre informazioni su pacchetti NuGet e l'archivio di runtime, vedere gli argomenti seguenti:For more information on NuGet packages and the runtime store, see the following topics:

Cartella bin del progettoProject bin folder

È possibile inserire un avvio dell'hosting tramite un assembly distribuito tramite bin nell'app migliorata.A hosting startup enhancement can be provided by a bin-deployed assembly in the enhanced app. I tipi di avvio dell'hosting offerti dall'assembly vengono resi disponibili all'app usando uno degli approcci seguenti:The hosting startup types provided by the assembly are made available to the app using one of the following approaches:

  • Il file di progetto dell'app migliorata crea un riferimento all'assembly nell'avvio dell'hosting startup (riferimento in fase di compilazione).The enhanced app's project file makes an assembly reference to the hosting startup (a compile-time reference). Dopo aver inserito il riferimento in fase di compilazione, l'assembly di avvio dell'hosting e tutte le relative dipendenze vengono incorporate nel file delle dipendenze dell'app ( .deps.json).With the compile-time reference in place, the hosting startup assembly and all of its dependencies are incorporated into the app's dependency file (.deps.json). Questo approccio si applica quando lo scenario di distribuzione richiede la creazione di un riferimento in fase di compilazione all'assembly dell'avvio dell'hosting (file DLL) e lo spostamento dell'assembly in uno dei due elementi seguenti:This approach applies when the deployment scenario calls for making a compile-time reference to the hosting startup's assembly (.dll file) and moving the assembly to either:
    • Il progetto che lo utilizza.The consuming project.
    • Una posizione accessibile dal progetto che lo utilizza.A location accessible by the consuming project.
  • Il file di dipendenze dell'avvio dell'hosting viene reso disponibile all'app migliorata come descritto nella sezione Archivio di runtime (senza un riferimento in fase di compilazione).The hosting startup's dependencies file is made available to the enhanced app as described in the Runtime store section (without a compile-time reference).
  • Quando la destinazione è .NET Framework, l'assembly può essere caricato nel contesto di caricamento predefinito, che in .NET Framework significa che l'assembly si trova in una delle posizioni seguenti:When targeting the .NET Framework, the assembly is loadable in the default load context, which on .NET Framework means that the assembly is located at either of the following locations:
    • Percorso della base dell'applicazione: cartella bin in cui si trova il file eseguibile dell'app (EXE).Application base path – The bin folder where the app's executable (.exe) is located.
    • Global Assembly Cache (GAC): gli assembly condivisi da più app .NET Framework vengono archiviati nella Global Assembly Cache.Global Assembly Cache (GAC) – The GAC stores assemblies that several .NET Framework apps share. Per altre informazioni, vedere Procedura: Installare un assembly nella Global Assembly Cache nella documentazione di .NET Framework.For more information, see How to: Install an assembly into the global assembly cache in the .NET Framework documentation.

Codice di esempioSample code

Il codice di esempio (come eseguire il download) illustra gli scenari di implementazione dell'avvio dell'hosting:The sample code (how to download) demonstrates hosting startup implementation scenarios:

  • Due assembly di avvio dell'hosting (librerie di classi) impostano ognuno una coppia chiave-valore di configurazione in memoria:Two hosting startup assemblies (class libraries) set a pair of in-memory configuration key-value pairs each:
    • Pacchetto NuGet (HostingStartupPackage)NuGet package (HostingStartupPackage)
    • Libreria di classi (HostingStartupLibrary)Class library (HostingStartupLibrary)
  • L'avvio dell'hosting viene attivato da un assembly distribuito tramite archivio di runtime (StartupDiagnostics).A hosting startup is activated from a runtime store-deployed assembly (StartupDiagnostics). All'avvio l'assembly aggiunge all'app due middleware che offrono informazioni di diagnostica su:The assembly adds two middlewares to the app at startup that provide diagnostic information on:
    • Servizi registratiRegistered services
    • Indirizzo (schema, host, base del percorso, percorso, stringa di query)Address (scheme, host, path base, path, query string)
    • Connessione (IP remoto, porta remota, IP locale, porta locale, certificato client)Connection (remote IP, remote port, local IP, local port, client certificate)
    • Intestazioni della richiestaRequest headers
    • Variabili di ambienteEnvironment variables

Per eseguire l'esempio:To run the sample:

Attivazione da un pacchetto NuGetActivation from a NuGet package

  1. Compilare il pacchetto HostingStartupPackage con il comando dotnet pack.Compile the HostingStartupPackage package with the dotnet pack command.

  2. Aggiungere il nome dell'assembly del pacchetto HostingStartupPackage alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.Add the package's assembly name of the HostingStartupPackage to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. Compilare ed eseguire l'app.Compile and run the app. L'app migliorata include un riferimento al pacchetto (riferimento in fase di compilazione).A package reference is present in the enhanced app (a compile-time reference). <PropertyGroup> nel file di progetto dell'app specifica l'output del progetto del pacchetto ( ../HostingStartupPackage/bin/Debug) come origine del pacchetto.A <PropertyGroup> in the app's project file specifies the package project's output (../HostingStartupPackage/bin/Debug) as a package source. Ciò consente all'app di usare il pacchetto senza caricarlo in nuget.org. Per altre informazioni, vedere le note nel file di progetto di HostingStartupApp.This allows the app to use the package without uploading the package to nuget.org. For more information, see the notes in the HostingStartupApp's project file.

    <PropertyGroup>
      <RestoreSources>$(RestoreSources);https://api.nuget.org/v3/index.json;../HostingStartupPackage/bin/Debug</RestoreSources>
    </PropertyGroup>
    
  4. Si noti che i valori di chiave di configurazione del servizio di cui è stato eseguito il rendering tramite la pagina Indice corrispondono ai valori impostati dal metodo ServiceKeyInjection.Configure del pacchetto.Observe that the service configuration key values rendered by the Index page match the values set by the package's ServiceKeyInjection.Configure method.

Se si apportano modifiche al progetto HostingStartupPackage e lo si ricompila, cancellare le cache del pacchetto NuGet locale per assicurarsi che HostingStartupApp riceva il pacchetto aggiornato e non un pacchetto non aggiornato proveniente dalla cache locale.If you make changes to the HostingStartupPackage project and recompile it, clear the local NuGet package caches to ensure that the HostingStartupApp receives the updated package and not a stale package from the local cache. Per cancellare le cache NuGet locali, eseguire il comando dotnet nuget locals seguente:To clear the local NuGet caches, execute the following dotnet nuget locals command:

dotnet nuget locals all --clear

Attivazione da una libreria di classiActivation from a class library

  1. Compilare la libreria di classi HostingStartupLibrary con il comando dotnet build.Compile the HostingStartupLibrary class library with the dotnet build command.

  2. Aggiungere il nome dell'assembly della libreria di classi di HostingStartupLibrary alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.Add the class library's assembly name of HostingStartupLibrary to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. Distribuire tramite bin l'assembly della libreria di classi all'app copiando il file HostingStartupLibrary.dll dall'output compilato della libreria di classi alla cartella bin/Debug dell'app.bin-deploy the class library's assembly to the app by copying the HostingStartupLibrary.dll file from the class library's compiled output to the app's bin/Debug folder.

  4. Compilare ed eseguire l'app.Compile and run the app. <ItemGroup> nel file di progetto dell'app fa riferimento all'assembly della libreria di classi ( .\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll) (riferimento in fase di compilazione).An <ItemGroup> in the app's project file references the class library's assembly (.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll) (a compile-time reference). Per altre informazioni, vedere le note nel file di progetto di HostingStartupApp.For more information, see the notes in the HostingStartupApp's project file.

    <ItemGroup>
      <Reference Include=".\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll">
        <HintPath>.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll</HintPath>
        <SpecificVersion>False</SpecificVersion>
      </Reference>
    </ItemGroup>
    
  5. Si noti che i valori di chiave di configurazione del servizio di cui è stato eseguito il rendering tramite la pagina Indice corrispondono ai valori impostati dal metodo ServiceKeyInjection.Configure della libreria di classi.Observe that the service configuration key values rendered by the Index page match the values set by the class library's ServiceKeyInjection.Configure method.

Attivazione da un assembly distribuito tramite l'archivio di runtimeActivation from a runtime store-deployed assembly

  1. Il progetto StartupDiagnostics usa PowerShell per modificare il relativo file StartupDiagnostics.deps.json.The StartupDiagnostics project uses PowerShell to modify its StartupDiagnostics.deps.json file. PowerShell viene installato per impostazione predefinita in Windows a partire da Windows 7 SP1 e Windows Server 2008 R2 SP1.PowerShell is installed by default on Windows starting with Windows 7 SP1 and Windows Server 2008 R2 SP1. Per ottenere PowerShell su altre piattaforme, vedere Installazione di Windows PowerShell.To obtain PowerShell on other platforms, see Installing Windows PowerShell.
  2. Eseguire lo script build.ps1 nella cartella RuntimeStore.Execute the build.ps1 script in the RuntimeStore folder. Lo script:The script:
    • Genera il pacchetto StartupDiagnostics.Generates the StartupDiagnostics package.
    • Genera l'archivio di runtime per StartupDiagnostics nella cartella store.Generates the runtime store for StartupDiagnostics in the store folder. Il comando dotnet store nello script usa l'identificatore di runtime (RID) win7-x64 per un avvio dell'hosting distribuito su Windows.The dotnet store command in the script uses the win7-x64 runtime identifier (RID) for a hosting startup deployed to Windows. Quando si specifica l'avvio dell'hosting per un runtime diverso, immettere il RID corretto nella riga 37 dello script.When providing the hosting startup for a different runtime, substitute the correct RID on line 37 of the script.
    • Genera additionalDeps per StartupDiagnostics nella cartella additionalDeps/shared/Microsoft.AspNetCore.App/{Shared Framework Version}/ .Generates the additionalDeps for StartupDiagnostics in the additionalDeps/shared/Microsoft.AspNetCore.App/{Shared Framework Version}/ folder.
    • Posiziona il file deploy.ps1 nella cartella deployment.Places the deploy.ps1 file in the deployment folder.
  3. Eseguire lo script deploy.ps1 nella cartella deployment.Run the deploy.ps1 script in the deployment folder. Lo script aggiunge:The script appends:
    • StartupDiagnostics alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.StartupDiagnostics to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.
    • Percorso delle dipendenze di avvio dell'hosting per la variabile di ambiente DOTNET_ADDITIONAL_DEPS.The hosting startup dependencies path to the DOTNET_ADDITIONAL_DEPS environment variable.
    • Percorso dell'archivio di runtime per la variabile di ambiente DOTNET_SHARED_STORE.The runtime store path to the DOTNET_SHARED_STORE environment variable.
  4. Eseguire l'app di esempio.Run the sample app.
  5. Richiedere l'endpoint /services per visualizzare i servizi registrati dell'app.Request the /services endpoint to see the app's registered services. Richiedere l'endpoint /diag per visualizzare le informazioni di diagnostica.Request the /diag endpoint to see the diagnostic information.