Utiliser des assemblys de démarrage d’hébergement dans ASP.NET CoreUse hosting startup assemblies in ASP.NET Core

Par Luke Latham et Pavel KrymetsBy Luke Latham and Pavel Krymets

Une implémentation IHostingStartup (hébergement au démarrage) ajoute des améliorations à une application au démarrage à partir d’un assembly externe.An IHostingStartup (hosting startup) implementation adds enhancements to an app at startup from an external assembly. Par exemple, une bibliothèque externe peut utiliser une implémentation d’hébergement au démarrage pour fournir des fournisseurs ou services de configuration supplémentaires à une application.For example, an external library can use a hosting startup implementation to provide additional configuration providers or services to an app.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)View or download sample code (how to download)

Attribut HostingStartupHostingStartup attribute

Un attribut HostingStartup indique la présence d’un assembly d’hébergement au démarrage à activer au moment de l’exécution.A HostingStartup attribute indicates the presence of a hosting startup assembly to activate at runtime.

L’assembly d’entrée ou l’assembly contenant la classe Startup est automatiquement analysé pour détecter l’attribut HostingStartup.The entry assembly or the assembly containing the Startup class is automatically scanned for the HostingStartup attribute. La liste des assemblys où les attributs HostingStartup doivent être recherchés est chargée au moment de l’exécution à partir de la configuration spécifiée dans WebHostDefaults.HostingStartupAssembliesKey.The list of assemblies to search for HostingStartup attributes is loaded at runtime from configuration in the WebHostDefaults.HostingStartupAssembliesKey. La liste des assemblys à exclure de cette détection est chargée de WebHostDefaults.HostingStartupExcludeAssembliesKey.The list of assemblies to exclude from discovery is loaded from the WebHostDefaults.HostingStartupExcludeAssembliesKey. Pour plus d’informations, consultez l’hôte web : Assemblys d’hébergement au démarrage et l’hôte web : Assemblys d’hébergement à exclure au démarrage.For more information, see Web Host: Hosting Startup Assemblies and Web Host: Hosting Startup Exclude Assemblies.

Dans l’exemple suivant, l’espace de noms de l’assembly d’hébergement au démarrage est StartupEnhancement.In the following example, the namespace of the hosting startup assembly is StartupEnhancement. La classe contenant le code d’hébergement au démarrage est StartupEnhancementHostingStartup :The class containing the hosting startup code is StartupEnhancementHostingStartup:

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

L’attribut HostingStartup se trouve généralement dans le fichier de classe d’implémentation IHostingStartup de l’assembly d’hébergement au démarrage.The HostingStartup attribute is typically located in the hosting startup assembly's IHostingStartup implementation class file.

Découvrir les assemblys d’hébergement au démarrage chargésDiscover loaded hosting startup assemblies

Pour détecter les assemblys d’hébergement au démarrage chargés, activez la journalisation et analysez les journaux de l’application.To discover loaded hosting startup assemblies, enable logging and check the app's logs. Les erreurs qui se produisent durant le chargement des assemblys sont journalisées.Errors that occur when loading assemblies are logged. Les assemblys d’hébergement au démarrage chargés sont journalisés au niveau Débogage, et toutes les erreurs sont journalisées.Loaded hosting startup assemblies are logged at the Debug level, and all errors are logged.

Désactiver le chargement automatique des assemblys d’hébergement au démarrageDisable automatic loading of hosting startup assemblies

Pour désactiver le chargement automatique des assemblys d’hébergement au démarrage, choisissez l’une des approches suivantes :To disable automatic loading of hosting startup assemblies, use one of the following approaches:

  • Pour bloquer le chargement de tous les assemblys d’hébergement au démarrage, définissez l’une des valeurs suivantes sur true ou 1 :To prevent all hosting startup assemblies from loading, set one of the following to true or 1:
    • Le paramètre de configuration d’hôte PreventHostingStartup.Prevent Hosting Startup host configuration setting.
    • La variable d’environnement ASPNETCORE_PREVENTHOSTINGSTARTUP.ASPNETCORE_PREVENTHOSTINGSTARTUP environment variable.
  • Pour bloquer le chargement de certains assemblys d’hébergement au démarrage, définissez l’une des valeurs suivantes sous la forme d’une liste délimitée par des points-virgules contenant les assemblys d’hébergement au démarrage à exclure au moment du démarrage :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:

