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

  • Articolo

Nota

Questa non è la versione più recente di questo articolo. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Avviso

Questa versione di ASP.NET Core non è più supportata. Per altre informazioni, vedere Criteri di supporto di .NET e .NET Core. Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Importante

Queste informazioni si riferiscono a un prodotto non definitive che può essere modificato in modo sostanziale prima che venga rilasciato commercialmente. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Per la versione corrente, vedere la versione .NET 8 di questo articolo.

Di Paolo Krymets

Un'implementazione IHostingStartup (avvio dell'hosting) aggiunge miglioramenti a un'app all'avvio da un assembly esterno. Una libreria esterna può ad esempio usare un'implementazione di avvio dell'hosting per offrire servizi o provider di configurazione aggiuntivi a un'app.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Attributo HostingStartup

Un attributo HostingStartup indica la presenza di un assembly di avvio dell'hosting da attivare in fase di runtime.

L'assembly di ingresso o l'assembly contenente la classe Startup viene analizzato automaticamente per la ricerca dell'attributo HostingStartup. L'elenco di assembly in cui cercare gli attributi HostingStartup viene caricato in fase di runtime dalla configurazione in WebHostDefaults.HostingStartupAssembliesKey. L'elenco di assembly da escludere dalla ricerca viene caricato da WebHostDefaults.HostingStartupExcludeAssembliesKey.

Nell'esempio seguente lo spazio dei nomi dell'assembly di avvio dell'hosting è StartupEnhancement. La classe che contiene il codice di avvio dell'hosting è 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.

Individuare gli assembly di avvio dell'hosting caricati

Per individuare gli assembly di avvio dell'hosting caricati, abilitare la registrazione e controllare i log dell'app. Gli errori che si verificano durante il caricamento degli assembly vengono registrati. Gli assembly di avvio dell'hosting caricati vengono registrati a livello di debug e tutti gli errori vengono registrati.

Disabilitare il caricamento automatico di assembly di avvio dell'hosting

Per disabilitare il caricamento automatico degli assembly di avvio dell'hosting, usare uno degli approcci seguenti:

  • Per evitare il caricamento di tutti gli assembly di avvio dell'hosting, impostare uno degli elementi seguenti su true o 1:

    • Impedisci l'impostazione di configurazione dell'host di avvio dell'hosting:

      public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseSetting(
                    WebHostDefaults.PreventHostingStartupKey, "true")
                .UseStartup<Startup>();
        });

    • La variabile di ambiente ASPNETCORE_PREVENTHOSTINGSTARTUP.

  • 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:

    • Impostazione di configurazione host Di esclusione assembly di avvio dell'hosting:

      public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseSetting(
                    WebHostDefaults.HostingStartupExcludeAssembliesKey, 
                    "{ASSEMBLY1;ASSEMBLY2; ...}")
                .UseStartup<Startup>();
        });

      Il {ASSEMBLY1;ASSEMBLY2; ...} segnaposto rappresenta l'elenco delimitato da punto e virgola degli assembly.

    • La variabile di ambiente ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES.

Se l'impostazione di configurazione host e la variabile di ambiente sono entrambe impostate, l'impostazione host controlla il comportamento.

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.

Project

Creare l'avvio dell'hosting con uno dei tipi di progetto seguenti:

Libreria di classi

È possibile includere un miglioramento di avvio dell'hosting in una libreria di classi. La libreria contiene un attributo HostingStartup.

Il codice di esempio include un'app Razor Pages, HostingStartupApp e una libreria di classi, HostingStartupLibrary. La libreria di classi:

  • Contiene una classe di avvio dell'hosting, ServiceKeyInjection, che implementa IHostingStartup. ServiceKeyInjection aggiunge una coppia di stringhe di servizio alla configurazione dell'app tramite il provider di configurazione in memoria (AddInMemoryCollection).
  • Include un attributo HostingStartup che identifica lo spazio dei nomi e la classe di avvio dell'hosting.

Il ServiceKeyInjection metodo della Configure classe usa un IWebHostBuilder oggetto per aggiungere miglioramenti a un'app.

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:

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. Il pacchetto ha le stesse caratteristiche della libreria di classi descritta in precedenza. Il pacchetto :

  • Contiene una classe di avvio dell'hosting, ServiceKeyInjection, che implementa IHostingStartup. ServiceKeyInjection aggiunge una coppia di stringhe di servizio alla configurazione dell'app.
  • Include un attributo HostingStartup.

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:

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 ingresso

