ASP.NET Core の基礎ASP.NET Core fundamentals

この記事では、ASP.NET Core アプリの開発方法を理解するための主要なトピックをまとめています。This article is an overview of key topics for understanding how to develop ASP.NET Core apps.

Startup クラスThe Startup class

Startup クラスとは、次のとおりです。The Startup class is where:

  • アプリで必要なサービスが構成されています。Services required by the app are configured.
  • 要求を処理するパイプラインが定義されています。The request handling pipeline is defined.

サービスとは、アプリが使用するコンポーネントです。Services are components that are used by the app. たとえば、ログ コンポーネントは、サービスです。For example, a logging component is a service. サービスを構成 (または登録) するコードが Startup.ConfigureServices メソッドに追加されています。Code to configure (or register) services is added to the Startup.ConfigureServices method.

要求を処理するパイプラインは、一連のミドルウェア コンポーネントとして構成されています。The request handling pipeline is composed as a series of middleware components. たとえば、ミドルウェアは、静的ファイルに対する要求を処理したり、HTTPS に HTTP 要求をリダイレクトします。For example, a middleware might handle requests for static files or redirect HTTP requests to HTTPS. 各ミドルウェアは HttpContext に非同期操作を実行してから、パイプラインの次のミドルウェアを呼び出すか、要求を終了します。Each middleware performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request. Startup.Configure メソッドには、要求を処理するパイプラインを構成するコードが追加されます。Code to configure the request handling pipeline is added to the Startup.Configure method.

Startup クラスの例を次に示します。Here's a sample Startup class:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseMvc();
    }
}

詳細については、ASP.NET Core でのアプリケーションのスタートアップ を参照してください。For more information, see ASP.NET Core でのアプリケーションのスタートアップ.

依存性の注入 (サービス)Dependency injection (services)

ASP.NET Core には、アプリのクラスが構成済みのサービスを利用できるようにする依存性の注入 (DI) フレームワークが組み込まれています。ASP.NET Core has a built-in dependency injection (DI) framework that makes configured services available to an app's classes. クラスのサービスのインスタンスを取得する 1 つの方法は、必要な型のパラメーターを使用したコンストラクターを作成することです。One way to get an instance of a service in a class is to create a constructor with a parameter of the required type. このパラメーターには、サービスの種類またはインターフェイスが可能です。The parameter can be the service type or an interface. DI システムは、実行時にこのサービスを提供します。The DI system provides the service at runtime.

Entity Framework Core コンテキスト オブジェクトを取得するために DI を使用するクラスを次に示します。Here's a class that uses DI to get an Entity Framework Core context object. 強調表示されている行は、コンストラクターの挿入の例です。The highlighted line is an example of constructor injection:

public class IndexModel : PageModel
{
    private readonly RazorPagesMovieContext _context;

    public IndexModel(RazorPagesMovieContext context)
    {
        _context = context;
    }
    // ...
    public async Task OnGetAsync()
    {
        var movies = from m in _context.Movies
                        select m;
        Movies = await movies.ToListAsync();
    }
}

DI が組み込まれており、必要に応じてサードパーティ製の制御の反転 (IoC) コンテナーを組み込むことができるよう設計されています。While DI is built in, it's designed to let you plug in a third-party Inversion of Control (IoC) container if you prefer.

詳細については、ASP.NET Core での依存関係の挿入 を参照してください。For more information, see ASP.NET Core での依存関係の挿入.

ミドルウェアMiddleware

要求を処理するパイプラインは、一連のミドルウェア コンポーネントとして構成されています。The request handling pipeline is composed as a series of middleware components. 各コンポーネントは HttpContext に非同期操作を実行してから、パイプラインの次のミドルウェアを呼び出すか、要求を終了します。Each component performs asynchronous operations on an HttpContext and then either invokes the next middleware in the pipeline or terminates the request.

通常、ミドルウェア コンポーネントは、Startup.Configure メソッドのその Use... 拡張メソッドを呼び出してパイプラインに追加されます。By convention, a middleware component is added to the pipeline by invoking its Use... extension method in the Startup.Configure method. たとえば、静的ファイルのレンダリングを有効にするには、UseStaticFiles を呼び出します。For example, to enable rendering of static files, call UseStaticFiles.