Si le paramètre de configuration d’hôte et la variable d’environnement sont définis tous les deux, c’est le paramètre d’hôte qui détermine le comportement.If both the host configuration setting and the environment variable are set, the host setting controls the behavior.

La désactivation des assemblys d’hébergement au démarrage à l’aide du paramètre d’hôte ou de la variable d’environnement désactive l’assembly globalement et peut donc désactiver plusieurs caractéristiques d’une application.Disabling hosting startup assemblies using the host setting or environment variable disables the assembly globally and may disable several characteristics of an app.

ProjetProject

Créez un hébergement au démarrage avec un des types de projet suivants :Create a hosting startup with either of the following project types:

Bibliothèque de classesClass library

Une amélioration de l’hébergement au démarrage peut être fournie dans une bibliothèque de classes.A hosting startup enhancement can be provided in a class library. La bibliothèque contient un attribut HostingStartup.The library contains a HostingStartup attribute.

L’exemple de code inclut une application Razor Pages (HostingStartupApp) et une bibliothèque de classes (HostingStartupLibrary).The sample code includes a Razor Pages app, HostingStartupApp, and a class library, HostingStartupLibrary. La bibliothèque de classes :The class library:

  • Contient une classe d’hébergement au démarrage, ServiceKeyInjection, qui implémente IHostingStartup.Contains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection ajoute une paire de chaînes de service à la configuration de l’application par le biais du fournisseur de configuration en mémoire (AddInMemoryCollection).ServiceKeyInjection adds a pair of service strings to the app's configuration using the in-memory configuration provider (AddInMemoryCollection).
  • Inclut un attribut HostingStartup qui identifie l’espace de noms et la classe d’hébergement au démarrage.Includes a HostingStartup attribute that identifies the hosting startup's namespace and class.

La méthode Configure de la classe ServiceKeyInjection utilise un IWebHostBuilder pour ajouter des améliorations à une application.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 page d’index de l’application lit et affiche les valeurs de configuration des deux clés définies par l’assembly d’hébergement au démarrage de la bibliothèque de classes :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()
    {
    }
}

L’exemple de code inclut également un projet de package NuGet qui fournit un hébergement au démarrage distinct, HostingStartupPackage.The sample code also includes a NuGet package project that provides a separate hosting startup, HostingStartupPackage. Le package a les mêmes caractéristiques que la bibliothèque de classes décrite précédemment.The package has the same characteristics of the class library described earlier. Le package :The package:

  • Contient une classe d’hébergement au démarrage, ServiceKeyInjection, qui implémente IHostingStartup.Contains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection ajoute une paire de chaînes de service à la configuration de l’application.ServiceKeyInjection adds a pair of service strings to the app's configuration.
  • Inclut un attribut 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 page d’index de l’application lit et affiche les valeurs de configuration des deux clés définies par l’assembly d’hébergement au démarrage du package :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()
    {
    }
}

Application console sans point d’entréeConsole app without an entry point

Cette approche s’applique aux applications .NET Core, mais pas aux applications .NET Framework.This approach is only available for .NET Core apps, not .NET Framework.

Une amélioration d’hébergement au démarrage dynamique qui ne nécessite pas de référence au moment de la compilation pour l’activation peut être fournie dans une application console sans point d’entrée qui contient un attribut 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 publication de l’application console génère un assembly d’hébergement au démarrage qui peut être utilisé à partir du magasin de runtime.Publishing the console app produces a hosting startup assembly that can be consumed from the runtime store.

Une application console sans point d’entrée est utilisée dans ce processus, car :A console app without an entry point is used in this process because:

  • Un fichier de dépendances est nécessaire pour utiliser l’hébergement au démarrage dans l’assembly d’hébergement au démarrage.A dependencies file is required to consume the hosting startup in the hosting startup assembly. Un fichier de dépendances est une ressource d’application exécutable qui est générée par la publication d’une application, et non d’une bibliothèque.A dependencies file is a runnable app asset that's produced by publishing an app, not a library.
  • Une bibliothèque ne peut pas être ajoutée directement au magasin de packages de runtime, qui nécessite un projet exécutable ciblant le runtime partagé.A library can't be added directly to the runtime package store, which requires a runnable project that targets the shared runtime.

