ASP.NET Core でホスティング スタートアップ アセンブリを使用するUse hosting startup assemblies in ASP.NET Core

作成者: Pavel KrymetsBy Pavel Krymets

IHostingStartup (ホスティング スタートアップ) の実装を使うと、外部アセンブリからの起動時にアプリに拡張機能を追加できます。An IHostingStartup (hosting startup) implementation adds enhancements to an app at startup from an external assembly. たとえば、外部ライブラリではホスティング スタートアップ実装を使用して、追加の構成プロバイダーまたはサービスをアプリに提供できます。For example, an external library can use a hosting startup implementation to provide additional configuration providers or services to an app.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

HostingStartup 属性HostingStartup attribute

HostingStartup 属性は、実行時にアクティブ化されるホスティング スタートアップ アセンブリが存在することを示しています。A HostingStartup attribute indicates the presence of a hosting startup assembly to activate at runtime.

入力アセンブリまたは Startup クラスを含むアセンブリは、HostingStartup 属性について自動的にスキャンされます。The entry assembly or the assembly containing the Startup class is automatically scanned for the HostingStartup attribute. HostingStartup 属性を検索するアセンブリの一覧は、WebHostDefaults.HostingStartupAssembliesKey 内の構成からランタイム時に読み込まれます。The list of assemblies to search for HostingStartup attributes is loaded at runtime from configuration in the WebHostDefaults.HostingStartupAssembliesKey. 検出から除外されるアセンブリの一覧は、WebHostDefaults.HostingStartupExcludeAssembliesKey から読み込まれます。The list of assemblies to exclude from discovery is loaded from the WebHostDefaults.HostingStartupExcludeAssembliesKey.

次に例では、ホスティング スタートアップ アセンブリの名前空間は StartupEnhancement となります。In the following example, the namespace of the hosting startup assembly is StartupEnhancement. ホスティング スタートアップ コードを含むクラスは StartupEnhancementHostingStartup です。The class containing the hosting startup code is StartupEnhancementHostingStartup:

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

HostingStartup 属性は、通常、ホスティング スタートアップ アセンブリの IHostingStartup 実装クラス ファイル内に置かれます。The HostingStartup attribute is typically located in the hosting startup assembly's IHostingStartup implementation class file.

読み込まれたホスティング スタートアップ アセンブリを見つけるDiscover loaded hosting startup assemblies

読み込まれたホスティング スタートアップ アセンブリを検出するには、ログ記録を有効にしてアプリのログを確認します。To discover loaded hosting startup assemblies, enable logging and check the app's logs. アセンブリの読み込み時に発生したエラーがログ記録されます。Errors that occur when loading assemblies are logged. 読み込まれたホスティング スタートアップ アセンブリは、デバッグ レベルでログ記録され、すべてのエラーが記録されます。Loaded hosting startup assemblies are logged at the Debug level, and all errors are logged.

ホスティング スタートアップ アセンブリの自動読み込みを無効にするDisable automatic loading of hosting startup assemblies

ホスティング スタートアップ アセンブリの自動読み込みを無効にするには、次の方法のいずれかを使用します。To disable automatic loading of hosting startup assemblies, use one of the following approaches:

  • すべてのホスティング スタートアップ アセンブリの読み込みを回避するには、次のいずれかを true または 1 に設定します。To prevent all hosting startup assemblies from loading, set one of the following to true or 1:

    • [ホスティング スタートアップを回避する] ホスト構成設定。Prevent Hosting Startup host configuration setting:

      public static IHostBuilder CreateHostBuilder(string[] args) =>
          Host.CreateDefaultBuilder(args)
              .ConfigureWebHostDefaults(webBuilder =>
              {
                  webBuilder.UseSetting(
                          WebHostDefaults.PreventHostingStartupKey, "true")
                      .UseStartup<Startup>();
              });
      
    • ASPNETCORE_PREVENTHOSTINGSTARTUP 環境変数。ASPNETCORE_PREVENTHOSTINGSTARTUP environment variable.

  • 特定のホスティング スタートアップ アセンブリの読み込みを回避するには、次に示すいずれかを、起動時に除外するホスティング スタートアップ アセンブリを示すセミコロンで区切られた文字列に設定します。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:

    • [Hosting Startup Exclude Assemblies](除外するホスティング スタートアップ アセンブリ) ホスト構成設定。Hosting Startup Exclude Assemblies host configuration setting:

      public static IHostBuilder CreateHostBuilder(string[] args) =>
          Host.CreateDefaultBuilder(args)
              .ConfigureWebHostDefaults(webBuilder =>
              {
                  webBuilder.UseSetting(
                          WebHostDefaults.HostingStartupExcludeAssembliesKey, 
                          "{ASSEMBLY1;ASSEMBLY2; ...}")
                      .UseStartup<Startup>();
              });
      
    • ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES 環境変数。ASPNETCORE_HOSTINGSTARTUPEXCLUDEASSEMBLIES environment variable.

ホスト構成設定と環境変数が両方とも設定されている場合は、ホスト設定によって動作が制御されます。If both the host configuration setting and the environment variable are set, the host setting controls the behavior.

ホスト設定または環境変数を使用してホスティング スタートアップ アセンブリを無効にすると、アセンブリがグローバルに無効になり、場合によってはアプリのいくつかの属性も無効になります。Disabling hosting startup assemblies using the host setting or environment variable disables the assembly globally and may disable several characteristics of an app.

ProjectProject

次のいずれかの種類のプロジェクトを使用して、ホスティング スタートアップを作成します。Create a hosting startup with either of the following project types:

クラス ライブラリClass library

クラス ライブラリでは、ホスティング スタートアップの拡張機能を提供できます。A hosting startup enhancement can be provided in a class library. このライブラリには HostingStartup 属性が含まれています。The library contains a HostingStartup attribute.

サンプル コードには、Razor Pages アプリ、 HostingStartupApp 、クラス ライブラリ、 HostingStartupLibrary が含まれています。The sample code includes a Razor Pages app, HostingStartupApp , and a class library, HostingStartupLibrary. クラス ライブラリには次のものが含まれています。The class library:

  • IHostingStartup を実装するホスティング スタートアップ クラス ServiceKeyInjectionContains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection では、メモリ内の構成プロバイダー (AddInMemoryCollection) を使用して、サービスの文字列のペアがアプリの構成に追加されます。ServiceKeyInjection adds a pair of service strings to the app's configuration using the in-memory configuration provider (AddInMemoryCollection).
  • ホスティング スタートアップの名前空間とクラスを識別する HostingStartup 属性。Includes a HostingStartup attribute that identifies the hosting startup's namespace and class.

ServiceKeyInjection クラスの Configure メソッドでは、IWebHostBuilder を使ってアプリに拡張機能を追加します。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);
            });
        }
    }
}

アプリのインデックス ページでは、クラス ライブラリのホスティング スタートアップ アセンブリによって設定された 2 つのキーの構成値が読み取られて表示されます。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()
    {
    }
}

サンプル コード には、別のホスティング スタートアップ HostingStartupPackage を提供する NuGet パッケージ プロジェクトも含まれています。The sample code also includes a NuGet package project that provides a separate hosting startup, HostingStartupPackage. パッケージには、前に説明したクラス ライブラリと同じ特性があります。The package has the same characteristics of the class library described earlier. パッケージには次のものが含まれます。The package:

  • IHostingStartup を実装するホスティング スタートアップ クラス ServiceKeyInjectionContains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection では、アプリの構成にサービス文字列のペアが追加されます。ServiceKeyInjection adds a pair of service strings to the app's configuration.
  • 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);
            });
        }
    }
}

アプリのインデックス ページでは、パッケージのホスティング スタートアップ アセンブリによって設定された 2 つのキーの構成値が読み取られて表示されます。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()
    {
    }
}

エントリ ポイントのないコンソール アプリConsole app without an entry point

