Minimal API アプリでの WebApplication と WebApplicationBuilder

WebApplication

次のコードが ASP.NET Core テンプレートによって生成されます。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

上記のコードは、コマンド ラインで dotnet new web を実行するか、Visual Studio で空の Web テンプレートを選択することによって作成できます。

次のコードにより、WebApplication (app) が作成されます。WebApplicationBuilder は明示的に作成されません。

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run();

WebApplication.Create は、事前構成された既定値を使用して WebApplication クラスの新しいインスタンスを初期化します。

ポートの設定

Visual Studio または dotnet new で Web アプリが作成されると、アプリの応答先となるポートを指定する Properties/launchSettings.json ファイルが作成されます。 続くポート設定サンプルで、Visual Studio からアプリを実行すると Unable to connect to web server 'AppName' エラー ダイアログが返されます。 Properties/launchSettings.json で指定されたポートが予期されますが、アプリでは app.Run("http://localhost:3000") で指定されたポートが使用されているため、Visual Studio からエラーが返されます。 コマンド ラインから次のポート変更サンプルを実行してください。

次のセクションでは、アプリが応答するポートを設定します。

var app = WebApplication.Create(args);

app.MapGet("/", () => "Hello World!");

app.Run("http://localhost:3000");

上記のコードの場合、アプリは 3000 ポートに応答します。

複数のポート

次のコードの場合、アプリは 3000 と 4000 ポートに応答します。

var app = WebApplication.Create(args);

app.Urls.Add("http://localhost:3000");
app.Urls.Add("http://localhost:4000");

app.MapGet("/", () => "Hello World");

app.Run();

コマンド ラインからポートを設定する

次のコマンドにより、アプリは 7777 ポートに応答するようになります。

dotnet run --urls="https://localhost:7777"

Kestrel ファイルで appsettings.json エンドポイントも構成されている場合、 appsettings.json ファイルで指定されている URL が使用されます。 詳細については、「Kestrelエンドポイント構成」を参照してください。

環境からポートを読み取る

次のコードでは、環境からポートを読み取ります。

var app = WebApplication.Create(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "3000";

app.MapGet("/", () => "Hello World");

app.Run($"http://localhost:{port}");

環境からポートを設定する際の推奨される方法は、次のセクションに示されているように、ASPNETCORE_URLS 環境変数を使用することです。

ASPNETCORE_URLS 環境変数を使用してポートを設定する

ASPNETCORE_URLS 環境変数は、ポートを設定するために使用できます。

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS は複数の URL をサポートしています。

ASPNETCORE_URLS=http://localhost:3000;https://localhost:5000

すべてのインターフェイスでリッスンする

次のサンプルは、すべてのインターフェイスでリッスンする方法を示しています

http://*:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://*:3000");

app.MapGet("/", () => "Hello World");

app.Run();

http://+:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://+:3000");

app.MapGet("/", () => "Hello World");

app.Run();

http://0.0.0.0:3000

var app = WebApplication.Create(args);

app.Urls.Add("http://0.0.0.0:3000");

app.MapGet("/", () => "Hello World");

app.Run();

ASPNETCORE_URLS を使用して、すべてのインターフェイスでリッスンする

上記のサンプルでは、ASPNETCORE_URLS を使用できます

ASPNETCORE_URLS=http://*:3000;https://+:5000;http://0.0.0.0:5005

ASPNETCORE_HTTPS_PORTS を使用して、すべてのインターフェイスでリッスンする

上記のサンプルでは、ASPNETCORE_HTTPS_PORTS および ASPNETCORE_HTTP_PORTS を使用できます。

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

詳細については、「ASP.NET Core Kestrel Web サーバーのエンドポイントを構成する」を参照してください

開発証明書を使用して HTTPS を指定する

var app = WebApplication.Create(args);

app.Urls.Add("https://localhost:3000");

app.MapGet("/", () => "Hello World");

app.Run();

開発証明書の詳細については、「Trust the ASP.NET Core HTTPS development certificate on Windows and macOS」(Windows および macOS で ASP.NET Core HTTPS 開発証明書を信頼する) を参照してください。

カスタム証明書を使用して HTTPS を指定する

次のセクションは、appsettings.json ファイルを使用してカスタム証明書を指定する方法と、構成により指定する方法を示しています。

カスタム証明書を appsettings.json で指定する

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "Certificates": {
      "Default": {
        "Path": "cert.pem",
        "KeyPath": "key.pem"
      }
    }
  }
}