Lors de la création d’un hébergement au démarrage dynamique :In the creation of a dynamic hosting startup:

  • Un assembly d’hébergement au démarrage est créé à partir de l’application console sans point d’entrée qui :A hosting startup assembly is created from the console app without an entry point that:
    • Inclut une classe qui contient l’implémentation IHostingStartup.Includes a class that contains the IHostingStartup implementation.
    • Inclut un attribut HostingStartup pour identifier la classe d’implémentation IHostingStartup.Includes a HostingStartup attribute to identify the IHostingStartup implementation class.
  • L’application console est publiée pour obtenir les dépendances de l’hébergement au démarrage.The console app is published to obtain the hosting startup's dependencies. La publication de l’application console entraîne la suppression des dépendances inutilisées dans le fichier de dépendances.A consequence of publishing the console app is that unused dependencies are trimmed from the dependencies file.
  • Le fichier de dépendances est modifié pour définir l’emplacement d’exécution de l’assembly d’hébergement au démarrage.The dependencies file is modified to set the runtime location of the hosting startup assembly.
  • L’assembly d’hébergement au démarrage et le fichier de dépendances associé sont placés dans le magasin de packages de runtime.The hosting startup assembly and its dependencies file is placed into the runtime package store. Pour permettre leur détection, l’assembly d’hébergement au démarrage et le fichier de dépendances associé sont référencés dans une paire de variables d’environnement.To discover the hosting startup assembly and its dependencies file, they're listed in a pair of environment variables.

L’application console référence le package 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 attribut HostingStartup identifie une classe en tant qu’implémentation de IHostingStartup pour le chargement et l’exécution durant la génération de IWebHost.A HostingStartup attribute identifies a class as an implementation of IHostingStartup for loading and execution when building the IWebHost. Dans l’exemple suivant, l’espace de noms est StartupEnhancement, et la classe est StartupEnhancementHostingStartup :In the following example, the namespace is StartupEnhancement, and the class is StartupEnhancementHostingStartup:

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

Une classe implémente IHostingStartup.A class implements IHostingStartup. La méthode Configure de la classe utilise un IWebHostBuilder pour ajouter des améliorations à une application.The class's Configure method uses an IWebHostBuilder to add enhancements to an app. IHostingStartup.Configure dans l’assembly d’hébergement au démarrage est appelé par le runtime avant Startup.Configure dans le code utilisateur, ce qui permet au code utilisateur de remplacer la configuration fournie par l’assembly d’hébergement au démarrage.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.
        }
    }
}

Lors de la génération d’un projet IHostingStartup, le fichier de dépendances ( .deps.json) définit le dossier bin comme emplacement du runtime :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": {}
      }
    }
  }
}

Seule une partie du fichier est affichée.Only part of the file is shown. Le nom de l’assembly dans l’exemple est StartupEnhancement.The assembly name in the example is StartupEnhancement.

Configuration fournie par le démarrage d’hébergementConfiguration provided by the hosting startup

Il existe deux approches de gestion de la configuration selon si vous souhaitez que la configuration du démarrage d’hébergement ait la priorité ou que la configuration d’application ait la priorité :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. Fournissez la configuration à l’application à l’aide de ConfigureAppConfiguration pour charger la configuration après l’exécution des délégués ConfigureAppConfiguration de l’application.Provide configuration to the app using ConfigureAppConfiguration to load the configuration after the app's ConfigureAppConfiguration delegates execute. Avec cette approche, la configuration de démarrage d’hébergement est prioritaire sur la configuration d’application.Hosting startup configuration takes priority over the app's configuration using this approach.
  2. Fournissez la configuration à l’application à l’aide de UseConfiguration pour charger la configuration avant l’exécution des délégués ConfigureAppConfiguration de l’application.Provide configuration to the app using UseConfiguration to load the configuration before the app's ConfigureAppConfiguration delegates execute. Avec cette approche, les valeurs de la configuration d’application sont prioritaires sur celles fournies par le démarrage d’hébergement.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);
    }
}

Spécifier l’assembly d’hébergement au démarrageSpecify the hosting startup assembly

Pour l’hébergement au démarrage fourni par une bibliothèque de classes ou une application console, spécifiez le nom de l’assembly d’hébergement au démarrage dans la variable d’environnement 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. Cette variable est spécifiée sous la forme d’une liste d’assemblys délimitée par des points-virgules.The environment variable is a semicolon-delimited list of assemblies.