このアプローチは、.NET Core アプリでのみ利用でき、.NET Framework では利用できません。This approach is only available for .NET Core apps, not .NET Framework.

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. コンソール アプリを発行すると、ランタイム ストアから使用できるホスティング スタートアップ アセンブリが生成されます。Publishing the console app produces a hosting startup assembly that can be consumed from the runtime store.

このプロセスにおいてエントリ ポイントのないコンソール アプリが使用される理由は、次のとおりです。A console app without an entry point is used in this process because:

  • ホスティング スタートアップ アセンブリ内のホスティング スタートアップを使用するには、依存関係ファイルが必要です。A dependencies file is required to consume the hosting startup in the hosting startup assembly. 依存関係ファイルは、ライブラリではなくアプリを発行することによって生成される、実行可能なアプリ資産です。A dependencies file is a runnable app asset that's produced by publishing an app, not a library.
  • ランタイム パッケージ ストア にライブラリを直接追加することはできません。それには、共有ランタイムを対象とする実行可能なプロジェクトが必要です。A library can't be added directly to the runtime package store, which requires a runnable project that targets the shared runtime.

動的ホスティング スタートアップを作成する場合:In the creation of a dynamic hosting startup:

  • 次のようなエントリ ポイントがないコンソール アプリからホスティング スタートアップ アセンブリが作成されます。A hosting startup assembly is created from the console app without an entry point that:
    • IHostingStartup の実装を含むクラスを含んでいる。Includes a class that contains the IHostingStartup implementation.
    • IHostingStartup 実装クラスを識別するための HostingStartup 属性を含んでいる。Includes a HostingStartup attribute to identify the IHostingStartup implementation class.
  • ホスティング スタートアップの依存関係を取得するには、コンソール アプリを発行します。The console app is published to obtain the hosting startup's dependencies. コンソール アプリを発行すると、その結果として、依存関係ファイルから未使用の依存関係が切り捨てられます。A consequence of publishing the console app is that unused dependencies are trimmed from the dependencies file.
  • ホスティング スタートアップ アセンブリのランタイムの場所を設定するために、依存関係ファイルが変更されます。The dependencies file is modified to set the runtime location of the hosting startup assembly.
  • ホスティング スタートアップ アセンブリとその依存関係ファイルは、ランタイム パッケージ ストアに配置されます。The hosting startup assembly and its dependencies file is placed into the runtime package store. ホスティング スタートアップ アセンブリとその依存関係ファイルを検出する場合、それらは環境変数のペアに記載されています。To discover the hosting startup assembly and its dependencies file, they're listed in a pair of environment variables.

コンソール アセンブリでは、Microsoft.AspNetCore.Hosting.Abstractions パッケージが参照されます。The console app references the Microsoft.AspNetCore.Hosting.Abstractions package:

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

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

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

</Project>

HostingStartup 属性を使うと、IWebHost のビルド時に、読み込みと実行のための IHostingStartup の実装としてクラスが識別されます。A HostingStartup attribute identifies a class as an implementation of IHostingStartup for loading and execution when building the IWebHost. 次の例では、名前空間は StartupEnhancement、クラスは StartupEnhancementHostingStartup です。In the following example, the namespace is StartupEnhancement, and the class is StartupEnhancementHostingStartup:

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

クラスは IHostingStartup を実装しています。A class implements IHostingStartup. このクラスの Configure メソッドでは、IWebHostBuilder を使ってアプリに拡張機能を追加します。The class's Configure method uses an IWebHostBuilder to add enhancements to an app. ホスティング スタートアップ アセンブリ内の IHostingStartup.Configure は、ユーザー コード内の Startup.Configure よりも前にランタイムによって呼び出されます。このため、ホスティング スタートアップ アセンブリによって提供されるすべての構成をユーザー コードで上書きすることができます。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.
        }
    }
}

IHostingStartup プロジェクトのビルド時に、依存関係ファイル ( .deps.json ) によってアセンブリの runtime の場所が bin フォルダーに設定されます。When building an IHostingStartup project, the dependencies file ( .deps.json ) sets the runtime location of the assembly to the bin folder:

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

ファイルの一部のみが示されています。Only part of the file is shown. 例のアセンブリ名は StartupEnhancement です。The assembly name in the example is StartupEnhancement.

ホスティング スタートアップによって指定される構成Configuration provided by the hosting startup

ホスティング スタートアップの構成、アプリの構成のどちらを優先させるかによって、2 つの異なる方法で構成を処理できます。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. アプリの ConfigureAppConfiguration デリゲートを実行した後で ConfigureAppConfiguration を使って構成を読み込み、アプリに構成を指定します。Provide configuration to the app using ConfigureAppConfiguration to load the configuration after the app's ConfigureAppConfiguration delegates execute. この方法を使うと、ホスティング スタートアップの構成の方がアプリの構成よりも優先されます。Hosting startup configuration takes priority over the app's configuration using this approach.
  2. アプリの ConfigureAppConfiguration デリゲートを実行する前に UseConfiguration を使って構成を読み込み、アプリに構成を指定します。Provide configuration to the app using UseConfiguration to load the configuration before the app's ConfigureAppConfiguration delegates execute. この方法を使うと、アプリの構成値の方がホスティング スタートアップにより指定されるものよりも優先されます。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);
    }
}

ホスティング スタートアップ アセンブリを指定するSpecify the hosting startup assembly

クラス ライブラリまたはコンソール アプリのいずれかで提供されるホスティング スタートアップの場合は、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. 環境変数はアセンブリのセミコロン区切りのリストです。The environment variable is a semicolon-delimited list of assemblies.

ホスティング スタートアップ アセンブリのみが、HostingStartup 属性に対してスキャンされます。Only hosting startup assemblies are scanned for the HostingStartup attribute. サンプル アプリ HostingStartupApp では、前述したホスティング スタートアップを検出するために、環境変数が次の値に設定されています。For the sample app, HostingStartupApp , to discover the hosting startups described earlier, the environment variable is set to the following value:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

また、ホスティング スタートアップ アセンブリは、[ホスティング スタートアップ アセンブリ] のホスト構成設定を使用して設定することもできます。A hosting startup assembly can also be set using the Hosting Startup Assemblies host configuration setting:

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

複数のホスティング スタートアップ アセンブリが存在する場合、それらの Configure メソッドは、アセンブリが一覧表示されている順序で実行されます。When multiple hosting startup assembles are present, their Configure methods are executed in the order that the assemblies are listed.

アクティベーションActivation

ホスティング スタートアップのアクティブ化のオプションは次のとおりです。Options for hosting startup activation are:

  • ランタイム ストア:アクティブ化では、アクティブ化に関するコンパイル時参照を必要としません。Runtime store: Activation doesn't require a compile-time reference for activation. サンプル アプリでは、ホスティング スタートアップ アセンブリおよび依存関係のファイルが deployment フォルダーに配置されています。これにより、複数のコンピューターから成る環境でのホスティング スタートアップの配置が容易になります。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. deployment フォルダーには、ホスティングスタートアップが有効になるように配置システム上で環境変数を作成および変更する PowerShell スクリプトも含まれています。The deployment folder also includes a PowerShell script that creates or modifies environment variables on the deployment system to enable the hosting startup.
  • アクティブ化で必須のコンパイル時参照Compile-time reference required for activation

ランタイム ストアRuntime store

ホスティング スタートアップ実装は、ランタイム ストアに置かれます。The hosting startup implementation is placed in the runtime store. アセンブリへのコンパイル時参照は、機能強化されたアプリで必須ではありません。A compile-time reference to the assembly isn't required by the enhanced app.

ホスティング スタートアップをビルドした後、プロジェクトのマニフェスト ファイルと 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

サンプル アプリ ( RuntimeStore プロジェクト) では、次のコマンドを使用します。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

ランタイムでランタイム ストアを検出できるように、ランタイム ストアの場所を環境変数 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.

ホスティング スタートアップの依存関係ファイルを変更して配置するModify and place the hosting startup's dependencies file