構成によりカスタム証明書を指定する

var builder = WebApplication.CreateBuilder(args);

// Configure the cert and the key
builder.Configuration["Kestrel:Certificates:Default:Path"] = "cert.pem";
builder.Configuration["Kestrel:Certificates:Default:KeyPath"] = "key.pem";

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

app.MapGet("/", () => "Hello World");

app.Run();

証明書 API を使用する

using System.Security.Cryptography.X509Certificates;

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(options =>
{
    options.ConfigureHttpsDefaults(httpsOptions =>
    {
        var certPath = Path.Combine(builder.Environment.ContentRootPath, "cert.pem");
        var keyPath = Path.Combine(builder.Environment.ContentRootPath, "key.pem");

        httpsOptions.ServerCertificate = X509Certificate2.CreateFromPemFile(certPath, 
                                         keyPath);
    });
});

var app = builder.Build();

app.Urls.Add("https://localhost:3000");

app.MapGet("/", () => "Hello World");

app.Run();

環境を読み取る

var app = WebApplication.Create(args);

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/oops");
}

app.MapGet("/", () => "Hello World");
app.MapGet("/oops", () => "Oops! An error happened.");

app.Run();

環境の使用方法の詳細については、「ASP.NET Core ランタイム環境」を参照してください。

Configuration

次のコードでは、環境システムから読み取ります。

var app = WebApplication.Create(args);

var message = app.Configuration["HelloKey"] ?? "Config failed!";

app.MapGet("/", () => message);

app.Run();

詳細については、「ASP.NET Core の構成」を参照してください

Logging

次のコードは、アプリケーションの起動時にログにメッセージを書き込みます。

var app = WebApplication.Create(args);

app.Logger.LogInformation("The app started");

app.MapGet("/", () => "Hello World");

app.Run();

詳細については、「.NET および ASP.NET Core でのログ記録」を参照してください。

依存関係の挿入 (DI) コンテナーにアクセスする

次のコードは、アプリケーションの起動時に DI コンテナーからサービスを取得する方法を示しています。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddScoped<SampleService>();

var app = builder.Build();

app.MapControllers();

using (var scope = app.Services.CreateScope())
{
    var sampleService = scope.ServiceProvider.GetRequiredService<SampleService>();
    sampleService.DoSomething();
}

app.Run();

次のコードは、[FromKeyedServices] 属性を使用して DI コンテナーからキーにアクセスする方法を示しています。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

var app = builder.Build();

app.MapGet("/big", ([FromKeyedServices("big")] ICache bigCache) => bigCache.Get("date"));

app.MapGet("/small", ([FromKeyedServices("small")] ICache smallCache) => smallCache.Get("date"));

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

DI の詳細については、「ASP.NET Core での依存関係の挿入」を参照してください。

WebApplicationBuilder

このセクションには、WebApplicationBuilder を使用するサンプル コードが含まれています。

コンテンツ ルート、アプリケーション名、環境を変更する

次のコードは、コンテンツ ルート、アプリケーション名、環境を設定します。

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    ApplicationName = typeof(Program).Assembly.FullName,
    ContentRootPath = Directory.GetCurrentDirectory(),
    EnvironmentName = Environments.Staging,
    WebRootPath = "customwwwroot"
});

Console.WriteLine($"Application Name: {builder.Environment.ApplicationName}");
Console.WriteLine($"Environment Name: {builder.Environment.EnvironmentName}");
Console.WriteLine($"ContentRoot Path: {builder.Environment.ContentRootPath}");
Console.WriteLine($"WebRootPath: {builder.Environment.WebRootPath}");

var app = builder.Build();

WebApplication.CreateBuilder は、事前に構成された既定値を使用して WebApplicationBuilder クラスの新しいインスタンスを初期化します。

詳細については、「ASP.NET Core の基礎の概要」を参照してください

環境変数またはコマンド ラインを使ったコンテンツ ルート、アプリ名、環境の変更

次の表は、コンテンツ ルート、アプリ名、環境を変更するために使用される環境変数とコマンド ライン引数を示しています。

フィーチャー	環境変数	コマンド ライン引数
アプリケーション名	ASPNETCORE_APPLICATIONNAME	--applicationName
環境名	ASPNETCORE_ENVIRONMENT	--environment
コンテンツ ルート	ASPNETCORE_CONTENTROOT	--contentRoot