L’analyse de détection de l’attribut HostingStartup porte uniquement sur les assemblys d’hébergement au démarrage.Only hosting startup assemblies are scanned for the HostingStartup attribute. Dans l’exemple d’application (HostingStartupApp), pour permettre la détection des hébergements au démarrage décrits précédemment, la variable d’environnement est définie à la valeur suivante :For the sample app, HostingStartupApp, to discover the hosting startups described earlier, the environment variable is set to the following value:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

Un assembly d’hébergement au démarrage peut également être défini à l’aide du paramètre de configuration d’hôte HostingStartupAssemblies.A hosting startup assembly can also be set using the Hosting Startup Assemblies host configuration setting.

Quand plusieurs assemblys de démarrage d’hébergement sont présents, leurs méthodes Configure sont exécutées dans l’ordre dans lequel ils sont répertoriés.When multiple hosting startup assembles are present, their Configure methods are executed in the order that the assemblies are listed.

ActivationActivation

Les options d’activation de l’hébergement au démarrage sont les suivantes :Options for hosting startup activation are:

  • Magasin de runtime – L’activation ne nécessite pas de référence au moment de la compilation pour l’activation.Runtime store – Activation doesn't require a compile-time reference for activation. L’exemple d’application place les fichiers de l’assembly d’hébergement au démarrage et de ses dépendances dans le dossier deployment pour faciliter le déploiement de l’hébergement au démarrage dans un environnement multimachine.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. Le dossier deployment inclut également un script PowerShell qui crée ou modifie des variables d’environnement sur le système de déploiement pour activer l’hébergement au démarrage.The deployment folder also includes a PowerShell script that creates or modifies environment variables on the deployment system to enable the hosting startup.
  • Référence au moment de la compilation requise pour l’activationCompile-time reference required for activation

Magasin de runtimeRuntime store

L’implémentation d’hébergement au démarrage est placée dans le magasin de runtime.The hosting startup implementation is placed in the runtime store. L’application améliorée ne nécessite pas de référence à l’assembly au moment de la compilation.A compile-time reference to the assembly isn't required by the enhanced app.

Une fois l’hébergement au démarrage créé, un magasin de runtime est généré à l’aide du fichier manifeste de projet et de la commande 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

Dans l’exemple d’application (projet RuntimeStore), la commande suivante est utilisée :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

Pour que le runtime découvre le magasin de runtime, l’emplacement du magasin de runtime est ajouté à la variable d’environnement 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.

Modifier et placer le fichier de dépendances de l’hébergement au démarrageModify and place the hosting startup's dependencies file

Pour activer l’amélioration sans référence de package à l’amélioration, spécifiez les dépendances supplémentaires pour le runtime avec additionalDeps.To activate the enhancement without a package reference to the enhancement, specify additional dependencies to the runtime with additionalDeps. additionalDeps vous permet de :additionalDeps allows you to:

  • Étendre le graphe de la bibliothèque de l’application en fournissant un ensemble de fichiers .deps.json supplémentaires à fusionner avec le fichier .deps.json de l’application au démarrage.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.
  • Rendre l’assembly d’hébergement au démarrage détectable et chargeable.Make the hosting startup assembly discoverable and loadable.

L’approche recommandée pour la génération du fichier de dépendances supplémentaire est la suivante :The recommended approach for generating the additional dependencies file is to:

  1. Exécutez dotnet publish sur le fichier manifeste du magasin de runtime référencé dans la section précédente.Execute dotnet publish on the runtime store manifest file referenced in the previous section.
  2. Supprimez la référence au manifeste des bibliothèques et la section runtime du fichier .deps.json obtenu.Remove the manifest reference from libraries and the runtime section of the resulting .deps.json file.

Dans l’exemple de projet, la propriété store.manifest/1.0.0 est supprimée de la section targets et de la section 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"
    }
  }
}

Placez le fichier .deps.json à l’emplacement suivant :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} – Emplacement ajouté à la variable d’environnement DOTNET_ADDITIONAL_DEPS.{ADDITIONAL DEPENDENCIES PATH} – Location added to the DOTNET_ADDITIONAL_DEPS environment variable.
  • {SHARED FRAMEWORK NAME} – Framework partagé requis pour ce fichier de dépendances supplémentaire.{SHARED FRAMEWORK NAME} – Shared framework required for this additional dependencies file.
  • {SHARED FRAMEWORK VERSION} – Version minimale du framework partagé.{SHARED FRAMEWORK VERSION} – Minimum shared framework version.
  • {ENHANCEMENT ASSEMBLY NAME} – Nom de l’assembly de l’amélioration.{ENHANCEMENT ASSEMBLY NAME} – The enhancement's assembly name.