拡張機能へのパッケージ参照なしで拡張機能をアクティブ化するには、additionalDeps を使用してランタイムに追加の依存関係を指定します。To activate the enhancement without a package reference to the enhancement, specify additional dependencies to the runtime with additionalDeps. additionalDeps を使用すると、次のことを実行できます。additionalDeps allows you to:

  • スタートアップ時にアプリの独自の .deps.json ファイルとマージさせる追加の .deps.json ファイルのセットを指定することで、アプリのライブラリのグラフを拡張します。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.
  • ホスティング スタートアップ アセンブリを検出可能および読み込み可能にします。Make the hosting startup assembly discoverable and loadable.

追加の依存関係ファイルを生成するために推奨される方法は次のとおりです。The recommended approach for generating the additional dependencies file is to:

  1. 前のセクションで参照したランタイム ストアのマニフェスト ファイルに対して dotnet publish を実行します。Execute dotnet publish on the runtime store manifest file referenced in the previous section.
  2. ライブラリと、結果として得られる deps.json ファイルの runtime セクションから、マニフェスト参照を削除します。Remove the manifest reference from libraries and the runtime section of the resulting .deps.json file.

プロジェクトの例では、targetslibraries セクションから store.manifest/1.0.0 プロパティが削除されます。In the example project, the store.manifest/1.0.0 property is removed from the targets and libraries section:

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

次の場所に .deps.json ファイルを配置します。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}:DOTNET_ADDITIONAL_DEPS 環境変数に追加される場所。{ADDITIONAL DEPENDENCIES PATH}: Location added to the DOTNET_ADDITIONAL_DEPS environment variable.
  • {SHARED FRAMEWORK NAME}:この追加の依存関係ファイルに必要な共有フレームワーク。{SHARED FRAMEWORK NAME}: Shared framework required for this additional dependencies file.
  • {SHARED FRAMEWORK VERSION}:共有フレームワークの最小バージョン。{SHARED FRAMEWORK VERSION}: Minimum shared framework version.
  • {ENHANCEMENT ASSEMBLY NAME}:拡張機能のアセンブリ名。{ENHANCEMENT ASSEMBLY NAME}: The enhancement's assembly name.

サンプル アプリ ( RuntimeStore プロジェクト) では、追加の依存関係ファイルは以下の場所に配置されます。In the sample app ( RuntimeStore project), the additional dependencies file is placed into the following location:

deployment/additionalDeps/shared/Microsoft.AspNetCore.App/3.0.0/StartupDiagnostics.deps.json

ランタイムでランタイム ストアの場所を検出できるように、追加の依存関係ファイルの場所が環境変数 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.

サンプル アプリ ( RuntimeStore プロジェクト) では、 PowerShell スクリプトを使用してランタイム ストアのビルドと追加の依存関係ファイルの生成を行います。In the sample app ( RuntimeStore project), building the runtime store and generating the additional dependencies file is accomplished using a PowerShell script.

さまざまなオペレーティング システムの環境変数を設定する方法の例については、複数の環境の使用に関するページを参照してください。For examples of how to set environment variables for various operating systems, see Use multiple environments.

配置Deployment

サンプル アプリでは、複数のコンピューターから成る環境へのホスティング スタートアップの配置を容易にするために、発行された出力内に、次を含む deployment フォルダーが作成されます。To facilitate the deployment of a hosting startup in a multimachine environment, the sample app creates a deployment folder in published output that contains:

  • ホスティング スタートアップのランタイム ストア。The hosting startup runtime store.
  • ホスティング スタートアップの依存関係ファイル。The hosting startup dependencies file.
  • ホスティング スタートアップのアクティブ化をサポートできるように、ASPNETCORE_HOSTINGSTARTUPASSEMBLIESDOTNET_SHARED_STOREDOTNET_ADDITIONAL_DEPS を作成および変更する PowerShell スクリプト。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. このスクリプトは、配置システム上の PowerShell 管理用コマンド プロンプトから実行します。Run the script from an administrative PowerShell command prompt on the deployment system.

NuGet パッケージNuGet package

NuGet パッケージでは、ホスティング スタートアップの拡張機能を提供できます。A hosting startup enhancement can be provided in a NuGet package. このパッケージには HostingStartup 属性があります。The package has a HostingStartup attribute. このパッケージで提供される種類のホスティング スタートアップは、次のアプローチのいずれかを使用してアプリで利用できるようになります。The hosting startup types provided by the package are made available to the app using either of the following approaches:

  • 機能強化されたアプリのプロジェクト ファイルでは、アプリのプロジェクト ファイル内のホスティング スタートアップに対するパッケージ参照 (コンパイル時参照) が作成されます。The enhanced app's project file makes a package reference for the hosting startup in the app's project file (a compile-time reference). コンパイル時参照を適用すると、ホスティング スタートアップ アセンブリとその依存関係のすべてが、アプリの依存関係ファイル ( .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 ). このアプローチは、nuget.org に発行されるホスティング スタートアップ アセンブリ パッケージに適用されます。This approach applies to a hosting startup assembly package published to nuget.org.
  • ホスティング スタートアップの依存関係ファイルは、「ランタイム ストア」のセクションで説明にしたように (コンパイル参照がない場合)、機能強化されたアプリで利用できるようになります。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).

NuGet パッケージとランタイム ストアの詳細については、次のトピックを参照してください。For more information on NuGet packages and the runtime store, see the following topics:

プロジェクトの bin フォルダーProject bin folder

ホスティング スタートアップの拡張機能は、機能強化されたアプリ内の bin 配置アセンブリによって提供できます。A hosting startup enhancement can be provided by a bin -deployed assembly in the enhanced app. このアセンブリで提供される種類のホスティング スタートアップは、次のアプローチのいずれかを使用してアプリで利用できるようになります。The hosting startup types provided by the assembly are made available to the app using one of the following approaches:

  • 機能強化されたアプリのプロジェクト ファイルでは、ホスティング スタートアップへのアセンブリ参照 (コンパイル時参照) が作成されます。The enhanced app's project file makes an assembly reference to the hosting startup (a compile-time reference). コンパイル時参照を適用すると、ホスティング スタートアップ アセンブリとその依存関係のすべてが、アプリの依存関係ファイル ( .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 ). この手法は、展開シナリオによって、ホスティング スタートアップのアセンブリ ( .dll ファイル) に対してコンパイル時参照を作成し、次のいずれかにそのアセンブリを移動させることが要請される場合に適用されます。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:
    • 使用するプロジェクト。The consuming project.
    • 使用するプロジェクトでアクセスできる場所。A location accessible by the consuming project.
  • ホスティング スタートアップの依存関係ファイルは、「ランタイム ストア」のセクションで説明にしたように (コンパイル参照がない場合)、機能強化されたアプリで利用できるようになります。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).
  • .NET Framework を対象にするとき、アセンブリは既定の読み込みコンテキストで読み込み可能です。これは、.NET Framework の場合、アセンブリが次のいずれかの場所にあることを意味します。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:
    • アプリケーション ベース パス:アプリの実行可能ファイル ( .exe ) が置かれている bin フォルダー。Application base path: The bin folder where the app's executable ( .exe ) is located.
    • グローバル アセンブリ キャッシュ (GAC):GAC には、複数の .NET Framework アプリで共有されるアセンブリが格納されています。Global Assembly Cache (GAC): The GAC stores assemblies that several .NET Framework apps share. 詳細については、「方法: アセンブリをグローバル アセンブリ キャッシュにインストールする」を参照してください。これは .NET Framework ドキュメントにあります。For more information, see How to: Install an assembly into the global assembly cache in the .NET Framework documentation.

サンプル コードSample code