次の例の強調表示されているコードは、要求を処理するパイプラインを構成します。The highlighted code in the following example configures the request handling pipeline:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        services.AddDbContext<MovieContext>(options =>
                options.UseSqlServer(Configuration.GetConnectionString("MovieDb")));
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseMvc();
    }
}

ASP.NET Core にはミドルウェアのセットが豊富に組み込まれており、カスタム ミドルウェアをユーザーが記述できます。ASP.NET Core includes a rich set of built-in middleware, and you can write custom middleware.

詳細については、ASP.NET Core のミドルウェア を参照してください。For more information, see ASP.NET Core のミドルウェア.

HostHost

ASP.NET Core アプリは起動時にホストをビルドします。An ASP.NET Core app builds a host on startup. ホストとは、次などのアプリのすべてのリソースをカプセル化するオブジェクトです。The host is an object that encapsulates all of the app's resources, such as:

  • HTTP サーバーの実装An HTTP server implementation
  • ミドルウェア コンポーネントMiddleware components
  • ログの記録Logging
  • DIDI
  • 構成Configuration

アプリの相互依存するすべてのリソースを 1 つのオブジェクトに含める主な理由は、アプリの起動と正常なシャットダウンの制御の有効期間の管理のためです。The main reason for including all of the app's interdependent resources in one object is lifetime management: control over app startup and graceful shutdown.

汎用ホストと Web ホストの 2 つのホストが利用可能です。Two hosts are available: the Generic Host and the Web Host. 汎用ホストが推奨されます。Web ホストは下位互換性のためにのみ使用できます。The Generic Host is recommended, and the Web Host is available only for backwards compatibility.

ホストを作成するコードは Program.Main にあります。The code to create a host is in Program.Main:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

CreateDefaultBuilder メソッドと ConfigureWebHostDefaults メソッドは、次のようなよく使用されるオプションと共にホストを構成します。The CreateDefaultBuilder and ConfigureWebHostDefaults methods configure a host with commonly used options, such as the following:

  • Web サーバーとして Kestrel を使用し、IIS の統合を有効にします。Use Kestrel as the web server and enable IIS integration.
  • appsettings.json、"appsettings.{環境名}.json"、環境変数、コマンド ライン引数、およびその他の構成ソースから構成を読み込みます。Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • ログ出力をコンソールとデバッグ プロバイダーに送ります。Send logging output to the console and debug providers.

詳細については、.NET での汎用ホスト を参照してください。For more information, see .NET での汎用ホスト.

Web ホストと汎用ホストの 2 つのホストが利用可能です。Two hosts are available: the Web Host and the Generic Host. ASP.NET core 2.x では、汎用ホストは Web 以外のシナリオのみを対象としています。In ASP.NET Core 2.x, the Generic Host is only for non-web scenarios.

ホストを作成するコードは Program.Main にあります。The code to create a host is in Program.Main:

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

CreateDefaultBuilder メソッドは、次のようなよく使用されるオプションと共にホストを構成します。The CreateDefaultBuilder method configures a host with commonly used options, such as the following:

  • Web サーバーとして Kestrel を使用し、IIS の統合を有効にします。Use Kestrel as the web server and enable IIS integration.
  • appsettings.json、"appsettings.{環境名}.json"、環境変数、コマンド ライン引数、およびその他の構成ソースから構成を読み込みます。Load configuration from appsettings.json, appsettings.{Environment Name}.json, environment variables, command line arguments, and other configuration sources.
  • ログ出力をコンソールとデバッグ プロバイダーに送ります。Send logging output to the console and debug providers.

詳細については、ASP.NET Core の Web ホスト を参照してください。For more information, see ASP.NET Core の Web ホスト.

Web 以外のシナリオNon-web scenarios

汎用ホストにより、他の種類のアプリで、ログ記録、依存性の注入 (DI)、構成、およびアプリの有効期間管理などの横断的なフレームワーク拡張機能を使えるようになります。The Generic Host allows other types of apps to use cross-cutting framework extensions, such as logging, dependency injection (DI), configuration, and app lifetime management. 詳細については、次のトピックを参照してください。 .NET での汎用ホスト および ASP.NET Core でホステッド サービスを使用するバックグラウンド タスクFor more information, see .NET での汎用ホスト and ASP.NET Core でホステッド サービスを使用するバックグラウンド タスク.