Dans l’exemple d’application (projet RuntimeStore), le fichier de dépendances supplémentaire est placé à l’emplacement suivant :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

Pour que le runtime découvre l’emplacement du magasin de runtime, l’emplacement du fichier de dépendances supplémentaire est ajouté à la variable d’environnement 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.

Dans l’exemple d’application (projet RuntimeStore), la génération du magasin de runtime et du fichier de dépendances supplémentaire s’effectue à l’aide d’un script PowerShell.In the sample app (RuntimeStore project), building the runtime store and generating the additional dependencies file is accomplished using a PowerShell script.

Pour obtenir des exemples montrant comment définir des variables d’environnement pour différents systèmes d’exploitation, consultez Utiliser plusieurs environnements.For examples of how to set environment variables for various operating systems, see Use multiple environments.

DéploiementDeployment

Pour faciliter le déploiement d’un hébergement au démarrage dans un environnement multimachine, l’exemple d’application crée un dossier deployment dans la sortie publiée qui contient les éléments suivants :To facilitate the deployment of a hosting startup in a multimachine environment, the sample app creates a deployment folder in published output that contains:

  • Le magasin de runtime d’hébergement au démarrage.The hosting startup runtime store.
  • Le fichier des dépendances de l’hébergement au démarrage.The hosting startup dependencies file.
  • Un script PowerShell qui crée ou modifie les variables ASPNETCORE_HOSTINGSTARTUPASSEMBLIES, DOTNET_SHARED_STORE et DOTNET_ADDITIONAL_DEPS pour prendre en charge l’activation de l’hébergement au démarrage.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. Exécutez ce script à partir d’une invite de commandes PowerShell d’administration sur le système de déploiement.Run the script from an administrative PowerShell command prompt on the deployment system.

Package NuGetNuGet package

Une amélioration de l’hébergement au démarrage peut être fournie dans un package NuGet.A hosting startup enhancement can be provided in a NuGet package. Le package a un attribut HostingStartup.The package has a HostingStartup attribute. Les types d’hébergement au démarrage fournis par le package sont mis à la disposition de l’application au moyen de l’une des approches suivantes :The hosting startup types provided by the package are made available to the app using either of the following approaches:

  • Le fichier projet de l’application améliorée crée une référence de package à l’hébergement au démarrage dans le fichier projet de l’application (référence au moment de la compilation).The enhanced app's project file makes a package reference for the hosting startup in the app's project file (a compile-time reference). Une fois la référence au moment de la compilation créée, l’assembly d’hébergement au démarrage et toutes ses dépendances sont ajoutés au fichier de dépendances de l’application ( .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). Cette approche s’applique à un package d’assembly d’hébergement au démarrage qui a été publié sur nuget.org.This approach applies to a hosting startup assembly package published to nuget.org.
  • Le fichier de dépendances de l’hébergement au démarrage est mis à la disposition de l’application améliorée de la façon décrite dans la section Magasin de runtime (sans référence au moment de la compilation).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).

Pour plus d’informations sur les packages NuGet et le magasin de runtime, consultez les rubriques suivantes :For more information on NuGet packages and the runtime store, see the following topics:

Dossier bin du projetProject bin folder