サンプル コード (ダウンロードする方法) では、ホスティング スタートアップ実装のシナリオを示します。The sample code (how to download) demonstrates hosting startup implementation scenarios:

  • 2 つのホスティング スタートアップ アセンブリ (クラス ライブラリ) ではそれぞれ、メモリ内の構成のキーと値のペアの組が設定されます。Two hosting startup assemblies (class libraries) set a pair of in-memory configuration key-value pairs each:
    • NuGet パッケージ ( HostingStartupPackage )NuGet package ( HostingStartupPackage )
    • クラス ライブラリ ( HostingStartupLibrary )Class library ( HostingStartupLibrary )
  • ホスティング スタートアップは、ランタイム ストア配置アセンブリ ( StartupDiagnostics ) からアクティブ化されます。A hosting startup is activated from a runtime store-deployed assembly ( StartupDiagnostics ). このアセンブリによってスタートアップ時に 2 つのミドルウェアがアプリに追加され、これにより診断情報が提供されます。The assembly adds two middlewares to the app at startup that provide diagnostic information on:
    • 登録サービスRegistered services
    • アドレス (スキーム、ホスト、パス ベース、パス、クエリ文字列)Address (scheme, host, path base, path, query string)
    • 接続 (リモート IP、リモート ポート、ローカル IP、ローカル ポート、クライアント証明書)Connection (remote IP, remote port, local IP, local port, client certificate)
    • 要求ヘッダーRequest headers
    • 環境変数Environment variables

サンプルを実行するにはTo run the sample:

NuGet パッケージからのアクティブ化Activation from a NuGet package

  1. dotnet pack コマンドを使用して HostingStartupPackage パッケージをコンパイルします。Compile the HostingStartupPackage package with the dotnet pack command.

  2. HostingStartupPackage のパッケージのアセンブリ名を ASPNETCORE_HOSTINGSTARTUPASSEMBLIES 環境変数に追加します。Add the package's assembly name of the HostingStartupPackage to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. アプリをコンパイルして実行します。Compile and run the app. 機能拡張されたアプリにはパッケージ参照 (コンパイル時参照) が存在します。A package reference is present in the enhanced app (a compile-time reference). アプリのプロジェクト ファイル内の <PropertyGroup> では、パッケージ プロジェクトの出力 ( ../HostingStartupPackage/Bin/debug ) がパッケージ ソースとして指定されます。A <PropertyGroup> in the app's project file specifies the package project's output ( ../HostingStartupPackage/bin/Debug ) as a package source. これにより、nuget.org にパッケージをアップロードすることなく、アプリによりパッケージが使用されるようになります。詳細については、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. インデックス ページで表示されるサービス構成キー値が、パッケージの ServiceKeyInjection.Configure メソッドによって設定された値と一致することを確認します。Observe that the service configuration key values rendered by the Index page match the values set by the package's ServiceKeyInjection.Configure method.

HostingStartupPackage プロジェクトに変更を加えてそれをコンパイルする場合は、ローカル キャッシュから、古いパッケージではなく更新されたパッケージが、 HostingStartupApp によって確実に受信されるように、ローカルの NuGet パッケージ キャッシュをクリアします。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. ローカルの NuGet キャッシュをクリアするには、次の dotnet nuget locals コマンドを実行します。To clear the local NuGet caches, execute the following dotnet nuget locals command:

dotnet nuget locals all --clear