Questo approccio è disponibile solo per le app .NET Core, non .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. La pubblicazione dell'app console produce un assembly di avvio dell'hosting che può essere utilizzato dall'archivio di runtime.

In questo processo viene usata un'app console senza un punto di ingresso perché:

  • È necessario un file di dipendenze per utilizzare l'avvio dell'hosting nell'assembly di avvio dell'hosting. Un file di dipendenze è una risorsa di app eseguibile prodotta dalla pubblicazione di un'app, non una libreria.
  • Una libreria non può essere aggiunta direttamente all'archivio dei pacchetti di runtime che richiede un progetto eseguibile indirizzato al runtime condiviso.

Durante la creazione di un avvio dell'hosting dinamico:

  • Un assembly di avvio dell'hosting viene creato dall'app console senza un punto di ingresso che:
    • Include una classe che contiene l'implementazione IHostingStartup.
    • Include un attributo HostingStartup per identificare la classe di implementazione IHostingStartup.
  • L'app console viene pubblicata per ottenere le dipendenze dell'avvio dell'hosting. Una conseguenza della pubblicazione dell'app console è che le dipendenze non usate vengono eliminate dal file di dipendenze.
  • Il file delle dipendenze viene modificato per impostare il percorso di runtime dell'assembly di avvio dell'hosting.
  • L'assembly di avvio dell'hosting e il relativo file di dipendenze vengono posizionati nell'archivio dei pacchetti di runtime. 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.

L'app console fa riferimento al pacchetto Microsoft.AspNetCore.Hosting.Abstractions:

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

  <PropertyGroup>
    <TargetFramework>netcoreapp3.0</TargetFramework>
  </PropertyGroup>

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

</Project>

Un attributo HostingStartup identifica una classe come implementazione di IHostingStartup per il caricamento e l'esecuzione durante la compilazione di IWebHost. Nell'esempio seguente, lo spazio dei nomi è StartupEnhancement e la classe è StartupEnhancementHostingStartup:

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

Una classe implementa IHostingStartup. Il metodo della Configure classe usa un IWebHostBuilder oggetto per aggiungere miglioramenti a un'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.

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

Quando si compila un IHostingStartup progetto, il file delle dipendenze (.deps.json) imposta il runtime percorso dell'assembly sulla cartella bin :

"targets": {
  ".NETCoreApp,Version=v3.0": {
    "StartupEnhancement/1.0.0": {
      "dependencies": {
        "Microsoft.AspNetCore.Hosting.Abstractions": "3.0.0"
      },
      "runtime": {
        "StartupEnhancement.dll": {}
      }
    }
  }
}

Viene visualizzata solo una parte del file. Il nome dell'assembly nell'esempio è StartupEnhancement.

Configurazione fornita dall'avvio dell'hosting

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:

  1. Fornire la configurazione all'app usando ConfigureAppConfiguration per caricare la configurazione dopo l'esecuzione dei delegati ConfigureAppConfiguration dell'app. La configurazione di avvio dell'hosting ha la priorità rispetto alla configurazione dell'app con questo approccio.
  2. Fornire la configurazione all'app usando UseConfiguration per caricare la configurazione prima dell'esecuzione dei delegati ConfigureAppConfiguration dell'app. I valori di configurazione dell'app hanno la priorità rispetto a quelli forniti dall'avvio dell'hosting usando questo approccio.
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'hosting

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. La variabile di ambiente è un elenco di assembly delimitato da punto e virgola.

L'attributo HostingStartup viene cercato solo negli assembly di avvio dell'hosting. Per l'app di esempio HostingStartupApp, per individuare gli avvii dell'hosting descritti in precedenza, la variabile di ambiente viene impostata sul valore seguente:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

È anche possibile impostare un assembly di avvio dell'hosting usando l'impostazione di configurazione host Assembly di avvio dell'hosting:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseSetting(
                    WebHostDefaults.HostingStartupAssembliesKey, 
                    "{ASSEMBLY1;ASSEMBLY2; ...}")
                .UseStartup<Startup>();
        });

Il {ASSEMBLY1;ASSEMBLY2; ...} segnaposto rappresenta l'elenco delimitato da punto e virgola degli assembly.

Quando sono presenti più assembly di avvio dell'hosting, i relativi Configure metodi vengono eseguiti nell'ordine in cui sono elencati gli assembly.

Attivazione

Le opzioni di attivazione dell'avvio dell'hosting sono:

  • Archivio di runtime: l'attivazione non richiede un riferimento in fase di compilazione per l'attivazione. 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. 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.
  • Riferimento in fase di compilazione necessario per l'attivazione