Une amélioration de l’hébergement au démarrage peut être fournie par un assembly déployé à partir du dossier bin dans l’application améliorée.A hosting startup enhancement can be provided by a bin-deployed assembly in the enhanced app. Les types d’hébergement au démarrage fournis par l’assembly sont mis à la disposition de l’application au moyen de l’une des approches suivantes :The hosting startup types provided by the assembly are made available to the app using one of the following approaches:

  • Le fichier projet de l’application améliorée crée une référence d’assembly à l’hébergement au démarrage (référence au moment de la compilation).The enhanced app's project file makes an assembly reference to the hosting startup (a compile-time reference). Une fois la référence au moment de la compilation créée, l’assembly d’hébergement au démarrage et toutes ses dépendances sont ajoutés au fichier de dépendances de l’application ( .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). Cette approche s’applique lorsque le scénario de déploiement appelle dans le but d’effectuer une référence au moment de la compilation à l’assembly d’hébergement au démarrage (fichier .dll) et en déplaçant l’assembly vers :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:
    • Le projet de consommation.The consuming project.
    • Un emplacement accessible par le projet de consommation.A location accessible by the consuming project.
  • Le fichier de dépendances de l’hébergement au démarrage est mis à la disposition de l’application améliorée de la façon décrite dans la section Magasin de runtime (sans référence au moment de la compilation).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).
  • Lors du ciblage de .NET Framework, l’assembly peut être chargé dans le contexte de charge par défaut, qui, sur .NET Framework, signifie que l’assembly se trouve à l’un des emplacements suivants :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:
    • Chemin de base de l’application – Le dossier bin dans lequel se trouve l’exécutable ( .exe) de l’application.Application base path – The bin folder where the app's executable (.exe) is located.
    • Global Assembly Cache (GAC) – Le GAC stocke des assemblys partagés par plusieurs applications .NET Framework.Global Assembly Cache (GAC) – The GAC stores assemblies that several .NET Framework apps share. Pour plus d'informations, voir Procédure : Installer un assembly dans le Global Assembly Cache dans la documentation de .NET Framework.For more information, see How to: Install an assembly into the global assembly cache in the .NET Framework documentation.

Exemple de codeSample code

L’exemple de code (Comment télécharger un exemple) montre des scénarios d’implémentation de l’hébergement au démarrage :The sample code (how to download) demonstrates hosting startup implementation scenarios:

  • Deux assemblys d’hébergement au démarrage (bibliothèques de classes) définissent chacun une paire clé-valeur de configuration en mémoire :Two hosting startup assemblies (class libraries) set a pair of in-memory configuration key-value pairs each:
    • Package NuGet (HostingStartupPackage)NuGet package (HostingStartupPackage)
    • Bibliothèque de classes (HostingStartupLibrary)Class library (HostingStartupLibrary)
  • Un hébergement au démarrage est activé à partir d’un assembly déployé depuis le magasin de runtime (StartupDiagnostics).A hosting startup is activated from a runtime store-deployed assembly (StartupDiagnostics). L’assembly ajoute deux middleware (intergiciels) à l’application au démarrage, qui fournissent des informations de diagnostic :The assembly adds two middlewares to the app at startup that provide diagnostic information on:
    • Services inscritsRegistered services
    • Adresse (schéma, hôte, chemin de base, chemin, chaîne de requête)Address (scheme, host, path base, path, query string)
    • Connexion (adresse IP distante, port distant, adresse IP locale, port local, certificat client)Connection (remote IP, remote port, local IP, local port, client certificate)
    • En-têtes de requêteRequest headers
    • Variables d’environnementEnvironment variables

Pour exécuter l’exemple :To run the sample:

Activation à partir d’un package NuGetActivation from a NuGet package

  1. Compilez le package HostingStartupPackage à l’aide de la commande dotnet pack.Compile the HostingStartupPackage package with the dotnet pack command.

  2. Ajoutez le nom de l’assembly du package HostingStartupPackage à la variable d’environnement ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.Add the package's assembly name of the HostingStartupPackage to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. Compilez et exécutez l’application.Compile and run the app. Une référence de package est présente dans l’application améliorée (référence au moment de la compilation).A package reference is present in the enhanced app (a compile-time reference). Un <PropertyGroup> dans le fichier projet de l’application spécifie la sortie du projet de package ( ../HostingStartupPackage/bin/Debug) comme source de package.A <PropertyGroup> in the app's project file specifies the package project's output (../HostingStartupPackage/bin/Debug) as a package source. L’application peut ainsi utiliser le package sans avoir à le charger sur nuget.org. Pour plus d’informations, consultez les remarques dans le fichier projet de l’application 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. Notez que les valeurs des clés de configuration de service affichées dans la page d’index correspondent aux valeurs définies par la méthode ServiceKeyInjection.Configure du package.Observe that the service configuration key values rendered by the Index page match the values set by the package's ServiceKeyInjection.Configure method.

Si vous modifiez le projet HostingStartupPackage et le recompilez, effacez les caches locaux du package NuGet pour vous assurer que HostingStartupApp reçoit le package mis à jour et pas un package périmé du cache local.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. Pour effacer les caches NuGet locaux, exécutez la commande dotnet nuget locals suivante :To clear the local NuGet caches, execute the following dotnet nuget locals command:

dotnet nuget locals all --clear