クラス ライブラリからのアクティブ化Activation from a class library

  1. dotnet build コマンドを使用して HostingStartupLibrary クラス ライブラリをコンパイルします。Compile the HostingStartupLibrary class library with the dotnet build command.

  2. HostingStartupLibrary のクラス ライブラリのアセンブリ名を ASPNETCORE_HOSTINGSTARTUPASSEMBLIES 環境変数に追加します。Add the class library's assembly name of HostingStartupLibrary to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. クラス ライブラリのアセンブリをアプリに bin 配置するには、クラス ライブラリのコンパイルされた出力からアプリの bin/Debug フォルダーに HostingStartupLibrary.dll ファイルをコピーします。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. アプリをコンパイルして実行します。Compile and run the app. アプリのプロジェクト ファイル内の <ItemGroup> により、クラス ライブラリのアセンブリ ( .\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll ) が参照されます (コンパイル時参照)。An <ItemGroup> in the app's project file references the class library's assembly ( .\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll ) (a compile-time reference). 詳細については、HostingStartupApp のプロジェクト ファイル内の注を参照してください。For more information, see the notes in the HostingStartupApp's project file.

    <ItemGroup>
      <Reference Include=".\\bin\\Debug\\netcoreapp3.0\\HostingStartupLibrary.dll">
        <HintPath>.\bin\Debug\netcoreapp3.0\HostingStartupLibrary.dll</HintPath>
        <SpecificVersion>False</SpecificVersion> 
      </Reference>
    </ItemGroup>
    
  5. インデックス ページで表示されるサービス構成キー値が、クラス ライブラリの ServiceKeyInjection.Configure メソッドによって設定された値と一致することを確認します。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 from a runtime store-deployed assembly

  1. StartupDiagnostics プロジェクトでは、 PowerShell を使用して、その StartupDiagnostics.deps.json ファイルを変更します。The StartupDiagnostics project uses PowerShell to modify its StartupDiagnostics.deps.json file. 既定では、PowerShell は Windows 7 SP1 と Windows Server 2008 R2 SP1 以降の Windows 上にインストールされます。PowerShell is installed by default on Windows starting with Windows 7 SP1 and Windows Server 2008 R2 SP1. 他のプラットフォームで PowerShell を取得するには、「PowerShell のさまざまなバージョンのインストール」を参照してください。To obtain PowerShell on other platforms, see Installing various versions of PowerShell.
  2. RuntimeStore フォルダーにある build.ps1 スクリプトを実行します。Execute the build.ps1 script in the RuntimeStore folder. スクリプトでは次のことが行われます。The script:
    • obj\packages フォルダーに StartupDiagnostics パッケージが生成されます。Generates the StartupDiagnostics package in the obj\packages folder.
    • store フォルダー内に StartupDiagnostics 用のランタイム ストアが生成されます。Generates the runtime store for StartupDiagnostics in the store folder. スクリプト内の dotnet store コマンドでは、Windows に展開されているホスティング スタートアップの win7-x64ランタイム識別子 (RID) が使用されます。The dotnet store command in the script uses the win7-x64 runtime identifier (RID) for a hosting startup deployed to Windows. 別のランタイムに対してホスティング スタートアップを指定する場合は、スクリプトの 37 行目を適切な RID に置き換えます。When providing the hosting startup for a different runtime, substitute the correct RID on line 37 of the script. StartupDiagnostics のランタイム ストアは、後で、アセンブリが使用されるコンピューター上のユーザーまたはシステムのランタイム ストアに移動されます。The runtime store for StartupDiagnostics would later be moved to the user's or system's runtime store on the machine where the assembly will be consumed. StartupDiagnostics アセンブリのユーザー ランタイム ストアのインストール場所は、 .dotnet/store/x64/netcoreapp3.0/startupdiagnostics/1.0.0/lib/netcoreapp3.0/StartupDiagnostics.dll です。The user runtime store install location for the StartupDiagnostics assembly is .dotnet/store/x64/netcoreapp3.0/startupdiagnostics/1.0.0/lib/netcoreapp3.0/StartupDiagnostics.dll.
    • additionalDeps フォルダーに StartupDiagnosticsadditionalDeps が生成されます。Generates the additionalDeps for StartupDiagnostics in the additionalDeps folder. 追加の依存関係は、後でユーザーまたはシステムの追加の依存関係に移動されます。The additional dependencies would later be moved to the user's or system's additional dependencies. ユーザーの StartupDiagnostics に関する追加の依存関係のインストール場所は、 .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/3.0.0/StartupDiagnostics.deps.json です。The user StartupDiagnostics additional dependencies install location is .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/3.0.0/StartupDiagnostics.deps.json.
    • deploy.ps1 ファイルが deployment フォルダーに配置されます。Places the deploy.ps1 file in the deployment folder.
  3. deployment フォルダーにある deploy.ps1 スクリプトを実行します。Run the deploy.ps1 script in the deployment folder. スクリプトでは以下のものが追加されます。The script appends:
    • StartupDiagnosticsASPNETCORE_HOSTINGSTARTUPASSEMBLIES 環境変数に。StartupDiagnostics to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.
    • (RuntimeStore プロジェクトの deployment フォルダーにある) ホスティング スタートアップの依存関係のパスが、DOTNET_ADDITIONAL_DEPS 環境変数に。The hosting startup dependencies path (in the RuntimeStore project's deployment folder) to the DOTNET_ADDITIONAL_DEPS environment variable.
    • (RuntimeStore プロジェクトの deployment フォルダーにある) ランタイム ストアのパスが、DOTNET_SHARED_STORE 環境変数に。The runtime store path (in the RuntimeStore project's deployment folder) to the DOTNET_SHARED_STORE environment variable.
  4. サンプル アプリを実行します。Run the sample app.
  5. /services エンドポイントを要求して、アプリの登録サービスを参照します。Request the /services endpoint to see the app's registered services. /diag エンドポイントを要求して、診断情報を参照します。Request the /diag endpoint to see the diagnostic information.

IHostingStartup (ホスティング スタートアップ) の実装を使うと、外部アセンブリからの起動時にアプリに拡張機能を追加できます。An IHostingStartup (hosting startup) implementation adds enhancements to an app at startup from an external assembly. たとえば、外部ライブラリではホスティング スタートアップ実装を使用して、追加の構成プロバイダーまたはサービスをアプリに提供できます。For example, an external library can use a hosting startup implementation to provide additional configuration providers or services to an app.

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

HostingStartup 属性HostingStartup attribute

HostingStartup 属性は、実行時にアクティブ化されるホスティング スタートアップ アセンブリが存在することを示しています。A HostingStartup attribute indicates the presence of a hosting startup assembly to activate at runtime.

入力アセンブリまたは Startup クラスを含むアセンブリは、HostingStartup 属性について自動的にスキャンされます。The entry assembly or the assembly containing the Startup class is automatically scanned for the HostingStartup attribute. HostingStartup 属性を検索するアセンブリの一覧は、WebHostDefaults.HostingStartupAssembliesKey 内の構成からランタイム時に読み込まれます。The list of assemblies to search for HostingStartup attributes is loaded at runtime from configuration in the WebHostDefaults.HostingStartupAssembliesKey. 検出から除外されるアセンブリの一覧は、WebHostDefaults.HostingStartupExcludeAssembliesKey から読み込まれます。The list of assemblies to exclude from discovery is loaded from the WebHostDefaults.HostingStartupExcludeAssembliesKey. 詳細については、「Web ホスト: ホスティング スタートアップ アセンブリWeb ホスト: 除外するホスティング スタートアップ アセンブリFor more information, see Web Host: Hosting Startup Assemblies and Web Host: Hosting Startup Exclude Assemblies.

次に例では、ホスティング スタートアップ アセンブリの名前空間は StartupEnhancement となります。In the following example, the namespace of the hosting startup assembly is StartupEnhancement. ホスティング スタートアップ コードを含むクラスは StartupEnhancementHostingStartup です。The class containing the hosting startup code is StartupEnhancementHostingStartup:

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

HostingStartup 属性は、通常、ホスティング スタートアップ アセンブリの IHostingStartup 実装クラス ファイル内に置かれます。The HostingStartup attribute is typically located in the hosting startup assembly's IHostingStartup implementation class file.

読み込まれたホスティング スタートアップ アセンブリを見つけるDiscover loaded hosting startup assemblies

読み込まれたホスティング スタートアップ アセンブリを検出するには、ログ記録を有効にしてアプリのログを確認します。To discover loaded hosting startup assemblies, enable logging and check the app's logs. アセンブリの読み込み時に発生したエラーがログ記録されます。Errors that occur when loading assemblies are logged. 読み込まれたホスティング スタートアップ アセンブリは、デバッグ レベルでログ記録され、すべてのエラーが記録されます。Loaded hosting startup assemblies are logged at the Debug level, and all errors are logged.

ホスティング スタートアップ アセンブリの自動読み込みを無効にするDisable automatic loading of hosting startup assemblies

ホスティング スタートアップ アセンブリの自動読み込みを無効にするには、次の方法のいずれかを使用します。To disable automatic loading of hosting startup assemblies, use one of the following approaches:

  • すべてのホスティング スタートアップ アセンブリの読み込みを回避するには、次のいずれかを true または 1 に設定します。To prevent all hosting startup assemblies from loading, set one of the following to true or 1:
  • 特定のホスティング スタートアップ アセンブリの読み込みを回避するには、次に示すいずれかを、起動時に除外するホスティング スタートアップ アセンブリを示すセミコロンで区切られた文字列に設定します。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:

ホスト構成設定と環境変数が両方とも設定されている場合は、ホスト設定によって動作が制御されます。If both the host configuration setting and the environment variable are set, the host setting controls the behavior.

ホスト設定または環境変数を使用してホスティング スタートアップ アセンブリを無効にすると、アセンブリがグローバルに無効になり、場合によってはアプリのいくつかの属性も無効になります。Disabling hosting startup assemblies using the host setting or environment variable disables the assembly globally and may disable several characteristics of an app.

ProjectProject

次のいずれかの種類のプロジェクトを使用して、ホスティング スタートアップを作成します。Create a hosting startup with either of the following project types:

クラス ライブラリClass library

クラス ライブラリでは、ホスティング スタートアップの拡張機能を提供できます。A hosting startup enhancement can be provided in a class library. このライブラリには HostingStartup 属性が含まれています。The library contains a HostingStartup attribute.

サンプル コードには、Razor Pages アプリ、 HostingStartupApp 、クラス ライブラリ、 HostingStartupLibrary が含まれています。The sample code includes a Razor Pages app, HostingStartupApp , and a class library, HostingStartupLibrary. クラス ライブラリには次のものが含まれています。The class library:

  • IHostingStartup を実装するホスティング スタートアップ クラス ServiceKeyInjectionContains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection では、メモリ内の構成プロバイダー (AddInMemoryCollection) を使用して、サービスの文字列のペアがアプリの構成に追加されます。ServiceKeyInjection adds a pair of service strings to the app's configuration using the in-memory configuration provider (AddInMemoryCollection).
  • ホスティング スタートアップの名前空間とクラスを識別する HostingStartup 属性。Includes a HostingStartup attribute that identifies the hosting startup's namespace and class.

ServiceKeyInjection クラスの Configure メソッドでは、IWebHostBuilder を使ってアプリに拡張機能を追加します。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);
            });
        }
    }
}

アプリのインデックス ページでは、クラス ライブラリのホスティング スタートアップ アセンブリによって設定された 2 つのキーの構成値が読み取られて表示されます。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()
    {
    }
}

サンプル コード には、別のホスティング スタートアップ HostingStartupPackage を提供する NuGet パッケージ プロジェクトも含まれています。The sample code also includes a NuGet package project that provides a separate hosting startup, HostingStartupPackage. パッケージには、前に説明したクラス ライブラリと同じ特性があります。The package has the same characteristics of the class library described earlier. パッケージには次のものが含まれます。The package:

  • IHostingStartup を実装するホスティング スタートアップ クラス ServiceKeyInjectionContains a hosting startup class, ServiceKeyInjection, which implements IHostingStartup. ServiceKeyInjection では、アプリの構成にサービス文字列のペアが追加されます。ServiceKeyInjection adds a pair of service strings to the app's configuration.
  • 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);
            });
        }
    }
}

アプリのインデックス ページでは、パッケージのホスティング スタートアップ アセンブリによって設定された 2 つのキーの構成値が読み取られて表示されます。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()
    {
    }
}

エントリ ポイントのないコンソール アプリConsole app without an entry point

このアプローチは、.NET Core アプリでのみ利用でき、.NET Framework では利用できません。This approach is only available for .NET Core apps, not .NET Framework.

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. コンソール アプリを発行すると、ランタイム ストアから使用できるホスティング スタートアップ アセンブリが生成されます。Publishing the console app produces a hosting startup assembly that can be consumed from the runtime store.

