WebApplication e WebApplicationBuilder em aplicativos de API mínima

WebApplication

O código a seguir é gerado por um modelo ASP.NET Core:

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

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

app.Run();

O código anterior pode ser criado por meio de dotnet new web na linha de comando ou selecionando o modelo da Web vazio no Visual Studio.

O código a seguir cria um WebApplication (app) sem criar explicitamente um WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create inicializa uma nova instância da classe WebApplication com padrões pré-configurados.

Trabalhar com portas

Quando um aplicativo Web é criado com o Visual Studio ou dotnet new, um arquivo de Properties/launchSettings.json é criado que especifica as portas às quais o aplicativo responde. Nos exemplos de configuração de porta a seguir, a execução do aplicativo do Visual Studio retorna uma caixa de diálogo de erro Unable to connect to web server 'AppName'. Visual Studio retorna um erro porque ele está esperando a porta especificada em Properties/launchSettings.json, mas o aplicativo está usando a porta especificada por app.Run("http://localhost:3000"). Execute os seguintes exemplos de alteração de porta a partir da linha de comandos.

As seções a seguir definem a porta à qual o aplicativo responde.

var app = WebApplication.Create(args);

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

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

No código anterior, o aplicativo responde à porta 3000.

Várias portas

No código a seguir, o aplicativo responde à porta 3000 e 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Definir a porta a partir da linha de comando

O comando a seguir faz com que o aplicativo responda à porta 7777:

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

Se o ponto de extremidade Kestrel também estiver configurado no arquivo appsettings.json, a URL especificada do arquivo appsettings.json será usada. Para obter mais informações, consulte Kestrel configuração do ponto de extremidade

Leia a porta do ambiente

O código a seguir lê a porta do ambiente:

var app = WebApplication.Create(args);

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

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

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

A maneira preferida de definir a porta do ambiente é usar a variável de ambiente ASPNETCORE_URLS, que é mostrada na seção a seguir.

Definir as portas através da variável de ambiente ASPNETCORE_URLS

A variável de ambiente ASPNETCORE_URLS está disponível para definir a porta:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS suporta vários URLs:

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

Ouça em todas as interfaces

Os exemplos a seguir demonstram a escuta em todas as interfaces

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();

Ouça em todas as interfaces usando ASPNETCORE_URLS

Os exemplos anteriores podem usar ASPNETCORE_URLS

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

Ouça em todas as interfaces usando ASPNETCORE_HTTPS_PORTS

Os exemplos anteriores podem usar ASPNETCORE_HTTPS_PORTS e ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Para obter mais informações, consulte Kestrel

Especificar HTTPS com certificado de desenvolvimento

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações sobre o certificado de desenvolvimento, consulte Confiar no certificado de desenvolvimento HTTPS do ASP.NET Core no Windows e macOS.

Especificar HTTPS usando um certificado personalizado

As seções a seguir mostram como especificar o certificado personalizado usando o arquivo appsettings.json e via configuração.

Especifique o certificado personalizado com appsettings.json

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

Especifique o certificado personalizado por meio da configuração

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();

Usar as APIs de certificado

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();

Ler o ambiente

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();

Para obter mais informações sobre como usar o ambiente, consulte ASP.NET Core runtime environments

Configuration

O código a seguir lê do sistema de configuração:

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações, consulte Configuração no ASP.NET Core

Logging

O código a seguir grava uma mensagem no log durante o arranque da aplicação.

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações, consulte Fazendo login no .NET e no ASP.NET Core

Aceder ao contentor de injeção de dependência (DI)

O código a seguir mostra como obter serviços do contêiner DI durante a inicialização do aplicativo:

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();

O código a seguir mostra como acessar chaves do contêiner DI usando o atributo [FromKeyedServices]:

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.";
}

Para obter mais informações sobre DI, consulte Injeção de dependência no ASP.NET Core.

WebApplicationBuilder

Esta seção contém código de exemplo usando WebApplicationBuilder.

Alterar a raiz do conteúdo, o nome do aplicativo e o ambiente

O código a seguir define a raiz do conteúdo, o nome do aplicativo e o ambiente:

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 inicializa uma nova instância da classe WebApplicationBuilder com padrões pré-configurados.

Para obter mais informações, consulte ASP.NET Visão geral dos fundamentos principais

Alterar a raiz do conteúdo, o nome do aplicativo e o ambiente usando variáveis de ambiente ou linha de comando

A tabela a seguir mostra a variável de ambiente e o argumento de linha de comando usados para alterar a raiz do conteúdo, o nome do aplicativo e o ambiente:

caraterística	Variável de ambiente	Argumento de linha de comando
Nome do aplicativo	ASPNETCORE_APPLICATIONNAME	--applicationName
Nome do ambiente	ASPNETCORE_ENVIRONMENT	--environment
Raiz do conteúdo	ASPNETCORE_CONTENTROOT	--contentRoot

Adicionar provedores de configuração

O exemplo a seguir adiciona o provedor de configuração INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Para obter informações detalhadas, consulte Provedores de configuração de arquivo em Configuração no ASP.NET Core.

Ler configuração

Por padrão, o WebApplicationBuilder lê a configuração de várias fontes, incluindo:

• appSettings.json e appSettings.{environment}.json
• Variáveis de ambiente
• A linha de comando

Para obter uma lista completa das fontes de configuração lidas, consulte de configuração padrão em Configuration in ASP.NET Core.

O código a seguir lê HelloKey da configuração e mostra o valor no endpoint /. Se o valor de configuração for null, "Hello" será atribuído a message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Ler o ambiente

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Adicionar fornecedores de registo

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();

Adicionar serviços

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();

Personalizar o IHostBuilder

Os métodos de extensão existentes no IHostBuilder podem ser acessados usando a propriedade 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();

Personalizar o IWebHostBuilder

Os métodos de extensão em IWebHostBuilder podem ser acessados usando a propriedade 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();

Alterar a raiz da Web

Por padrão, a raiz da Web é relativa à raiz de conteúdo na pasta wwwroot. A raiz da Web é onde o Static File Middleware procura arquivos estáticos. A raiz da Web pode ser alterada com WebHostOptions, a linha de comando ou o método UseWebRoot:

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

var app = builder.Build();

app.Run();

Container de injeção de dependências (DI) personalizado

O exemplo a seguir usa 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();

Adicionar middleware

Qualquer middleware existente do ASP.NET Core pode ser configurado no WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Para obter mais informações, consulte ASP.NET Core Middleware

Página de exceção do desenvolvedor

WebApplication.CreateBuilder inicializa uma nova instância da classe WebApplicationBuilder com padrões pré-configurados. A página de exceção do desenvolvedor está habilitada nos padrões pré-configurados. Quando o código a seguir é executado no ambiente de desenvolvimento , navegar até / renderiza uma página amigável que mostra a exceção.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();