Activation à partir d’une bibliothèque de classesActivation from a class library

  1. Compilez la bibliothèque de classes HostingStartupLibrary à l’aide de la commande dotnet build.Compile the HostingStartupLibrary class library with the dotnet build command.

  2. Ajoutez le nom de l’assembly de la bibliothèque de classes HostingStartupLibrary à la variable d’environnement ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.Add the class library's assembly name of HostingStartupLibrary to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. À partir du dossier bin, déployez l’assembly de la bibliothèque de classes dans l’application en copiant le fichier HostingStartupLibrary.dll du résultat de la compilation de la bibliothèque de classes dans le dossier bin/Debug de l’application.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. Compilez et exécutez l’application.Compile and run the app. Dans le fichier projet de l’application, un <ItemGroup> référence l’assembly de la bibliothèque de classes ( .\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll) (référence au moment de la compilation).An <ItemGroup> in the app's project file references the class library's assembly (.\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll) (a compile-time reference). Pour plus d’informations, consultez les remarques dans le fichier projet de l’application 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. Notez que les valeurs des clés de configuration de service affichées dans la page d’index correspondent aux valeurs définies par la méthode ServiceKeyInjection.Configure de la bibliothèque de classes.Observe that the service configuration key values rendered by the Index page match the values set by the class library's ServiceKeyInjection.Configure method.

Activation à partir d’un assembly déployé depuis le magasin de runtimeActivation from a runtime store-deployed assembly

  1. Le projet StartupDiagnostics utilise PowerShell pour modifier le fichier StartupDiagnostics.deps.json associé.The StartupDiagnostics project uses PowerShell to modify its StartupDiagnostics.deps.json file. PowerShell est installé par défaut sur Windows à compter de Windows 7 SP1 et de Windows Server 2008 R2 SP1.PowerShell is installed by default on Windows starting with Windows 7 SP1 and Windows Server 2008 R2 SP1. Pour obtenir PowerShell sur d’autres plateformes, consultez Installation de Windows PowerShell.To obtain PowerShell on other platforms, see Installing Windows PowerShell.
  2. Exécutez le script build.ps1 du dossier RuntimeStore.Execute the build.ps1 script in the RuntimeStore folder. Le script :The script:
    • Génère le package StartupDiagnostics.Generates the StartupDiagnostics package.
    • Génère le magasin de runtime de StartupDiagnostics dans le dossier store.Generates the runtime store for StartupDiagnostics in the store folder. La commande dotnet store du script utilise l’identificateur de runtime (RID) win7-x64 pour un hébergement au démarrage déployé sur Windows.The dotnet store command in the script uses the win7-x64 runtime identifier (RID) for a hosting startup deployed to Windows. Si vous fournissez l’hébergement au démarrage pour un autre runtime, spécifiez l’identificateur du runtime à la ligne 37 du script.When providing the hosting startup for a different runtime, substitute the correct RID on line 37 of the script.
    • Génère additionalDeps de StartupDiagnostics dans le dossier additionalDeps/shared/Microsoft.AspNetCore.App/{Shared Framework Version}/ .Generates the additionalDeps for StartupDiagnostics in the additionalDeps/shared/Microsoft.AspNetCore.App/{Shared Framework Version}/ folder.
    • Place le fichier deploy.ps1 dans le dossier deployment.Places the deploy.ps1 file in the deployment folder.
  3. Exécutez le script deploy.ps1 du dossier Deployment.Run the deploy.ps1 script in the deployment folder. Le script ajoute :The script appends:
    • StartupDiagnostics à la variable d’environnement ASPNETCORE_HOSTINGSTARTUPASSEMBLIES.StartupDiagnostics to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.
    • Le chemin des dépendances d’hébergement au démarrage à la variable d’environnement DOTNET_ADDITIONAL_DEPS.The hosting startup dependencies path to the DOTNET_ADDITIONAL_DEPS environment variable.
    • Le chemin du magasin de runtime à la variable d’environnement DOTNET_SHARED_STORE.The runtime store path to the DOTNET_SHARED_STORE environment variable.
  4. Exécutez l’exemple d’application.Run the sample app.
  5. Demandez le point de terminaison /services pour voir les services inscrits de l’application.Request the /services endpoint to see the app's registered services. Demandez le point de terminaison /diag pour voir les informations de diagnostic.Request the /diag endpoint to see the diagnostic information.