このプロセスにおいてエントリ ポイントのないコンソール アプリが使用される理由は、次のとおりです。A console app without an entry point is used in this process because:

  • ホスティング スタートアップ アセンブリ内のホスティング スタートアップを使用するには、依存関係ファイルが必要です。A dependencies file is required to consume the hosting startup in the hosting startup assembly. 依存関係ファイルは、ライブラリではなくアプリを発行することによって生成される、実行可能なアプリ資産です。A dependencies file is a runnable app asset that's produced by publishing an app, not a library.
  • ランタイム パッケージ ストア にライブラリを直接追加することはできません。それには、共有ランタイムを対象とする実行可能なプロジェクトが必要です。A library can't be added directly to the runtime package store, which requires a runnable project that targets the shared runtime.

動的ホスティング スタートアップを作成する場合:In the creation of a dynamic hosting startup:

  • 次のようなエントリ ポイントがないコンソール アプリからホスティング スタートアップ アセンブリが作成されます。A hosting startup assembly is created from the console app without an entry point that:
    • IHostingStartup の実装を含むクラスを含んでいる。Includes a class that contains the IHostingStartup implementation.
    • IHostingStartup 実装クラスを識別するための HostingStartup 属性を含んでいる。Includes a HostingStartup attribute to identify the IHostingStartup implementation class.
  • ホスティング スタートアップの依存関係を取得するには、コンソール アプリを発行します。The console app is published to obtain the hosting startup's dependencies. コンソール アプリを発行すると、その結果として、依存関係ファイルから未使用の依存関係が切り捨てられます。A consequence of publishing the console app is that unused dependencies are trimmed from the dependencies file.
  • ホスティング スタートアップ アセンブリのランタイムの場所を設定するために、依存関係ファイルが変更されます。The dependencies file is modified to set the runtime location of the hosting startup assembly.
  • ホスティング スタートアップ アセンブリとその依存関係ファイルは、ランタイム パッケージ ストアに配置されます。The hosting startup assembly and its dependencies file is placed into the runtime package store. ホスティング スタートアップ アセンブリとその依存関係ファイルを検出する場合、それらは環境変数のペアに記載されています。To discover the hosting startup assembly and its dependencies file, they're listed in a pair of environment variables.

コンソール アセンブリでは、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>

HostingStartup 属性を使うと、IWebHost のビルド時に、読み込みと実行のための IHostingStartup の実装としてクラスが識別されます。A HostingStartup attribute identifies a class as an implementation of IHostingStartup for loading and execution when building the IWebHost. 次の例では、名前空間は StartupEnhancement、クラスは StartupEnhancementHostingStartup です。In the following example, the namespace is StartupEnhancement, and the class is StartupEnhancementHostingStartup:

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

クラスは IHostingStartup を実装しています。A class implements IHostingStartup. このクラスの Configure メソッドでは、IWebHostBuilder を使ってアプリに拡張機能を追加します。The class's Configure method uses an IWebHostBuilder to add enhancements to an app. ホスティング スタートアップ アセンブリ内の IHostingStartup.Configure は、ユーザー コード内の Startup.Configure よりも前にランタイムによって呼び出されます。このため、ホスティング スタートアップ アセンブリによって提供されるすべての構成をユーザー コードで上書きすることができます。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.
        }
    }
}

IHostingStartup プロジェクトのビルド時に、依存関係ファイル ( .deps.json ) によってアセンブリの runtime の場所が bin フォルダーに設定されます。When building an IHostingStartup project, the dependencies file ( .deps.json ) sets the runtime location of the assembly to the bin folder:

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

ファイルの一部のみが示されています。Only part of the file is shown. 例のアセンブリ名は StartupEnhancement です。The assembly name in the example is StartupEnhancement.

ホスティング スタートアップによって指定される構成Configuration provided by the hosting startup

ホスティング スタートアップの構成、アプリの構成のどちらを優先させるかによって、2 つの異なる方法で構成を処理できます。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. アプリの ConfigureAppConfiguration デリゲートを実行した後で ConfigureAppConfiguration を使って構成を読み込み、アプリに構成を指定します。Provide configuration to the app using ConfigureAppConfiguration to load the configuration after the app's ConfigureAppConfiguration delegates execute. この方法を使うと、ホスティング スタートアップの構成の方がアプリの構成よりも優先されます。Hosting startup configuration takes priority over the app's configuration using this approach.
  2. アプリの ConfigureAppConfiguration デリゲートを実行する前に UseConfiguration を使って構成を読み込み、アプリに構成を指定します。Provide configuration to the app using UseConfiguration to load the configuration before the app's ConfigureAppConfiguration delegates execute. この方法を使うと、アプリの構成値の方がホスティング スタートアップにより指定されるものよりも優先されます。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);
    }
}

ホスティング スタートアップ アセンブリを指定するSpecify the hosting startup assembly

クラス ライブラリまたはコンソール アプリのいずれかで提供されるホスティング スタートアップの場合は、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. 環境変数はアセンブリのセミコロン区切りのリストです。The environment variable is a semicolon-delimited list of assemblies.

ホスティング スタートアップ アセンブリのみが、HostingStartup 属性に対してスキャンされます。Only hosting startup assemblies are scanned for the HostingStartup attribute. サンプル アプリ HostingStartupApp では、前述したホスティング スタートアップを検出するために、環境変数が次の値に設定されています。For the sample app, HostingStartupApp , to discover the hosting startups described earlier, the environment variable is set to the following value:

HostingStartupLibrary;HostingStartupPackage;StartupDiagnostics

ホスティング スタートアップ アセンブリはまた、[ホスティング スタートアップ アセンブリ] ホスト構成設定を使用して設定することもできます。A hosting startup assembly can also be set using the Hosting Startup Assemblies host configuration setting.

複数のホスティング スタートアップ アセンブリが存在する場合、それらの Configure メソッドは、アセンブリが一覧表示されている順序で実行されます。When multiple hosting startup assembles are present, their Configure methods are executed in the order that the assemblies are listed.

アクティベーションActivation

ホスティング スタートアップのアクティブ化のオプションは次のとおりです。Options for hosting startup activation are:

  • ランタイム ストア:アクティブ化では、アクティブ化に関するコンパイル時参照を必要としません。Runtime store: Activation doesn't require a compile-time reference for activation. サンプル アプリでは、ホスティング スタートアップ アセンブリおよび依存関係のファイルが deployment フォルダーに配置されています。これにより、複数のコンピューターから成る環境でのホスティング スタートアップの配置が容易になります。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. deployment フォルダーには、ホスティングスタートアップが有効になるように配置システム上で環境変数を作成および変更する PowerShell スクリプトも含まれています。The deployment folder also includes a PowerShell script that creates or modifies environment variables on the deployment system to enable the hosting startup.
  • アクティブ化で必須のコンパイル時参照Compile-time reference required for activation

ランタイム ストアRuntime store

ホスティング スタートアップ実装は、ランタイム ストアに置かれます。The hosting startup implementation is placed in the runtime store. アセンブリへのコンパイル時参照は、機能強化されたアプリで必須ではありません。A compile-time reference to the assembly isn't required by the enhanced app.

ホスティング スタートアップをビルドした後、プロジェクトのマニフェスト ファイルと 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

サンプル アプリ ( RuntimeStore プロジェクト) では、次のコマンドを使用します。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

ランタイムでランタイム ストアを検出できるように、ランタイム ストアの場所を環境変数 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.

ホスティング スタートアップの依存関係ファイルを変更して配置するModify and place the hosting startup's dependencies file

拡張機能へのパッケージ参照なしで拡張機能をアクティブ化するには、additionalDeps を使用してランタイムに追加の依存関係を指定します。To activate the enhancement without a package reference to the enhancement, specify additional dependencies to the runtime with additionalDeps. additionalDeps を使用すると、次のことを実行できます。additionalDeps allows you to:

  • スタートアップ時にアプリの独自の .deps.json ファイルとマージさせる追加の .deps.json ファイルのセットを指定することで、アプリのライブラリのグラフを拡張します。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.
  • ホスティング スタートアップ アセンブリを検出可能および読み込み可能にします。Make the hosting startup assembly discoverable and loadable.