Archivio di runtime

L'implementazione dell'avvio dell'hosting viene inserita nell'archivio di runtime. L'app migliorata non richiede un riferimento in fase di compilazione all'assembly.

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.

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

Nell'app di esempio (progetto RuntimeStore) viene usato il comando seguente:

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.

Modificare e inserire il file di dipendenze dell'avvio dell'hosting

Per attivare il miglioramento senza un riferimento al pacchetto per il miglioramento, specificare le dipendenze aggiuntive per il runtime con additionalDeps. additionalDeps consente di:

  • Estendere il grafico della libreria dell'app fornendo un set di file aggiuntivi .deps.json da unire con il proprio .deps.json file all'avvio dell'app.
  • Rendere l'assembly di avvio dell'hosting individuabile e caricabile.

L'approccio consigliato per la generazione del file delle dipendenze aggiuntive è:

  1. Eseguire dotnet publish sul file manifesto dell'archivio di runtime indicato nella sezione precedente.
  2. Rimuovere il riferimento al manifesto dalle librerie e dalla runtime sezione del file risultante .deps.json .

Nel progetto di esempio la proprietà store.manifest/1.0.0 viene rimossa da targets e dalla sezione libraries:

{
  "runtimeTarget": {
    "name": ".NETCoreApp,Version=v3.0",
    "signature": ""
  },
  "compilationOptions": {},
  "targets": {
    ".NETCoreApp,Version=v3.0": {
      "store.manifest/1.0.0": {
        "dependencies": {
          "StartupDiagnostics": "1.0.0"
        },
        "runtime": {
          "store.manifest.dll": {}
        }
      },
      "StartupDiagnostics/1.0.0": {
        "runtime": {
          "lib/netcoreapp3.0/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-xrhzuNSyM5/f4ZswhooJ9dmIYLP64wMnqUJSyTKVDKDVj5T+qtzypl8JmM/aFJLLpYrf0FYpVWvGujd7/FfMEw==",
      "path": "startupdiagnostics/1.0.0",
      "hashPath": "startupdiagnostics.1.0.0.nupkg.sha512"
    }
  }
}

Inserire il .deps.json file nel percorso seguente:

{ADDITIONAL DEPENDENCIES PATH}/shared/{SHARED FRAMEWORK NAME}/{SHARED FRAMEWORK VERSION}/{ENHANCEMENT ASSEMBLY NAME}.deps.json
  • {ADDITIONAL DEPENDENCIES PATH}: percorso aggiunto alla DOTNET_ADDITIONAL_DEPS variabile di ambiente.
  • {SHARED FRAMEWORK NAME}: framework condiviso necessario per questo file di dipendenze aggiuntivo.
  • {SHARED FRAMEWORK VERSION}: versione minima del framework condiviso.
  • {ENHANCEMENT ASSEMBLY NAME}: nome dell'assembly del miglioramento.

Nell'app di esempio (progetto RuntimeStore), il file di dipendenze aggiuntive viene posizionato nel percorso seguente:

deployment/additionalDeps/shared/Microsoft.AspNetCore.App/3.0.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.

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.

Per esempi che illustrano come impostare le variabili di ambiente per diversi sistemi operativi, vedere Usare più ambienti.

Distribuzione

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:

  • L'archivio di runtime dell'avvio dell'hosting.
  • Il file di dipendenze dell'avvio dell'hosting.
  • 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. Eseguire lo script da un prompt dei comandi di PowerShell amministrativo del sistema di distribuzione.

Pacchetto NuGet

È possibile includere un miglioramento di avvio dell'hosting in un pacchetto NuGet. Il pacchetto include un attributo HostingStartup. I tipi di avvio dell'hosting offerti dal pacchetto vengono resi disponibili all'app usando uno degli approcci seguenti:

  • 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). Con il riferimento in fase di compilazione sul posto, l'assembly di avvio dell'hosting e tutte le relative dipendenze vengono incorporate nel file di dipendenza dell'app (.deps.json). Questo approccio si applica a un pacchetto di assembly di avvio dell'hosting pubblicato in 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).

Per altre informazioni su pacchetti NuGet e l'archivio di runtime, vedere gli argomenti seguenti:

Cartella bin del progetto