サーバーServers

ASP.NET Core アプリは、HTTP 要求をリッスンするために HTTP サーバー実装を使用します。An ASP.NET Core app uses an HTTP server implementation to listen for HTTP requests. サーバーは、HttpContext に構成した要求機能のセットとして、アプリへの要求を公開します。The server surfaces requests to the app as a set of request features composed into an HttpContext.

ASP.NET Core では、次のサーバー実装が提供されます。ASP.NET Core provides the following server implementations:

  • Kestrel は、クロスプラットフォームの Web サーバーです。Kestrel is a cross-platform web server. Kestrel は IIS を使用してリバース プロキシ構成で実行されることがよくあります。Kestrel is often run in a reverse proxy configuration using IIS. Kestrel は、ASP.NET Core 2.0 以降で、インターネットに直接公開される一般向けエッジ サーバーとして実行することもできます。In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • IIS HTTP サーバーは、IIS を使用する Windows のサーバーです。IIS HTTP Server is a server for windows that uses IIS. このサーバーでは、ASP.NET Core アプリと IIS が同じプロセスで実行されます。With this server, the ASP.NET Core app and IIS run in the same process.
  • HTTP.sys は、IIS とは一緒に使用しない Windows のサーバーです。HTTP.sys is a server for Windows that isn't used with IIS.

ASP.NET Core では、次のサーバー実装が提供されます。ASP.NET Core provides the following server implementations:

  • Kestrel は、クロスプラットフォームの Web サーバーです。Kestrel is a cross-platform web server. Kestrel は IIS を使用してリバース プロキシ構成で実行されることがよくあります。Kestrel is often run in a reverse proxy configuration using IIS. Kestrel は、ASP.NET Core 2.0 以降で、インターネットに直接公開される一般向けエッジ サーバーとして実行することもできます。In ASP.NET Core 2.0 or later, Kestrel can be run as a public-facing edge server exposed directly to the Internet.
  • HTTP.sys は、IIS とは一緒に使用しない Windows のサーバーです。HTTP.sys is a server for Windows that isn't used with IIS.

詳細については、ASP.NET Core での Web サーバーの実装 を参照してください。For more information, see ASP.NET Core での Web サーバーの実装.

構成Configuration

ASP.NET Core は、構成プロバイダーの順序付けされたセットから、名前と値のペアの設定を取得する構成フレームワークとなります。ASP.NET Core provides a configuration framework that gets settings as name-value pairs from an ordered set of configuration providers. .json ファイル、 .xml ファイル、環境変数、コマンドライン引数など、さまざまなソース用に構成プロバイダーが組み込まれています。There are built-in configuration providers for a variety of sources, such as .json files, .xml files, environment variables, and command-line arguments. 独自のカスタム構成プロバイダーを記述することもできます。You can also write custom configuration providers.

たとえば、構成は appsettings.json と環境変数から取得したものであると指定できます。For example, you could specify that configuration comes from appsettings.json and environment variables. このとき ConnectionString 値が要求されると、フレームワークはまず appsettings.json ファイルを参照します。Then when the value of ConnectionString is requested, the framework looks first in the appsettings.json file. 値がそこにあり、しかし環境変数にもある場合、環境変数の値が優先されます。If the value is found there but also in an environment variable, the value from the environment variable would take precedence.

ASP.NET Core には、パスワードなどの機密の構成データの管理にシークレット マネージャー ツールが用意されています。For managing confidential configuration data such as passwords, ASP.NET Core provides a Secret Manager tool. 実稼働の機密情報には、Azure Key Vault を使用することをお勧めします。For production secrets, we recommend Azure Key Vault.

詳細については、ASP.NET Core の構成 を参照してください。For more information, see ASP.NET Core の構成.

オプションOptions

ASP.NET Core では、構成値の格納と取得に、可能な限りオプション パターンを使用します。Where possible, ASP.NET Core follows the options pattern for storing and retrieving configuration values. オプション パターンではクラスを使用して、関連する設定のグループを表します。The options pattern uses classes to represent groups of related settings.

たとえば、以下のコードでは WebSockets のオプションが設定されます。For example, the following code sets WebSockets options:

var options = new WebSocketOptions  
{  
   KeepAliveInterval = TimeSpan.FromSeconds(120),  
   ReceiveBufferSize = 4096
};  
app.UseWebSockets(options);

詳細については、ASP.NET Core のオプション パターン を参照してください。For more information, see ASP.NET Core のオプション パターン.

環境Environments

開発ステージング、および実稼働などの実行環境は ASP.NET Core の最上の概念です。Execution environments, such as Development, Staging, and Production, are a first-class notion in ASP.NET Core. アプリが実行している環境は、ASPNETCORE_ENVIRONMENT 環境変数を設定することにより指定できます。You can specify the environment an app is running in by setting the ASPNETCORE_ENVIRONMENT environment variable. ASP.NET Core は、アプリの起動時にその環境変数を読み取り、その値を IHostingEnvironment 実装に格納します。ASP.NET Core reads that environment variable at app startup and stores the value in an IHostingEnvironment implementation. この環境オブジェクトは、DI を介しアプリの任意の場所で使用されます。The environment object is available anywhere in the app via DI.

Startup クラスの次のサンプル コードは、それが開発環境で実行された場合のみ、詳細なエラー情報を提供するようアプリを構成します。The following sample code from the Startup class configures the app to provide detailed error information only when it runs in development:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();
    app.UseMvc();
}

詳細については、ASP.NET Core で複数の環境を使用する を参照してください。For more information, see ASP.NET Core で複数の環境を使用する.

ログの記録Logging

ASP.NET Core では、組み込みやサード パーティ製のさまざまなログ プロバイダーと連携するログ API がサポートされています。ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. 利用可能なプロバイダーは次のとおりです。Available providers include the following:

  • コンソールConsole
  • デバッグDebug
  • Event Tracing on WindowsEvent Tracing on Windows
  • Windows イベント ログWindows Event Log
  • TraceSourceTraceSource
  • Azure App ServiceAzure App Service
  • Azure Application InsightsAzure Application Insights

DI からの ILogger オブジェクトの取得およびログ メソッドの呼び出しによってアプリのコードの任意の場所からログを記述します。Write logs from anywhere in an app's code by getting an ILogger object from DI and calling log methods.

コンストラクターの挿入とログ記録メソッドの呼び出しが強調表示されている ILogger オブジェクトを使用するサンプル コードを次に示します。Here's sample code that uses an ILogger object, with constructor injection and the logging method calls highlighted.

public class TodoController : ControllerBase
{
    private readonly ILogger _logger;

    public TodoController(ILogger<TodoController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}", Name = "GetTodo")]
    public ActionResult<TodoItem> GetById(string id)
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
        // Item lookup code removed.
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
            return NotFound();
        }
        return item;
    }
}

ILogger インターフェイスは、ログ プロバイダーに任意の数のフィールドを渡すことができます。The ILogger interface lets you pass any number of fields to the logging provider. このフィールドは、一般的にメッセージの文字列を構築するために使用しますが、プロバイダーがデータ ストアに別のフィールドとして送信することも可能です。The fields are commonly used to construct a message string, but the provider can also send them as separate fields to a data store. この機能は、構造化ロギングとも呼ばれるセマンティック ロギングをログ プロバイダーが実装するのを可能にします。This feature makes it possible for logging providers to implement semantic logging, also known as structured logging.

詳細については、ASP.NET Core でのログ記録 を参照してください。For more information, see ASP.NET Core でのログ記録.

ルーティングRouting

ルートとは、ハンドラーにマップされている URL のパターンです。A route is a URL pattern that is mapped to a handler. このハンドラーは一般的には Razor Pages、MVC コントローラーのアクション メソッドまたはミドルウェアです。The handler is typically a Razor page, an action method in an MVC controller, or a middleware. ASP.NET Core のルーティングでは、アプリで使用する URL を制御できます。ASP.NET Core routing gives you control over the URLs used by your app.

詳細については、ASP.NET Core のルーティング を参照してください。For more information, see ASP.NET Core のルーティング.

エラー処理Error handling

ASP.NET Core には、次などのエラー処理用の機能が組み込まれています。ASP.NET Core has built-in features for handling errors, such as:

  • 開発者例外ページA developer exception page
  • カスタム エラー ページCustom error pages
  • 静的状態コード ページStatic status code pages
  • 起動時の例外処理Startup exception handling