追加の依存関係ファイルを生成するために推奨される方法は次のとおりです。The recommended approach for generating the additional dependencies file is to:

  1. 前のセクションで参照したランタイム ストアのマニフェスト ファイルに対して dotnet publish を実行します。Execute dotnet publish on the runtime store manifest file referenced in the previous section.
  2. ライブラリと、結果として得られる deps.json ファイルの runtime セクションから、マニフェスト参照を削除します。Remove the manifest reference from libraries and the runtime section of the resulting .deps.json file.

プロジェクトの例では、targetslibraries セクションから store.manifest/1.0.0 プロパティが削除されます。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"
    }
  }
}

次の場所に .deps.json ファイルを配置します。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}:DOTNET_ADDITIONAL_DEPS 環境変数に追加される場所。{ADDITIONAL DEPENDENCIES PATH}: Location added to the DOTNET_ADDITIONAL_DEPS environment variable.
  • {SHARED FRAMEWORK NAME}:この追加の依存関係ファイルに必要な共有フレームワーク。{SHARED FRAMEWORK NAME}: Shared framework required for this additional dependencies file.
  • {SHARED FRAMEWORK VERSION}:共有フレームワークの最小バージョン。{SHARED FRAMEWORK VERSION}: Minimum shared framework version.
  • {ENHANCEMENT ASSEMBLY NAME}:拡張機能のアセンブリ名。{ENHANCEMENT ASSEMBLY NAME}: The enhancement's assembly name.

サンプル アプリ ( RuntimeStore プロジェクト) では、追加の依存関係ファイルは以下の場所に配置されます。In the sample app ( RuntimeStore project), the additional dependencies file is placed into the following location:

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

ランタイムでランタイム ストアの場所を検出できるように、追加の依存関係ファイルの場所が環境変数 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.

サンプル アプリ ( RuntimeStore プロジェクト) では、 PowerShell スクリプトを使用してランタイム ストアのビルドと追加の依存関係ファイルの生成を行います。In the sample app ( RuntimeStore project), building the runtime store and generating the additional dependencies file is accomplished using a PowerShell script.

さまざまなオペレーティング システムの環境変数を設定する方法の例については、複数の環境の使用に関するページを参照してください。For examples of how to set environment variables for various operating systems, see Use multiple environments.

配置Deployment

サンプル アプリでは、複数のコンピューターから成る環境へのホスティング スタートアップの配置を容易にするために、発行された出力内に、次を含む deployment フォルダーが作成されます。To facilitate the deployment of a hosting startup in a multimachine environment, the sample app creates a deployment folder in published output that contains:

  • ホスティング スタートアップのランタイム ストア。The hosting startup runtime store.
  • ホスティング スタートアップの依存関係ファイル。The hosting startup dependencies file.
  • ホスティング スタートアップのアクティブ化をサポートできるように、ASPNETCORE_HOSTINGSTARTUPASSEMBLIESDOTNET_SHARED_STOREDOTNET_ADDITIONAL_DEPS を作成および変更する PowerShell スクリプト。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. このスクリプトは、配置システム上の PowerShell 管理用コマンド プロンプトから実行します。Run the script from an administrative PowerShell command prompt on the deployment system.

NuGet パッケージNuGet package

NuGet パッケージでは、ホスティング スタートアップの拡張機能を提供できます。A hosting startup enhancement can be provided in a NuGet package. このパッケージには HostingStartup 属性があります。The package has a HostingStartup attribute. このパッケージで提供される種類のホスティング スタートアップは、次のアプローチのいずれかを使用してアプリで利用できるようになります。The hosting startup types provided by the package are made available to the app using either of the following approaches:

  • 機能強化されたアプリのプロジェクト ファイルでは、アプリのプロジェクト ファイル内のホスティング スタートアップに対するパッケージ参照 (コンパイル時参照) が作成されます。The enhanced app's project file makes a package reference for the hosting startup in the app's project file (a compile-time reference). コンパイル時参照を適用すると、ホスティング スタートアップ アセンブリとその依存関係のすべてが、アプリの依存関係ファイル ( .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 ). このアプローチは、nuget.org に発行されるホスティング スタートアップ アセンブリ パッケージに適用されます。This approach applies to a hosting startup assembly package published to nuget.org.
  • ホスティング スタートアップの依存関係ファイルは、「ランタイム ストア」のセクションで説明にしたように (コンパイル参照がない場合)、機能強化されたアプリで利用できるようになります。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).

NuGet パッケージとランタイム ストアの詳細については、次のトピックを参照してください。For more information on NuGet packages and the runtime store, see the following topics:

プロジェクトの bin フォルダーProject bin folder

ホスティング スタートアップの拡張機能は、機能強化されたアプリ内の bin 配置アセンブリによって提供できます。A hosting startup enhancement can be provided by a bin -deployed assembly in the enhanced app. このアセンブリで提供される種類のホスティング スタートアップは、次のアプローチのいずれかを使用してアプリで利用できるようになります。The hosting startup types provided by the assembly are made available to the app using one of the following approaches:

  • 機能強化されたアプリのプロジェクト ファイルでは、ホスティング スタートアップへのアセンブリ参照 (コンパイル時参照) が作成されます。The enhanced app's project file makes an assembly reference to the hosting startup (a compile-time reference). コンパイル時参照を適用すると、ホスティング スタートアップ アセンブリとその依存関係のすべてが、アプリの依存関係ファイル ( .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 ). この手法は、展開シナリオによって、ホスティング スタートアップのアセンブリ ( .dll ファイル) に対してコンパイル時参照を作成し、次のいずれかにそのアセンブリを移動させることが要請される場合に適用されます。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:
    • 使用するプロジェクト。The consuming project.
    • 使用するプロジェクトでアクセスできる場所。A location accessible by the consuming project.
  • ホスティング スタートアップの依存関係ファイルは、「ランタイム ストア」のセクションで説明にしたように (コンパイル参照がない場合)、機能強化されたアプリで利用できるようになります。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).
  • .NET Framework を対象にするとき、アセンブリは既定の読み込みコンテキストで読み込み可能です。これは、.NET Framework の場合、アセンブリが次のいずれかの場所にあることを意味します。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:
    • アプリケーション ベース パス:アプリの実行可能ファイル ( .exe ) が置かれている bin フォルダー。Application base path: The bin folder where the app's executable ( .exe ) is located.
    • グローバル アセンブリ キャッシュ (GAC):GAC には、複数の .NET Framework アプリで共有されるアセンブリが格納されています。Global Assembly Cache (GAC): The GAC stores assemblies that several .NET Framework apps share. 詳細については、「方法: アセンブリをグローバル アセンブリ キャッシュにインストールする」を参照してください。これは .NET Framework ドキュメントにあります。For more information, see How to: Install an assembly into the global assembly cache in the .NET Framework documentation.

サンプル コードSample code

サンプル コード (ダウンロードする方法) では、ホスティング スタートアップ実装のシナリオを示します。The sample code (how to download) demonstrates hosting startup implementation scenarios:

  • 2 つのホスティング スタートアップ アセンブリ (クラス ライブラリ) ではそれぞれ、メモリ内の構成のキーと値のペアの組が設定されます。Two hosting startup assemblies (class libraries) set a pair of in-memory configuration key-value pairs each:
    • NuGet パッケージ ( HostingStartupPackage )NuGet package ( HostingStartupPackage )
    • クラス ライブラリ ( HostingStartupLibrary )Class library ( HostingStartupLibrary )
  • ホスティング スタートアップは、ランタイム ストア配置アセンブリ ( StartupDiagnostics ) からアクティブ化されます。A hosting startup is activated from a runtime store-deployed assembly ( StartupDiagnostics ). このアセンブリによってスタートアップ時に 2 つのミドルウェアがアプリに追加され、これにより診断情報が提供されます。The assembly adds two middlewares to the app at startup that provide diagnostic information on:
    • 登録サービスRegistered services
    • アドレス (スキーム、ホスト、パス ベース、パス、クエリ文字列)Address (scheme, host, path base, path, query string)
    • 接続 (リモート IP、リモート ポート、ローカル IP、ローカル ポート、クライアント証明書)Connection (remote IP, remote port, local IP, local port, client certificate)
    • 要求ヘッダーRequest headers
    • 環境変数Environment variables