構成プロバイダーの追加

次のサンプルでは、INI 構成プロバイダーが追加されます。

var builder = WebApplication.CreateBuilder(args);

builder.Configuration.AddIniFile("appsettings.ini");

var app = builder.Build();

詳細については、「ASP.NET Core の構成」の「ファイル構成プロバイダー」を参照してください。

構成の読み取り

既定では、WebApplicationBuilder は次を含む複数のソースから構成を読み取ります。

• appSettings.json および appSettings.{environment}.json
• 環境変数
• コマンド ライン

読み取る構成ソースの完全な一覧については、「ASP.NET Core の構成」の「既定の構成」を参照してください。

次のコードは構成から HelloKey を読み取り、/ エンドポイントの値を表示します。 構成値が null 値の場合、message には "Hello" が代入されます。

var builder = WebApplication.CreateBuilder(args);

var message = builder.Configuration["HelloKey"] ?? "Hello";

var app = builder.Build();

app.MapGet("/", () => message);

app.Run();

環境を読み取る

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine($"Running in development.");
}

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

ログ プロバイダーを追加する

var builder = WebApplication.CreateBuilder(args);

// Configure JSON logging to the console.
builder.Logging.AddJsonConsole();

var app = builder.Build();

app.MapGet("/", () => "Hello JSON console!");

app.Run();

サービスを追加する

var builder = WebApplication.CreateBuilder(args);

// Add the memory cache services.
builder.Services.AddMemoryCache();

// Add a custom scoped service.
builder.Services.AddScoped<ITodoRepository, TodoRepository>();
var app = builder.Build();

IHostBuilder をカスタマイズする

IHostBuilder の既存の拡張メソッドは、Host プロパティを使用してアクセスできます。

var builder = WebApplication.CreateBuilder(args);

// Wait 30 seconds for graceful shutdown.
builder.Host.ConfigureHostOptions(o => o.ShutdownTimeout = TimeSpan.FromSeconds(30));

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

IWebHostBuilder をカスタマイズする

IWebHostBuilder の拡張メソッドは、WebApplicationBuilder.WebHost プロパティを使用してアクセスできます。

var builder = WebApplication.CreateBuilder(args);

// Change the HTTP server implemenation to be HTTP.sys based
builder.WebHost.UseHttpSys();

var app = builder.Build();

app.MapGet("/", () => "Hello HTTP.sys");

app.Run();

Web ルートを変更する

既定では、Web ルートは、wwwroot フォルダーのコンテンツ ルートに対して相対的です。 Web ルートは、静的ファイル ミドルウェアが静的ファイルを検索する場所です。 Web ルートは、WebHostOptions、コマンド ライン、UseWebRoot メソッドを使用して変更できます。

var builder = WebApplication.CreateBuilder(new WebApplicationOptions
{
    Args = args,
    // Look for static files in webroot
    WebRootPath = "webroot"
});

var app = builder.Build();

app.Run();

カスタムの依存関係の挿入 (DI) コンテナー

次の例では、Autofac を使用しています。

var builder = WebApplication.CreateBuilder(args);

builder.Host.UseServiceProviderFactory(new AutofacServiceProviderFactory());

// Register services directly with Autofac here. Don't
// call builder.Populate(), that happens in AutofacServiceProviderFactory.
builder.Host.ConfigureContainer<ContainerBuilder>(builder => builder.RegisterModule(new MyApplicationModule()));

var app = builder.Build();

ミドルウェアの追加

既存の ASP.NET Core のミドルウェアは、WebApplication で構成できます。

var app = WebApplication.Create(args);

// Setup the file server to serve static files.
app.UseFileServer();

app.MapGet("/", () => "Hello World!");

app.Run();

詳細については、「ASP.NET Core のミドルウェア」を参照してください

開発者例外ページ

WebApplication.CreateBuilder は、事前構成された既定値を使用して WebApplicationBuilder クラスの新しいインスタンスを初期化します。 開発者例外ページは、事前に構成された既定値で有効化されています。 開発環境で次のコードを実行して、/ にアクセスすると、例外を示すページが表示されます。

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () =>
{
    throw new InvalidOperationException("Oops, the '/' route has thrown an exception.");
});

app.Run();