詳細については、ASP.NET Core のエラーを処理する を参照してください。For more information, see ASP.NET Core のエラーを処理する.

HTTP 要求を行うMake HTTP requests

HttpClient インスタンスの作成に、IHttpClientFactory の実装を使用できます。An implementation of IHttpClientFactory is available for creating HttpClient instances. ファクトリは次のことを行います。The factory:

  • 論理 HttpClient インスタンスの名前付けと構成を一元化します。Provides a central location for naming and configuring logical HttpClient instances. たとえば、github クライアントを登録して、GitHub にアクセスするように構成できます。For example, a github client can be registered and configured to access GitHub. 既定のクライアントは、他の目的に登録できます。A default client can be registered for other purposes.
  • 複数のデリゲート ハンドラーを登録してチェーン化し、送信要求ミドルウェア パイプラインを構築するのをサポートしています。Supports registration and chaining of multiple delegating handlers to build an outgoing request middleware pipeline. このパターンは、ASP.NET Core での受信ミドルウェア パイプラインに似ています。This pattern is similar to the inbound middleware pipeline in ASP.NET Core. このパターンは、キャッシュ、エラー処理、シリアル化、ログ記録など、HTTP 要求に関する横断的関心事を管理するためのメカニズムを提供します。The pattern provides a mechanism to manage cross-cutting concerns around HTTP requests, including caching, error handling, serialization, and logging.
  • 一時的な障害処理用の人気のサードパーティ製ライブラリ、Polly と統合できます。Integrates with Polly, a popular third-party library for transient fault handling.
  • 基になっている HttpClientMessageHandler インスタンスのプールと有効期間を管理し、HttpClient の有効期間を手動で管理するときに発生する一般的な DNS の問題を防ぎます。Manages the pooling and lifetime of underlying HttpClientMessageHandler instances to avoid common DNS problems that occur when manually managing HttpClient lifetimes.
  • ファクトリによって作成されたクライアントから送信されるすべての要求に対し、(ILogger によって) 構成可能なログ エクスペリエンスを追加します。Adds a configurable logging experience (via ILogger) for all requests sent through clients created by the factory.

詳細については、ASP.NET Core で IHttpClientFactory を使用して HTTP 要求を行う を参照してください。For more information, see ASP.NET Core で IHttpClientFactory を使用して HTTP 要求を行う.

コンテンツ ルートContent root

このコンテンツ ルートは、その Razor ファイルなど、アプリで使用されるすべてのプライベート コンテンツへの基本パスです。The content root is the base path to any private content used by the app, such as its Razor files. 既定では、コンテンツ ルートは、アプリをホストする実行可能ファイルの基本パスです。By default, the content root is the base path for the executable hosting the app. ホストの構築時には、別の場所を指定できます。An alternative location can be specified when building the host.

詳細については、コンテンツ ルートに関するページを参照してください。For more information, see Content root.

詳細については、コンテンツ ルートに関するページを参照してください。For more information, see Content root.

Web ルートWeb root

(webroot としても知られている) Web ルートは、CSS、JavaScript、およびイメージ ファイルなど、パブリックな静的リソースへの基本パスです。The web root (also known as webroot) is the base path to public, static resources, such as CSS, JavaScript, and image files. 既定で、この静的ファイル ミドルウェアは、Web ルート ディレクトリ (とそのサブディレクトリ) のファイルにのみサービスを提供します。The static files middleware will only serve files from the web root directory (and sub-directories) by default. Web ルートのパスの既定値は、" {コンテンツ ルート}/wwwroot" ですが、ホストの構築時に別の場所を指定することも可能です。The web root path defaults to {Content Root}/wwwroot, but a different location can be specified when building the host.

Razor ( .cshtml) のファイルの場合、チルダとスラッシュ ~/ が webroot を指します。In Razor (.cshtml) files, the tilde-slash ~/ points to the web root. ~/ で始まるパスは仮想パスと呼ばれます。Paths beginning with ~/ are referred to as virtual paths.

詳細については、ASP.NET Core の静的ファイル を参照してください。For more information, see ASP.NET Core の静的ファイル.