È possibile inserire un avvio dell'hosting tramite un assembly distribuito tramite bin nell'app migliorata. I tipi di avvio dell'hosting offerti dall'assembly vengono resi disponibili all'app usando uno degli approcci seguenti:

  • Il file di progetto dell'app migliorata crea un riferimento all'assembly nell'avvio dell'hosting startup (riferimento in fase di compilazione). Con il riferimento in fase di compilazione sul posto, l'assembly di avvio dell'hosting e tutte le relative dipendenze vengono incorporate nel file di dipendenza dell'app (.deps.json). Questo approccio si applica quando lo scenario di distribuzione chiama per effettuare un riferimento in fase di compilazione all'assembly di avvio dell'hosting (.dll file) e spostarlo in uno dei due elementi seguenti:
    • Il progetto che lo utilizza.
    • Una posizione accessibile dal progetto che lo utilizza.
  • 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).
  • Quando la destinazione è .NET Framework, l'assembly è caricabile nel contesto di caricamento predefinito, che in .NET Framework significa che l'assembly si trova in una delle posizioni seguenti:
    • Percorso di base dell'applicazione: cartella bin in cui si trova il file eseguibile dell'app (.exe).
    • Global Assembly Cache (GAC): la GAC archivia gli assembly condivisi da diverse app .NET Framework. Per altre informazioni, vedere Procedura: Installare un assembly nella Global Assembly Cache nella documentazione di .NET Framework.

Codice di esempio

Il codice di esempio (come eseguire il download) illustra gli scenari di implementazione dell'avvio dell'hosting:

  • Due assembly di avvio dell'hosting (librerie di classi) impostano una coppia di coppie chiave-valore di configurazione in memoria ognuna:
    • Pacchetto NuGet (HostingStartupPackage)
    • Libreria di classi (HostingStartupLibrary)
  • L'avvio dell'hosting viene attivato da un assembly distribuito tramite archivio di runtime (StartupDiagnostics). L'assembly aggiunge due middleware all'app all'avvio che forniscono informazioni di diagnostica su:
    • Servizi registrati
    • Indirizzo (schema, host, base del percorso, percorso, stringa di query)
    • Connessione (IP remoto, porta remota, IP locale, porta locale, certificato client)
    • Intestazioni delle richieste
    • Variabili di ambiente

Per eseguire l'esempio:

Attivazione da un pacchetto NuGet

  1. Compilare il pacchetto HostingStartupPackage con il comando dotnet pack.

  2. Aggiungere il nome dell'assembly del pacchetto HostingStartupPackage alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.

  3. Compila ed esegui l'app. L'app migliorata include un riferimento al pacchetto (riferimento in fase di compilazione). <PropertyGroup> nel file di progetto dell'app specifica l'output del progetto del pacchetto (../HostingStartupPackage/bin/Debug) come origine del pacchetto. In questo modo l'app può usare il pacchetto senza caricare il pacchetto in nuget.org. Per altre informazioni, vedere le note nel file di progetto di HostingStartupApp.

    <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.

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. Per cancellare le cache NuGet locali, eseguire il comando dotnet nuget locals seguente:

dotnet nuget locals all --clear

Attivazione da una libreria di classi

  1. Compilare la libreria di classi HostingStartupLibrary con il comando dotnet build.

  2. Aggiungere il nome dell'assembly della libreria di classi di HostingStartupLibrary alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.

  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.

  4. Compila ed esegui l'app. Un <ItemGroup> oggetto nel file di progetto dell'app fa riferimento all'assembly della libreria di classi (.\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll) (riferimento in fase di compilazione). Per altre informazioni, vedere le note nel file di progetto di HostingStartupApp.

    <ItemGroup>
  <Reference Include=".\\bin\\Debug\\netcoreapp3.0\\HostingStartupLibrary.dll">
    <HintPath>.\bin\Debug\netcoreapp3.0\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.