サンプルを実行するにはTo run the sample:

NuGet パッケージからのアクティブ化Activation from a NuGet package

  1. dotnet pack コマンドを使用して HostingStartupPackage パッケージをコンパイルします。Compile the HostingStartupPackage package with the dotnet pack command.

  2. HostingStartupPackage のパッケージのアセンブリ名を ASPNETCORE_HOSTINGSTARTUPASSEMBLIES 環境変数に追加します。Add the package's assembly name of the HostingStartupPackage to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. アプリをコンパイルして実行します。Compile and run the app. 機能拡張されたアプリにはパッケージ参照 (コンパイル時参照) が存在します。A package reference is present in the enhanced app (a compile-time reference). アプリのプロジェクト ファイル内の <PropertyGroup> では、パッケージ プロジェクトの出力 ( ../HostingStartupPackage/Bin/debug ) がパッケージ ソースとして指定されます。A <PropertyGroup> in the app's project file specifies the package project's output ( ../HostingStartupPackage/bin/Debug ) as a package source. これにより、nuget.org にパッケージをアップロードすることなく、アプリによりパッケージが使用されるようになります。詳細については、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. インデックス ページで表示されるサービス構成キー値が、パッケージの ServiceKeyInjection.Configure メソッドによって設定された値と一致することを確認します。Observe that the service configuration key values rendered by the Index page match the values set by the package's ServiceKeyInjection.Configure method.

HostingStartupPackage プロジェクトに変更を加えてそれをコンパイルする場合は、ローカル キャッシュから、古いパッケージではなく更新されたパッケージが、 HostingStartupApp によって確実に受信されるように、ローカルの NuGet パッケージ キャッシュをクリアします。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. ローカルの NuGet キャッシュをクリアするには、次の dotnet nuget locals コマンドを実行します。To clear the local NuGet caches, execute the following dotnet nuget locals command:

dotnet nuget locals all --clear

クラス ライブラリからのアクティブ化Activation from a class library

  1. dotnet build コマンドを使用して HostingStartupLibrary クラス ライブラリをコンパイルします。Compile the HostingStartupLibrary class library with the dotnet build command.

  2. HostingStartupLibrary のクラス ライブラリのアセンブリ名を ASPNETCORE_HOSTINGSTARTUPASSEMBLIES 環境変数に追加します。Add the class library's assembly name of HostingStartupLibrary to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.

  3. クラス ライブラリのアセンブリをアプリに bin 配置するには、クラス ライブラリのコンパイルされた出力からアプリの bin/Debug フォルダーに HostingStartupLibrary.dll ファイルをコピーします。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. アプリをコンパイルして実行します。Compile and run the app. アプリのプロジェクト ファイル内の <ItemGroup> は、クラス ライブラリのアセンブリ ( .\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll ) を参照します (コンパイル時参照)。An <ItemGroup> in the app's project file references the class library's assembly ( .\bin\Debug\netcoreapp2.1\HostingStartupLibrary.dll ) (a compile-time reference). 詳細については、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. インデックス ページで表示されるサービス構成キー値が、クラス ライブラリの ServiceKeyInjection.Configure メソッドによって設定された値と一致することを確認します。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 from a runtime store-deployed assembly

  1. StartupDiagnostics プロジェクトでは、 PowerShell を使用して、その StartupDiagnostics.deps.json ファイルを変更します。The StartupDiagnostics project uses PowerShell to modify its StartupDiagnostics.deps.json file. 既定では、PowerShell は Windows 7 SP1 と Windows Server 2008 R2 SP1 以降の Windows 上にインストールされます。PowerShell is installed by default on Windows starting with Windows 7 SP1 and Windows Server 2008 R2 SP1. 他のプラットフォームで PowerShell を取得するには、「PowerShell のさまざまなバージョンのインストール」を参照してください。To obtain PowerShell on other platforms, see Installing various versions of PowerShell.
  2. RuntimeStore フォルダーにある build.ps1 スクリプトを実行します。Execute the build.ps1 script in the RuntimeStore folder. スクリプトでは次のことが行われます。The script:
    • obj\packages フォルダーに StartupDiagnostics パッケージが生成されます。Generates the StartupDiagnostics package in the obj\packages folder.
    • store フォルダー内に StartupDiagnostics 用のランタイム ストアが生成されます。Generates the runtime store for StartupDiagnostics in the store folder. スクリプト内の dotnet store コマンドでは、Windows に展開されているホスティング スタートアップの win7-x64ランタイム識別子 (RID) が使用されます。The dotnet store command in the script uses the win7-x64 runtime identifier (RID) for a hosting startup deployed to Windows. 別のランタイムに対してホスティング スタートアップを指定する場合は、スクリプトの 37 行目を適切な RID に置き換えます。When providing the hosting startup for a different runtime, substitute the correct RID on line 37 of the script. StartupDiagnostics のランタイム ストアは、後で、アセンブリが使用されるコンピューター上のユーザーまたはシステムのランタイム ストアに移動されます。The runtime store for StartupDiagnostics would later be moved to the user's or system's runtime store on the machine where the assembly will be consumed. StartupDiagnostics アセンブリのユーザー ランタイム ストアのインストール場所は、 .dotnet/store/x64/netcoreapp2.2/startupdiagnostics/1.0.0/lib/netcoreapp2.2/StartupDiagnostics.dll です。The user runtime store install location for the StartupDiagnostics assembly is .dotnet/store/x64/netcoreapp2.2/startupdiagnostics/1.0.0/lib/netcoreapp2.2/StartupDiagnostics.dll.
    • additionalDeps フォルダーに StartupDiagnosticsadditionalDeps が生成されます。Generates the additionalDeps for StartupDiagnostics in the additionalDeps folder. 追加の依存関係は、後でユーザーまたはシステムの追加の依存関係に移動されます。The additional dependencies would later be moved to the user's or system's additional dependencies. ユーザーの StartupDiagnostics に関する追加の依存関係のインストール場所は、 .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/2.2.0/StartupDiagnostics.deps.json です。The user StartupDiagnostics additional dependencies install location is .dotnet/x64/additionalDeps/StartupDiagnostics/shared/Microsoft.NETCore.App/2.2.0/StartupDiagnostics.deps.json.
    • deploy.ps1 ファイルが deployment フォルダーに配置されます。Places the deploy.ps1 file in the deployment folder.
  3. deployment フォルダーにある deploy.ps1 スクリプトを実行します。Run the deploy.ps1 script in the deployment folder. スクリプトでは以下のものが追加されます。The script appends:
    • StartupDiagnosticsASPNETCORE_HOSTINGSTARTUPASSEMBLIES 環境変数に。StartupDiagnostics to the ASPNETCORE_HOSTINGSTARTUPASSEMBLIES environment variable.
    • (RuntimeStore プロジェクトの deployment フォルダーにある) ホスティング スタートアップの依存関係のパスが、DOTNET_ADDITIONAL_DEPS 環境変数に。The hosting startup dependencies path (in the RuntimeStore project's deployment folder) to the DOTNET_ADDITIONAL_DEPS environment variable.
    • (RuntimeStore プロジェクトの deployment フォルダーにある) ランタイム ストアのパスが、DOTNET_SHARED_STORE 環境変数に。The runtime store path (in the RuntimeStore project's deployment folder) to the DOTNET_SHARED_STORE environment variable.
  4. サンプル アプリを実行します。Run the sample app.
  5. /services エンドポイントを要求して、アプリの登録サービスを参照します。Request the /services endpoint to see the app's registered services. /diag エンドポイントを要求して、診断情報を参照します。Request the /diag endpoint to see the diagnostic information.