Attivazione da un assembly distribuito tramite l'archivio di runtime

  1. Il progetto StartupDiagnostics usa PowerShell per modificarne il StartupDiagnostics.deps.json file. PowerShell viene installato per impostazione predefinita in Windows a partire da Windows 7 SP1 e Windows Server 2008 R2 SP1. Per ottenere PowerShell in altre piattaforme, vedere Installazione di varie versioni di PowerShell.
  2. Eseguire lo script build.ps1 nella cartella RuntimeStore. Script:
    • Genera il StartupDiagnostics pacchetto nella cartella obj\packages .
    • Genera l'archivio di runtime per StartupDiagnostics nella cartella store. Il dotnet store comando nello script usa l'identificatore di runtime (RID) per un'avvio dell'hosting win7-x64 distribuito in Windows. Quando si specifica l'avvio dell'hosting per un runtime diverso, immettere il RID corretto nella riga 37 dello script. L'archivio di runtime per StartupDiagnostics verrà successivamente spostato nell'archivio di runtime dell'utente o del sistema nel computer in cui verrà utilizzato l'assembly. Il percorso di installazione dell'archivio runtime utente per l'assembly StartupDiagnostics è .dotnet/store/x64/netcoreapp3.0/startupdiagnostics/1.0.0/lib/netcoreapp3.0/StartupDiagnostics.dll.
    • Genera l'oggetto additionalDeps per StartupDiagnostics nella cartella additionalDeps . Le dipendenze aggiuntive verranno spostate in un secondo momento nelle dipendenze aggiuntive dell'utente o del sistema. Il percorso di installazione delle dipendenze aggiuntive dell'utente StartupDiagnostics è .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/3.0.0/StartupDiagnostics.deps.json.
    • Posiziona il file deploy.ps1 nella cartella deployment.
  3. Eseguire lo script deploy.ps1 nella cartella deployment. Lo script aggiunge:
    • StartupDiagnostics alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.
    • Percorso delle dipendenze di avvio dell'hosting (nella cartella di distribuzione del progetto RuntimeStore) alla DOTNET_ADDITIONAL_DEPS variabile di ambiente.
    • Percorso dell'archivio di runtime (nella cartella di distribuzione del progetto RuntimeStore) nella DOTNET_SHARED_STORE variabile di ambiente.
  4. Eseguire l'app di esempio.
  5. Richiedere l'endpoint /services per visualizzare i servizi registrati dell'app. Richiedere l'endpoint /diag per visualizzare le informazioni di diagnostica.

Un'implementazione IHostingStartup (avvio dell'hosting) aggiunge miglioramenti a un'app all'avvio da un assembly esterno. Una libreria esterna può ad esempio usare un'implementazione di avvio dell'hosting per offrire servizi o provider di configurazione aggiuntivi a un'app.

Visualizzare o scaricare il codice di esempio (procedura per il download)

Attributo HostingStartup

Un attributo HostingStartup indica la presenza di un assembly di avvio dell'hosting da attivare in fase di runtime.

L'assembly di ingresso o l'assembly contenente la classe Startup viene analizzato automaticamente per la ricerca dell'attributo HostingStartup. L'elenco di assembly in cui cercare gli attributi HostingStartup viene caricato in fase di runtime dalla configurazione in WebHostDefaults.HostingStartupAssembliesKey. L'elenco di assembly da escludere dalla ricerca viene caricato da WebHostDefaults.HostingStartupExcludeAssembliesKey. Per altre informazioni, vedere Host Web: Assembly di avvio dell'hosting e Host Web: Assembly di avvio dell'hosting da escludere.

Nell'esempio seguente lo spazio dei nomi dell'assembly di avvio dell'hosting è StartupEnhancement. La classe che contiene il codice di avvio dell'hosting è 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.

Individuare gli assembly di avvio dell'hosting caricati

Per individuare gli assembly di avvio dell'hosting caricati, abilitare la registrazione e controllare i log dell'app. Gli errori che si verificano durante il caricamento degli assembly vengono registrati. Gli assembly di avvio dell'hosting caricati vengono registrati a livello di debug e tutti gli errori vengono registrati.

Disabilitare il caricamento automatico di assembly di avvio dell'hosting

Per disabilitare il caricamento automatico degli assembly di avvio dell'hosting, usare uno degli approcci seguenti:

  • Per impedire il caricamento di tutti gli assembly di avvio dell'hosting, impostare una delle opzioni seguenti su true o 1:
  • Per impedire il caricamento di assembly di avvio dell'hosting specifici, impostare una delle opzioni seguenti su una stringa delimitata da punto e virgola di assembly di avvio dell'hosting da escludere all'avvio:

Se l'impostazione di configurazione host e la variabile di ambiente sono entrambe impostate, l'impostazione host controlla il comportamento.

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.

Project

Creare l'avvio dell'hosting con uno dei tipi di progetto seguenti:

Libreria di classi

È possibile includere un miglioramento di avvio dell'hosting in una libreria di classi. La libreria contiene un attributo HostingStartup.

Il codice di esempio include un'app Razor Pages, HostingStartupApp e una libreria di classi, HostingStartupLibrary. La libreria di classi:

  • Contiene una classe di avvio dell'hosting, ServiceKeyInjection, che implementa IHostingStartup. ServiceKeyInjection aggiunge una coppia di stringhe di servizio alla configurazione dell'app tramite il provider di configurazione in memoria (AddInMemoryCollection).
  • Include un attributo HostingStartup che identifica lo spazio dei nomi e la classe di avvio dell'hosting.

Il ServiceKeyInjection metodo della Configure classe usa un IWebHostBuilder oggetto per aggiungere miglioramenti a un'app.

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:

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. Il pacchetto ha le stesse caratteristiche della libreria di classi descritta in precedenza. Il pacchetto :

  • Contiene una classe di avvio dell'hosting, ServiceKeyInjection, che implementa IHostingStartup. ServiceKeyInjection aggiunge una coppia di stringhe di servizio alla configurazione dell'app.
  • Include un attributo HostingStartup.

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:

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 ingresso

Questo approccio è disponibile solo per le app .NET Core, non .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. La pubblicazione dell'app console produce un assembly di avvio dell'hosting che può essere utilizzato dall'archivio di runtime.

In questo processo viene usata un'app console senza un punto di ingresso perché:

  • È necessario un file di dipendenze per utilizzare l'avvio dell'hosting nell'assembly di avvio dell'hosting. Un file di dipendenze è una risorsa di app eseguibile prodotta dalla pubblicazione di un'app, non una libreria.
  • Una libreria non può essere aggiunta direttamente all'archivio dei pacchetti di runtime che richiede un progetto eseguibile indirizzato al runtime condiviso.

Durante la creazione di un avvio dell'hosting dinamico:

  • Un assembly di avvio dell'hosting viene creato dall'app console senza un punto di ingresso che:
    • Include una classe che contiene l'implementazione IHostingStartup.
    • Include un attributo HostingStartup per identificare la classe di implementazione IHostingStartup.
  • L'app console viene pubblicata per ottenere le dipendenze dell'avvio dell'hosting. Una conseguenza della pubblicazione dell'app console è che le dipendenze non usate vengono eliminate dal file di dipendenze.
  • Il file delle dipendenze viene modificato per impostare il percorso di runtime dell'assembly di avvio dell'hosting.
  • L'assembly di avvio dell'hosting e il relativo file di dipendenze vengono posizionati nell'archivio dei pacchetti di runtime. 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.

L'app console fa riferimento al pacchetto Microsoft.AspNetCore.Hosting.Abstractions:

<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 implementazione di IHostingStartup per il caricamento e l'esecuzione durante la compilazione di IWebHost. Nell'esempio seguente, lo spazio dei nomi è StartupEnhancement e la classe è StartupEnhancementHostingStartup:

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

Una classe implementa IHostingStartup. Il metodo della Configure classe usa un IWebHostBuilder oggetto per aggiungere miglioramenti a un'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.

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

Quando si compila un IHostingStartup progetto, il file delle dipendenze (.deps.json) imposta il runtime percorso dell'assembly sulla cartella bin :

"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. Il nome dell'assembly nell'esempio è StartupEnhancement.

Configurazione fornita dall'avvio dell'hosting

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:

  1. Fornire la configurazione all'app usando ConfigureAppConfiguration per caricare la configurazione dopo l'esecuzione dei delegati ConfigureAppConfiguration dell'app. La configurazione di avvio dell'hosting ha la priorità rispetto alla configurazione dell'app con questo approccio.
  2. Fornire la configurazione all'app usando UseConfiguration per caricare la configurazione prima dell'esecuzione dei delegati ConfigureAppConfiguration dell'app. I valori di configurazione dell'app hanno la priorità rispetto a quelli forniti dall'avvio dell'hosting usando questo approccio.
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'hosting

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. La variabile di ambiente è un elenco di assembly delimitato da punto e virgola.

L'attributo HostingStartup viene cercato solo negli assembly di avvio dell'hosting. Per l'app di esempio HostingStartupApp, per individuare gli avvii dell'hosting descritti in precedenza, la variabile di ambiente viene impostata sul valore seguente:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

È possibile impostare l'assembly di avvio dell'hosting anche tramite l'impostazione di configurazione host Assembly di avvio dell'hosting.

Quando sono presenti più assembly di avvio dell'hosting, i relativi Configure metodi vengono eseguiti nell'ordine in cui sono elencati gli assembly.

Attivazione

Le opzioni di attivazione dell'avvio dell'hosting sono:

  • Archivio di runtime: l'attivazione non richiede un riferimento in fase di compilazione per l'attivazione. 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. 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.
  • Riferimento in fase di compilazione necessario per l'attivazione

Archivio di runtime

L'implementazione dell'avvio dell'hosting viene inserita nell'archivio di runtime. L'app migliorata non richiede un riferimento in fase di compilazione all'assembly.

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.

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

Nell'app di esempio (progetto RuntimeStore) viene usato il comando seguente:

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.

Modificare e inserire il file di dipendenze dell'avvio dell'hosting

Per attivare il miglioramento senza un riferimento al pacchetto per il miglioramento, specificare le dipendenze aggiuntive per il runtime con additionalDeps. additionalDeps consente di:

  • Estendere il grafico della libreria dell'app fornendo un set di file aggiuntivi .deps.json da unire con il proprio .deps.json file all'avvio dell'app.
  • Rendere l'assembly di avvio dell'hosting individuabile e caricabile.

L'approccio consigliato per la generazione del file delle dipendenze aggiuntive è:

  1. Eseguire dotnet publish sul file manifesto dell'archivio di runtime indicato nella sezione precedente.
  2. Rimuovere il riferimento al manifesto dalle librerie e dalla runtime sezione del file risultante .deps.json .

Nel progetto di esempio la proprietà store.manifest/1.0.0 viene rimossa da targets e dalla sezione libraries:

{
  "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"
    }
  }
}

Inserire il .deps.json file nel percorso seguente:

{ADDITIONAL DEPENDENCIES PATH}/shared/{SHARED FRAMEWORK NAME}/{SHARED FRAMEWORK VERSION}/{ENHANCEMENT ASSEMBLY NAME}.deps.json
  • {ADDITIONAL DEPENDENCIES PATH}: percorso aggiunto alla DOTNET_ADDITIONAL_DEPS variabile di ambiente.
  • {SHARED FRAMEWORK NAME}: framework condiviso necessario per questo file di dipendenze aggiuntivo.
  • {SHARED FRAMEWORK VERSION}: versione minima del framework condiviso.
  • {ENHANCEMENT ASSEMBLY NAME}: nome dell'assembly del miglioramento.

Nell'app di esempio (progetto RuntimeStore), il file di dipendenze aggiuntive viene posizionato nel percorso seguente:

deployment/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.

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.

Per esempi che illustrano come impostare le variabili di ambiente per diversi sistemi operativi, vedere Usare più ambienti.

Distribuzione

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:

  • L'archivio di runtime dell'avvio dell'hosting.
  • Il file di dipendenze dell'avvio dell'hosting.
  • 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. Eseguire lo script da un prompt dei comandi di PowerShell amministrativo del sistema di distribuzione.

Pacchetto NuGet

È possibile includere un miglioramento di avvio dell'hosting in un pacchetto NuGet. Il pacchetto include un attributo HostingStartup. I tipi di avvio dell'hosting offerti dal pacchetto vengono resi disponibili all'app usando uno degli approcci seguenti:

  • 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). Con il riferimento in fase di compilazione sul posto, l'assembly di avvio dell'hosting e tutte le relative dipendenze vengono incorporate nel file di dipendenza dell'app (.deps.json). Questo approccio si applica a un pacchetto di assembly di avvio dell'hosting pubblicato in 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).

Per altre informazioni su pacchetti NuGet e l'archivio di runtime, vedere gli argomenti seguenti:

Cartella bin del progetto

È possibile inserire un avvio dell'hosting tramite un assembly distribuito tramite bin nell'app migliorata. I tipi di avvio dell'hosting offerti dall'assembly vengono resi disponibili all'app usando uno degli approcci seguenti:

  • Il file di progetto dell'app migliorata crea un riferimento all'assembly nell'avvio dell'hosting startup (riferimento in fase di compilazione). Con il riferimento in fase di compilazione sul posto, l'assembly di avvio dell'hosting e tutte le relative dipendenze vengono incorporate nel file di dipendenza dell'app (.deps.json). Questo approccio si applica quando lo scenario di distribuzione chiama per effettuare un riferimento in fase di compilazione all'assembly di avvio dell'hosting (.dll file) e spostarlo in uno dei due elementi seguenti:
    • Il progetto che lo utilizza.
    • Una posizione accessibile dal progetto che lo utilizza.
  • 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).
  • Quando la destinazione è .NET Framework, l'assembly è caricabile nel contesto di caricamento predefinito, che in .NET Framework significa che l'assembly si trova in una delle posizioni seguenti:
    • Percorso di base dell'applicazione: cartella bin in cui si trova il file eseguibile dell'app (.exe).
    • Global Assembly Cache (GAC): la GAC archivia gli assembly condivisi da diverse app .NET Framework. Per altre informazioni, vedere Procedura: Installare un assembly nella Global Assembly Cache nella documentazione di .NET Framework.

Codice di esempio

Il codice di esempio (come eseguire il download) illustra gli scenari di implementazione dell'avvio dell'hosting:

  • Due assembly di avvio dell'hosting (librerie di classi) impostano una coppia di coppie chiave-valore di configurazione in memoria ognuna:
    • Pacchetto NuGet (HostingStartupPackage)
    • Libreria di classi (HostingStartupLibrary)
  • L'avvio dell'hosting viene attivato da un assembly distribuito tramite archivio di runtime (StartupDiagnostics). L'assembly aggiunge due middleware all'app all'avvio che forniscono informazioni di diagnostica su:
    • Servizi registrati
    • Indirizzo (schema, host, base del percorso, percorso, stringa di query)
    • Connessione (IP remoto, porta remota, IP locale, porta locale, certificato client)
    • Intestazioni delle richieste
    • Variabili di ambiente

Per eseguire l'esempio:

Attivazione da un pacchetto NuGet

  1. Compilare il pacchetto HostingStartupPackage con il comando dotnet pack.

  2. Aggiungere il nome dell'assembly del pacchetto HostingStartupPackage alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.

  3. Compila ed esegui l'app. L'app migliorata include un riferimento al pacchetto (riferimento in fase di compilazione). <PropertyGroup> nel file di progetto dell'app specifica l'output del progetto del pacchetto (../HostingStartupPackage/bin/Debug) come origine del pacchetto. In questo modo l'app può usare il pacchetto senza caricare il pacchetto in nuget.org. Per altre informazioni, vedere le note nel file di progetto di HostingStartupApp.

    <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.

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. Per cancellare le cache NuGet locali, eseguire il comando dotnet nuget locals seguente:

dotnet nuget locals all --clear

Attivazione da una libreria di classi

  1. Compilare la libreria di classi HostingStartupLibrary con il comando dotnet build.

  2. Aggiungere il nome dell'assembly della libreria di classi di HostingStartupLibrary alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.

  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.

  4. Compila ed esegui l'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). Per altre informazioni, vedere le note nel file di progetto di HostingStartupApp.

    <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.

Attivazione da un assembly distribuito tramite l'archivio di runtime

  1. Il progetto StartupDiagnostics usa PowerShell per modificarne il StartupDiagnostics.deps.json file. PowerShell viene installato per impostazione predefinita in Windows a partire da Windows 7 SP1 e Windows Server 2008 R2 SP1. Per ottenere PowerShell in altre piattaforme, vedere Installazione di varie versioni di PowerShell.
  2. Eseguire lo script build.ps1 nella cartella RuntimeStore. Script:
    • Genera il StartupDiagnostics pacchetto nella cartella obj\packages .
    • Genera l'archivio di runtime per StartupDiagnostics nella cartella store. Il dotnet store comando nello script usa l'identificatore di runtime (RID) per un'avvio dell'hosting win7-x64 distribuito in Windows. Quando si specifica l'avvio dell'hosting per un runtime diverso, immettere il RID corretto nella riga 37 dello script. L'archivio di runtime per StartupDiagnostics verrà successivamente spostato nell'archivio di runtime dell'utente o del sistema nel computer in cui verrà utilizzato l'assembly. Il percorso di installazione dell'archivio runtime utente per l'assembly StartupDiagnostics è .dotnet/store/x64/netcoreapp2.2/startupdiagnostics/1.0.0/lib/netcoreapp2.2/StartupDiagnostics.dll.
    • Genera l'oggetto additionalDeps per StartupDiagnostics nella cartella additionalDeps . Le dipendenze aggiuntive verranno spostate in un secondo momento nelle dipendenze aggiuntive dell'utente o del sistema. Il percorso di installazione delle dipendenze aggiuntive dell'utente StartupDiagnostics è .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/2.2.0/StartupDiagnostics.deps.json.
    • Posiziona il file deploy.ps1 nella cartella deployment.
  3. Eseguire lo script deploy.ps1 nella cartella deployment. Lo script aggiunge:
    • StartupDiagnostics alla variabile di ambiente ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.
    • Percorso delle dipendenze di avvio dell'hosting (nella cartella di distribuzione del progetto RuntimeStore) alla DOTNET_ADDITIONAL_DEPS variabile di ambiente.
    • Percorso dell'archivio di runtime (nella cartella di distribuzione del progetto RuntimeStore) nella DOTNET_SHARED_STORE variabile di ambiente.
  4. Eseguire l'app di esempio.
  5. Richiedere l'endpoint /services per visualizzare i servizi registrati dell'app. Richiedere l'endpoint /diag per visualizzare le informazioni di diagnostica.