Referensi cepat API minimal

Dokumen ini:

• Menyediakan referensi cepat untuk API Minimal.
• Ditujukan untuk pengembang berpengalaman. Untuk pengenalan, lihat Tutorial: Membuat API minimal dengan ASP.NET Core.

API Minimal terdiri dari:

• WebApplication dan WebApplicationBuilder
• Penangan Rute

WebApplication

Kode berikut dihasilkan oleh templat ASP.NET Core:

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

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

app.Run();

Kode sebelumnya dapat dibuat melalui dotnet new web pada baris perintah atau memilih templat Web Kosong di Visual Studio.

Kode berikut membuat WebApplication (app) tanpa secara eksplisit membuat WebApplicationBuilder:

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create menginisialisasi instans WebApplication baru kelas dengan default yang telah dikonfigurasi sebelumnya.

Bekerja dengan port

Saat aplikasi web dibuat dengan Visual Studio atau dotnet new, Properties/launchSettings.json file dibuat yang menentukan port yang ditanggapi aplikasi. Di sampel pengaturan port berikut, menjalankan aplikasi dari Visual Studio mengembalikan dialog Unable to connect to web server 'AppName'kesalahan . Visual Studio mengembalikan kesalahan karena mengharapkan port yang ditentukan dalam Properties/launchSettings.json, tetapi aplikasi menggunakan port yang ditentukan oleh app.Run("http://localhost:3000"). Jalankan sampel perubahan port berikut dari baris perintah.

Bagian berikut mengatur port yang direspons aplikasi.

var app = WebApplication.Create(args);

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

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

Dalam kode sebelumnya, aplikasi merespons port 3000.

Beberapa port

Dalam kode berikut, aplikasi merespons port 3000 dan 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Mengatur port dari baris perintah

Perintah berikut membuat aplikasi merespons port 7777:

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

Kestrel Jika titik akhir juga dikonfigurasi dalam appsettings.json file, appsettings.json URL yang ditentukan file akan digunakan. Untuk informasi selengkapnya, lihat Kestrel konfigurasi titik akhir

Membaca port dari lingkungan

Kode berikut membaca port dari lingkungan:

var app = WebApplication.Create(args);

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

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

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

Cara yang disukai untuk mengatur port dari lingkungan adalah dengan menggunakan ASPNETCORE_URLS variabel lingkungan, yang ditunjukkan di bagian berikut.

Mengatur port melalui variabel lingkungan ASPNETCORE_URLS

Variabel ASPNETCORE_URLS lingkungan tersedia untuk mengatur port:

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS mendukung beberapa URL:

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

Dengarkan semua antarmuka

Sampel berikut menunjukkan mendengarkan di semua antarmuka

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

Dengarkan semua antarmuka menggunakan ASPNETCORE_URLS

Sampel sebelumnya dapat menggunakan ASPNETCORE_URLS

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

Dengarkan semua antarmuka menggunakan ASPNETCORE_HTTPS_PORTS

Sampel sebelumnya dapat menggunakan ASPNETCORE_HTTPS_PORTS dan ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Untuk informasi selengkapnya, lihat Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel

Tentukan HTTPS dengan sertifikat pengembangan

var app = WebApplication.Create(args);

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

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

app.Run();

Untuk informasi selengkapnya tentang sertifikat pengembangan, lihat Mempercayai sertifikat pengembangan ASP.NET Core HTTPS di Windows dan macOS.

Tentukan HTTPS menggunakan sertifikat kustom

Bagian berikut menunjukkan cara menentukan sertifikat kustom menggunakan appsettings.json file dan melalui konfigurasi.

Tentukan sertifikat kustom dengan appsettings.json

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

Tentukan sertifikat kustom melalui konfigurasi

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

Menggunakan API sertifikat

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

Membaca lingkungan

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

Untuk informasi lebih lanjut tentang penggunaan lingkungan runtime, lihat lingkungan runtime ASP.NET Core.

Configuration

Kode berikut membaca dari sistem konfigurasi:

var app = WebApplication.Create(args);

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

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

app.Run();

Untuk informasi selengkapnya, lihat Konfigurasi di ASP.NET Core

Logging

Kode berikut menulis pesan ke startup aplikasi masuk:

var app = WebApplication.Create(args);

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

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

app.Run();

Untuk informasi selengkapnya, lihat Logging di .NET dan ASP.NET Core

Mengakses kontainer Injeksi Dependensi (DI)

Kode berikut menunjukkan cara mendapatkan layanan dari kontainer DI selama pengaktifan aplikasi:

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

Kode berikut menunjukkan cara mengakses kunci dari kontainer DI menggunakan [FromKeyedServices] atribut :

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

Untuk informasi selengkapnya tentang DI, lihat Injeksi dependensi di ASP.NET Core.

WebApplicationBuilder

Bagian ini berisi kode sampel menggunakan WebApplicationBuilder.

Mengubah akar konten, nama aplikasi, dan lingkungan

Kode berikut mengatur akar konten, nama aplikasi, dan lingkungan:

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 menginisialisasi instans baru kelas WebApplicationBuilder dengan default yang telah dikonfigurasi sebelumnya.

Untuk informasi selengkapnya, lihat gambaran umum dasar-dasar ASP.NET Core

Mengubah akar konten, nama aplikasi, dan lingkungan dengan menggunakan variabel lingkungan atau baris perintah

Tabel berikut ini memperlihatkan variabel lingkungan dan argumen baris perintah yang digunakan untuk mengubah akar konten, nama aplikasi, dan lingkungan:

fitur	Variabel lingkungan	Argumen baris perintah
Nama aplikasi	ASPNETCORE_APPLICATIONNAME	--applicationName
Nama lingkungan	ASPNETCORE_ENVIRONMENT	--environment
Akar konten	ASPNETCORE_CONTENTROOT	--contentRoot

Menambahkan penyedia konfigurasi

Contoh berikut menambahkan penyedia konfigurasi INI:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Untuk informasi terperinci, lihat Penyedia konfigurasi file di Konfigurasi di ASP.NET Core.

Membaca konfigurasi

Secara default WebApplicationBuilder , konfigurasi baca dari beberapa sumber, termasuk:

• appSettings.json dan appSettings.{environment}.json
• Variabel lingkungan
• Baris perintah

Untuk daftar lengkap sumber konfigurasi yang dibaca, lihat Konfigurasi default di Konfigurasi di ASP.NET Core.

Kode berikut membaca HelloKey dari konfigurasi dan menampilkan nilai di / titik akhir. Jika nilai konfigurasi null, "Halo" ditetapkan ke message:

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Membaca lingkungan

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Menambahkan penyedia pengelogan

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

Menambahkan layanan

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

Menyesuaikan IHostBuilder

Metode ekstensi yang ada di IHostBuilder dapat diakses menggunakan properti 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();

Menyesuaikan IWebHostBuilder

Metode ekstensi pada IWebHostBuilder dapat diakses menggunakan properti 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();

Mengubah akar web

Secara default, akar web relatif terhadap akar konten di wwwroot folder. Direktori root web adalah tempat Middleware File Statis mencari file statis. Akar web dapat diubah dengan WebHostOptions, baris perintah, atau dengan UseWebRoot metode :

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

var app = builder.Build();

app.Run();

Kontainer injeksi dependensi kustom (DI)

Contoh berikut menggunakan 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();

Tambahkan Middleware

Middleware ASP.NET Core yang ada dapat dikonfigurasi pada WebApplication:

var app = WebApplication.Create(args);

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

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

app.Run();

Untuk informasi selengkapnya, lihat ASP.NET Core Middleware

Halaman pengecualian pengembang

WebApplication.CreateBuilder menginisialisasi instans WebApplicationBuilder baru kelas dengan default yang telah dikonfigurasi sebelumnya. Halaman pengecualian pengembang diaktifkan dalam default yang telah dikonfigurasi sebelumnya. Saat kode berikut dijalankan di lingkungan pengembangan, navigasi untuk / merender halaman ramah yang menunjukkan pengecualian.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

ASP.NET Core Middleware

Tabel berikut mencantumkan beberapa middleware yang sering digunakan dengan API Minimal.

Middleware	Description	API
Authentication	Menyediakan dukungan autentikasi.	UseAuthentication
Authorization	Menyediakan dukungan otorisasi.	UseAuthorization
CORS	Mengonfigurasi Cross-Origin Resource Sharing.	UseCors
Handler Pengecualian	Secara global menangani pengecualian yang dilemparkan oleh alur middleware.	UseExceptionHandler
Header yang Diteruskan	Meneruskan header yang diproksi ke permintaan saat ini.	UseForwardedHeaders
Pengalihan HTTPS	Mengalihkan semua permintaan HTTP ke HTTPS.	UseHttpsRedirection
Http Strict Transport Security (HSTS)	Middleware peningkatan keamanan yang menambahkan header respons khusus.	UseHsts
Pengelogan Permintaan	Menyediakan dukungan untuk mencatat permintaan dan respons HTTP.	UseHttpLogging
Batas Waktu Permintaan	Menyediakan dukungan untuk mengonfigurasi batas waktu permintaan, default global, dan per titik akhir.	UseRequestTimeouts
Pengelogan Permintaan W3C	Menyediakan dukungan untuk mencatat permintaan dan respons HTTP dalam format W3C.	UseW3CLogging
Penembolokan Respons	Menyediakan dukungan untuk respons penembolokan.	UseResponseCaching
Kompresi Respons	Memberikan dukungan untuk memadatkan respons.	UseResponseCompression
Session	Menyediakan dukungan untuk mengelola sesi pengguna.	UseSession
File Statis	Menyediakan dukungan untuk menyajikan file statis dan penjelajahan direktori.	UseStaticFiles, UseFileServer
WebSockets	Mengaktifkan protokol WebSocket.	UseWebSockets

Bagian berikut mencakup penanganan permintaan: perutean, pengikatan parameter, dan respons.

Routing

Dukungan yang dikonfigurasi WebApplication dan Map{Verb} di mana MapMethods adalah metode HTTP camel-cased seperti {Verb}, , Get, Postatau Put:Delete

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

app.MapGet("/", () => "This is a GET");
app.MapPost("/", () => "This is a POST");
app.MapPut("/", () => "This is a PUT");
app.MapDelete("/", () => "This is a DELETE");

app.MapMethods("/options-or-head", new[] { "OPTIONS", "HEAD" }, 
                          () => "This is an options or head request ");

app.Run();

Argumen Delegate yang diteruskan ke metode ini disebut "penangan rute".

Penangan Rute

Penangan rute adalah metode yang dijalankan saat rute cocok. Penangan rute dapat berupa ekspresi lambda, fungsi lokal, metode instans, atau metode statis. Penangan rute bisa sinkron atau asinkron.

Ekspresi Lambda

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

app.MapGet("/inline", () => "This is an inline lambda");

var handler = () => "This is a lambda variable";

app.MapGet("/", handler);

app.Run();

Fungsi lokal

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

string LocalFunction() => "This is local function";

app.MapGet("/", LocalFunction);

app.Run();

Metode instans

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

var handler = new HelloHandler();

app.MapGet("/", handler.Hello);

app.Run();

class HelloHandler
{
    public string Hello()
    {
        return "Hello Instance method";
    }
}

Metode statis

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

app.MapGet("/", HelloHandler.Hello);

app.Run();

class HelloHandler
{
    public static string Hello()
    {
        return "Hello static method";
    }
}

Titik akhir yang ditentukan di luar Program.cs

API minimal tidak harus berada di Program.cs.

Program.cs

using MinAPISeparateFile;

var builder = WebApplication.CreateSlimBuilder(args);

var app = builder.Build();

TodoEndpoints.Map(app);

app.Run();

TodoEndpoints.cs

namespace MinAPISeparateFile;

public static class TodoEndpoints
{
    public static void Map(WebApplication app)
    {
        app.MapGet("/", async context =>
        {
            // Get all todo items
            await context.Response.WriteAsJsonAsync(new { Message = "All todo items" });
        });

        app.MapGet("/{id}", async context =>
        {
            // Get one todo item
            await context.Response.WriteAsJsonAsync(new { Message = "One todo item" });
        });
    }
}

Lihat juga Merutekan grup nanti di artikel ini.

Titik akhir dan pembuatan tautan bernama

Titik akhir dapat diberikan nama untuk menghasilkan URL ke titik akhir. Menggunakan titik akhir bernama menghindari harus melakukan jalur kode keras di aplikasi:

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

app.MapGet("/hello", () => "Hello named route")
   .WithName("hi");

app.MapGet("/", (LinkGenerator linker) => 
        $"The link to the hello route is {linker.GetPathByName("hi", values: null)}");

app.Run();

Kode sebelumnya ditampilkan The link to the hello route is /hello dari / titik akhir.

CATATAN: Nama titik akhir peka huruf besar/kecil.

Nama titik akhir:

• Harus unik secara global.
• Digunakan sebagai id operasi OpenAPI saat dukungan OpenAPI diaktifkan. Untuk informasi selengkapnya, lihat OpenAPI.

Parameter Rute

Parameter rute dapat ditangkap sebagai bagian dari definisi pola rute:

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

app.MapGet("/users/{userId}/books/{bookId}", 
    (int userId, int bookId) => $"The user id is {userId} and book id is {bookId}");

app.Run();

Kode sebelumnya dikembalikan The user id is 3 and book id is 7 dari URI /users/3/books/7.

Handler rute dapat mendeklarasikan parameter yang akan diambil. Ketika permintaan dibuat ke rute dengan parameter yang dinyatakan untuk diambil, parameter diurai dan diteruskan ke handler. Ini memudahkan untuk menangkap nilai dengan cara yang aman. Dalam kode sebelumnya, userId dan bookId keduanya int.

Dalam kode sebelumnya, jika salah satu nilai rute tidak dapat dikonversi ke int, pengecualian akan dilemparkan. Permintaan /users/hello/books/3 GET melemparkan pengecualian berikut:

BadHttpRequestException: Failed to bind parameter "int userId" from "hello".

Kartubebas dan tangkap semua rute

Berikut ini menangkap semua rute yang Routing to hello dikembalikan dari titik akhir '/posts/hello':

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

app.MapGet("/posts/{*rest}", (string rest) => $"Routing to {rest}");

app.Run();

Batasan rute

Batasan rute membatasi perilaku pencocokan rute.

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

app.MapGet("/todos/{id:int}", (int id) => db.Todos.Find(id));
app.MapGet("/todos/{text}", (string text) => db.Todos.Where(t => t.Text.Contains(text));
app.MapGet("/posts/{slug:regex(^[a-z0-9_-]+$)}", (string slug) => $"Post {slug}");

app.Run();

Tabel berikut menunjukkan templat rute sebelumnya dan perilakunya:

Templat Rute	Contoh URI yang Cocok
/todos/{id:int}	/todos/1
/todos/{text}	/todos/something
/posts/{slug:regex(^[a-z0-9_-]+$)}	/posts/mypost

Untuk informasi selengkapnya, lihat Referensi batasan rute dalam Perutean di ASP.NET Core.

Grup rute

Metode MapGroup ekstensi membantu mengatur grup titik akhir dengan awalan umum. Ini mengurangi kode berulang dan memungkinkan untuk menyesuaikan seluruh grup titik akhir dengan satu panggilan ke metode seperti RequireAuthorization dan WithMetadata yang menambahkan metadata titik akhir.

Misalnya, kode berikut membuat dua grup titik akhir serupa:

app.MapGroup("/public/todos")
    .MapTodosApi()
    .WithTags("Public");

app.MapGroup("/private/todos")
    .MapTodosApi()
    .WithTags("Private")
    .AddEndpointFilterFactory(QueryPrivateTodos)
    .RequireAuthorization();


EndpointFilterDelegate QueryPrivateTodos(EndpointFilterFactoryContext factoryContext, EndpointFilterDelegate next)
{
    var dbContextIndex = -1;

    foreach (var argument in factoryContext.MethodInfo.GetParameters())
    {
        if (argument.ParameterType == typeof(TodoDb))
        {
            dbContextIndex = argument.Position;
            break;
        }
    }

    // Skip filter if the method doesn't have a TodoDb parameter.
    if (dbContextIndex < 0)
    {
        return next;
    }

    return async invocationContext =>
    {
        var dbContext = invocationContext.GetArgument<TodoDb>(dbContextIndex);
        dbContext.IsPrivate = true;

        try
        {
            return await next(invocationContext);
        }
        finally
        {
            // This should only be relevant if you're pooling or otherwise reusing the DbContext instance.
            dbContext.IsPrivate = false;
        }
    };
}

public static RouteGroupBuilder MapTodosApi(this RouteGroupBuilder group)
{
    group.MapGet("/", GetAllTodos);
    group.MapGet("/{id}", GetTodo);
    group.MapPost("/", CreateTodo);
    group.MapPut("/{id}", UpdateTodo);
    group.MapDelete("/{id}", DeleteTodo);

    return group;
}

Dalam skenario ini, Anda dapat menggunakan alamat relatif untuk Location header dalam hasil 201 Created :

public static async Task<Created<Todo>> CreateTodo(Todo todo, TodoDb database)
{
    await database.AddAsync(todo);
    await database.SaveChangesAsync();

    return TypedResults.Created($"{todo.Id}", todo);
}

Grup titik akhir pertama hanya akan cocok dengan permintaan yang diawali dan /public/todos dapat diakses tanpa autentikasi apa pun. Grup titik akhir kedua hanya akan cocok dengan permintaan yang diawali dan /private/todos memerlukan autentikasi.

Pabrik QueryPrivateTodos filter titik akhir adalah fungsi lokal yang memodifikasi parameter handler TodoDb rute untuk memungkinkan mengakses dan menyimpan data todo privat.

Grup rute juga mendukung grup berlapis dan pola awalan kompleks dengan parameter rute dan batasan. Dalam contoh berikut, dan handler rute yang dipetakan user ke grup dapat menangkap {org} parameter rute dan {group} yang ditentukan dalam awalan grup luar.

Awalan juga dapat kosong. Ini dapat berguna untuk menambahkan metadata titik akhir atau filter ke sekelompok titik akhir tanpa mengubah pola rute.

var all = app.MapGroup("").WithOpenApi();
var org = all.MapGroup("{org}");
var user = org.MapGroup("{user}");
user.MapGet("", (string org, string user) => $"{org}/{user}");

Menambahkan filter atau metadata ke grup berulah dengan cara yang sama seperti menambahkannya satu per satu ke setiap titik akhir sebelum menambahkan filter atau metadata tambahan yang mungkin telah ditambahkan ke grup dalam atau titik akhir tertentu.

var outer = app.MapGroup("/outer");
var inner = outer.MapGroup("/inner");

inner.AddEndpointFilter((context, next) =>
{
    app.Logger.LogInformation("/inner group filter");
    return next(context);
});

outer.AddEndpointFilter((context, next) =>
{
    app.Logger.LogInformation("/outer group filter");
    return next(context);
});

inner.MapGet("/", () => "Hi!").AddEndpointFilter((context, next) =>
{
    app.Logger.LogInformation("MapGet filter");
    return next(context);
});

Dalam contoh di atas, filter luar akan mencatat permintaan masuk sebelum filter dalam meskipun ditambahkan kedua. Karena filter diterapkan ke grup yang berbeda, urutan yang ditambahkan relatif satu sama lain tidak masalah. Filter pesanan ditambahkan tidak masalah jika diterapkan ke grup yang sama atau titik akhir tertentu.

Permintaan untuk /outer/inner/ mencatat hal berikut:

/outer group filter
/inner group filter
MapGet filter

Pengikatan parameter

Pengikatan parameter adalah proses mengonversi data permintaan menjadi parameter yang diekspresikan dengan kuat yang dinyatakan oleh penangan rute. Sumber pengikatan menentukan dari mana parameter terikat. Sumber pengikatan dapat eksplisit atau disimpulkan berdasarkan metode HTTP dan jenis parameter.

Sumber pengikatan yang didukung:

• Nilai rute
• Untai kueri
• Header
• Isi (sebagai JSON)
• Nilai formulir
• Layanan yang disediakan oleh injeksi dependensi
• Custom

Handler rute GET berikut menggunakan beberapa sumber pengikatan parameter ini:

var builder = WebApplication.CreateBuilder(args);

// Added as service
builder.Services.AddSingleton<Service>();

var app = builder.Build();

app.MapGet("/{id}", (int id,
                     int page,
                     [FromHeader(Name = "X-CUSTOM-HEADER")] string customHeader,
                     Service service) => { });

class Service { }

Fitur pengikatan parameter penting

• Pengikatan eksplisit: Gunakan atribut seperti [FromRoute], , [FromQuery], [FromHeader][FromBody], [FromForm], dan [FromServices] untuk secara eksplisit menentukan sumber pengikatan.
• Pengikatan formulir: Mengikat nilai formulir menggunakan [FromForm] atribut, termasuk dukungan untuk IFormFile dan IFormFileCollection untuk unggahan file.
• Jenis kompleks: Ikat ke koleksi dan jenis kompleks dari formulir, string kueri, dan header.
• Pengikatan kustom: Terapkan logika pengikatan kustom menggunakan TryParse, BindAsync, atau IBindableFromHttpContext<T> antarmuka.
• Parameter opsional: Mendukung jenis nullable dan nilai default untuk parameter opsional.
• Injeksi dependensi: Parameter secara otomatis dihubungkan dari layanan yang terdaftar dalam kontainer DI tersebut.
• Jenis khusus: Pengikatan otomatis untuk HttpContext, , HttpRequest, HttpResponseCancellationToken, ClaimsPrincipal, Stream, dan PipeReader.

---

Pelajari lebih lanjut: Untuk informasi terperinci tentang pengikatan parameter termasuk skenario lanjutan, validasi, prioritas pengikatan, dan pemecahan masalah, lihat Pengikatan parameter dalam aplikasi API Minimal.

Deserialisasi Json+PipeReader dalam API minimal

Mulai dari .NET 10, area fungsional berikut dari ASP.NET Core menggunakan kelebihan beban JsonSerializer.DeserializeAsync berdasarkan PipeReader alih-alih Stream:

• Minimal API (pengikatan parameter, membaca isi permintaan)
• MVC (pemformat input, model)
• Metode HttpRequestJsonExtensions Ekstensi untuk membaca isi permintaan sebagai JSON.

Untuk sebagian besar aplikasi, transisi dari Stream ke PipeReader memberikan performa yang lebih baik tanpa memerlukan perubahan dalam kode aplikasi. Tetapi jika aplikasi Anda memiliki pengonversi kustom, pengonversi mungkin tidak menangani Utf8JsonReader.HasValueSequence dengan benar. Jika tidak, hasilnya bisa berupa kesalahan seperti ArgumentOutOfRangeException atau data yang hilang saat deserialisasi. Anda memiliki opsi berikut untuk membuat pengonversi Anda berfungsi tanpa kesalahan terkait PipeReader.

Opsi 1: Solusi sementara

Solusi cepatnya adalah kembali menggunakan Stream tanpa dukungan PipeReader. Untuk menerapkan opsi ini, atur sakelar AppContext "Microsoft.AspNetCore.UseStreamBasedJsonParsing" ke "true". Kami menyarankan agar Anda melakukan ini hanya sebagai solusi sementara, dan perbarui pengonversi Anda untuk mendukung HasValueSequence sesegera mungkin. Sakelar mungkin dihapus di .NET 11. Satu-satunya tujuannya adalah untuk memberi pengembang waktu untuk memperbarui konverter mereka.

Opsi 2: Perbaikan cepat untuk JsonConverter implementasi

Untuk perbaikan ini, Anda mengalokasikan array dari ReadOnlySequence. Contoh ini menunjukkan seperti apa kode tersebut:

public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
    var span = reader.HasValueSequence ? reader.ValueSequence.ToArray() : reader.ValueSpan;
    // previous code
}

Opsi 3: Perbaikan yang lebih rumit tetapi berkinerja lebih baik

Perbaikan ini melibatkan pengaturan jalur kode terpisah untuk ReadOnlySequence penanganan:

public override T? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
    if (reader.HasValueSequence)
    {
        reader.ValueSequence;
        // ReadOnlySequence optimized path
    }
    else
    {
        reader.ValueSpan;
        // ReadOnlySpan optimized path
    }
}

Untuk mengetahui informasi selengkapnya, lihat

• System.Text.Json.Serialization.JsonConverter
• github.com/dotnet/aspnetcore/pull/62895

Dukungan validasi dalam API Minimal

Mengaktifkan validasi memungkinkan runtime ASP.NET Core untuk melakukan validasi yang ditentukan pada:

• Query
• Header
• Isi dari permintaan

Validasi didefinisikan menggunakan atribut di DataAnnotations namespace.

Saat parameter ke titik akhir API Minimal adalah kelas atau jenis rekaman, atribut validasi akan diterapkan secara otomatis. Contohnya:

public record Product(
    [Required] string Name,
    [Range(1, 1000)] int Quantity);

Pengembang menyesuaikan perilaku sistem validasi dengan:

• Membuat implementasi atribut kustom[Validation].
• Menerapkan IValidatableObject antarmuka untuk logika validasi yang kompleks.

Jika validasi gagal, runtime mengembalikan respons 400 - Permintaan Buruk dengan detail kesalahan validasi.

Mengaktifkan dukungan validasi bawaan untuk API Minimal

Aktifkan dukungan validasi bawaan untuk API Minimal dengan memanggil AddValidation metode ekstensi untuk mendaftarkan layanan yang diperlukan dalam kontainer layanan untuk aplikasi Anda:

builder.Services.AddValidation();

Implementasi secara otomatis menemukan jenis yang didefinisikan dalam handler API Minimal atau sebagai jenis dasar jenis yang ditentukan dalam handler API Minimal. Filter titik akhir melakukan validasi pada jenis ini dan ditambahkan untuk setiap titik akhir.

Validasi dapat dinonaktifkan untuk titik akhir tertentu dengan menggunakan DisableValidation metode ekstensi, seperti dalam contoh berikut:

app.MapPost("/products",
    ([EvenNumber(ErrorMessage = "Product ID must be even")] int productId, [Required] string name)
        => TypedResults.Ok(productId))
    .DisableValidation();

Menyesuaikan respons kesalahan validasi menggunakan IProblemDetailsService

Sesuaikan respons kesalahan dari logika validasi API Minimal dengan IProblemDetailsService implementasi. Daftarkan layanan ini dalam kumpulan layanan aplikasi Anda untuk mengaktifkan respons kesalahan yang lebih konsisten dan spesifik pengguna. Dukungan untuk validasi API Minimal diperkenalkan di ASP.NET Core di .NET 10.

Untuk menerapkan respons kesalahan validasi kustom:

• Menerapkan IProblemDetailsService atau menggunakan implementasi default
• Mendaftarkan layanan dalam kontainer DI
• Sistem validasi secara otomatis menggunakan layanan terdaftar untuk memformat respons kesalahan validasi

Untuk informasi selengkapnya tentang menyesuaikan respons kesalahan validasi dengan IProblemDetailsService, lihat Membuat respons di aplikasi API Minimal.

Responses

Handler rute mendukung jenis nilai pengembalian berikut:

1. IResult berbasis - Ini termasuk Task<IResult> dan ValueTask<IResult>
2. string - Ini termasuk Task<string> dan ValueTask<string>
3. T (Jenis lainnya) - Ini termasuk Task<T> dan ValueTask<T>

Mengembalikan nilai	Behavior	Content-Type
IResult	Kerangka kerja memanggil IResult.ExecuteAsync	Diputuskan IResult oleh implementasi
string	Kerangka kerja menulis string langsung ke respons	text/plain
T (Jenis lainnya)	Kerangka kerja JSON-menserialisasikan respons	application/json

Untuk panduan yang lebih mendalam untuk merutekan nilai pengembalian handler, lihat Membuat respons di aplikasi API Minimal

Contoh nilai pengembalian

nilai pengembalian string

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

JSON mengembalikan nilai

app.MapGet("/hello", () => new { Message = "Hello World" });

Mengembalikan TypedResults

Kode berikut mengembalikan TypedResults:

app.MapGet("/hello", () => TypedResults.Ok(new Message() {  Text = "Hello World!" }));

TypedResults Mengembalikan lebih disukai untuk mengembalikan Results. Untuk informasi selengkapnya, lihat TypedResults vs Results.

Nilai pengembalian IResult

app.MapGet("/hello", () => Results.Ok(new { Message = "Hello World" }));

Contoh berikut menggunakan jenis hasil bawaan untuk mengkustomisasi respons:

app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

JSON

app.MapGet("/hello", () => Results.Json(new { Message = "Hello World" }));

Kode Status Kustom

app.MapGet("/405", () => Results.StatusCode(405));

Text

app.MapGet("/text", () => Results.Text("This is some text"));

Stream

var proxyClient = new HttpClient();
app.MapGet("/pokemon", async () => 
{
    var stream = await proxyClient.GetStreamAsync("http://contoso/pokedex.json");
    // Proxy the response as JSON
    return Results.Stream(stream, "application/json");
});

Lihat Membuat respons di aplikasi API Minimal untuk contoh selengkapnya.

Redirect

app.MapGet("/old-path", () => Results.Redirect("/new-path"));

File

app.MapGet("/download", () => Results.File("myfile.text"));

Hasil bawaan

Pembantu hasil umum ada di Results kelas statis dan TypedResults . TypedResults Mengembalikan lebih disukai untuk mengembalikan Results. Untuk informasi selengkapnya, lihat TypedResults vs Results.

Mengubah Header

Gunakan objek HttpResponse untuk mengubah header respons:

app.MapGet("/", (HttpContext context) => {
    // Set a custom header
    context.Response.Headers["X-Custom-Header"] = "CustomValue";

    // Set a known header
    context.Response.Headers.CacheControl = $"public,max-age=3600";

    return "Hello World";
});

Menyesuaikan hasil

Aplikasi dapat mengontrol respons dengan menerapkan jenis kustom IResult . Kode berikut adalah contoh jenis hasil HTML:

using System.Net.Mime;
using System.Text;
static class ResultsExtensions
{
    public static IResult Html(this IResultExtensions resultExtensions, string html)
    {
        ArgumentNullException.ThrowIfNull(resultExtensions);

        return new HtmlResult(html);
    }
}

class HtmlResult : IResult
{
    private readonly string _html;

    public HtmlResult(string html)
    {
        _html = html;
    }

    public Task ExecuteAsync(HttpContext httpContext)
    {
        httpContext.Response.ContentType = MediaTypeNames.Text.Html;
        httpContext.Response.ContentLength = Encoding.UTF8.GetByteCount(_html);
        return httpContext.Response.WriteAsync(_html);
    }
}

Sebaiknya tambahkan metode ekstensi untuk Microsoft.AspNetCore.Http.IResultExtensions membuat hasil kustom ini lebih dapat ditemukan.

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

app.MapGet("/html", () => Results.Extensions.Html(@$"<!doctype html>
<html>
    <head><title>miniHTML</title></head>
    <body>
        <h1>Hello World</h1>
        <p>The time on the server is {DateTime.Now:O}</p>
    </body>
</html>"));

app.Run();

Hasil yang ditik

Antarmuka IResult dapat mewakili nilai yang dikembalikan dari API Minimal yang tidak menggunakan dukungan implisit untuk JSON yang menserialisasikan objek yang dikembalikan ke respons HTTP. Kelas Hasil statis digunakan untuk membuat berbagai IResult objek yang mewakili berbagai jenis respons. Misalnya, mengatur kode status respons atau mengalihkan ke URL lain.

Jenis yang IResult diterapkan bersifat publik, memungkinkan pernyataan jenis saat pengujian. Contohnya:

[TestClass()]
public class WeatherApiTests
{
    [TestMethod()]
    public void MapWeatherApiTest()
    {
        var result = WeatherApi.GetAllWeathers();
        Assert.IsInstanceOfType(result, typeof(Ok<WeatherForecast[]>));
    }      
}

Anda dapat melihat jenis pengembalian metode yang sesuai pada kelas TypedResults statis untuk menemukan jenis publik IResult yang benar untuk ditransmisikan.

Lihat Membuat respons di aplikasi API Minimal untuk contoh selengkapnya.

Filters

Untuk informasi selengkapnya, lihat Filter di aplikasi API Minimal.

Authorization

Rute dapat dilindungi menggunakan kebijakan otorisasi. Ini dapat dideklarasikan melalui [Authorize] atribut atau dengan menggunakan RequireAuthorization metode :

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using WebRPauth.Data;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization(o => o.AddPolicy("AdminsOnly", 
                                  b => b.RequireClaim("admin", "true")));

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();

var app = builder.Build();

app.UseAuthorization();

app.MapGet("/auth", [Authorize] () => "This endpoint requires authorization.");
app.MapGet("/", () => "This endpoint doesn't require authorization.");
app.MapGet("/Identity/Account/Login", () => "Sign in page at this endpoint.");

app.Run();

Kode sebelumnya dapat ditulis dengan RequireAuthorization:

app.MapGet("/auth", () => "This endpoint requires authorization")
   .RequireAuthorization();

Sampel berikut menggunakan otorisasi berbasis kebijakan:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;
using WebRPauth.Data;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization(o => o.AddPolicy("AdminsOnly", 
                                  b => b.RequireClaim("admin", "true")));

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<IdentityUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();

var app = builder.Build();

app.UseAuthorization();

app.MapGet("/admin", [Authorize("AdminsOnly")] () => 
                             "The /admin endpoint is for admins only.");

app.MapGet("/admin2", () => "The /admin2 endpoint is for admins only.")
   .RequireAuthorization("AdminsOnly");

app.MapGet("/", () => "This endpoint doesn't require authorization.");
app.MapGet("/Identity/Account/Login", () => "Sign in page at this endpoint.");

app.Run();

Perbolehkan pengguna yang tidak diaauthenticated untuk mengakses titik akhir

memungkinkan [AllowAnonymous] pengguna yang tidak diaauthenticated untuk mengakses titik akhir:

app.MapGet("/login", [AllowAnonymous] () => "This endpoint is for all roles.");


app.MapGet("/login2", () => "This endpoint also for all roles.")
   .AllowAnonymous();

CORS

Rute dapat diaktifkan CORS menggunakan kebijakan CORS. CORS dapat dideklarasikan melalui [EnableCors] atribut atau dengan menggunakan RequireCors metode . Sampel berikut mengaktifkan CORS:

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors(options =>
{
    options.AddPolicy(name: MyAllowSpecificOrigins,
                      builder =>
                      {
                          builder.WithOrigins("http://example.com",
                                              "http://www.contoso.com");
                      });
});

var app = builder.Build();
app.UseCors();

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

app.Run();

using Microsoft.AspNetCore.Cors;

const string MyAllowSpecificOrigins = "_myAllowSpecificOrigins";

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddCors(options =>
{
    options.AddPolicy(name: MyAllowSpecificOrigins,
                      builder =>
                      {
                          builder.WithOrigins("http://example.com",
                                              "http://www.contoso.com");
                      });
});

var app = builder.Build();
app.UseCors();

app.MapGet("/cors", [EnableCors(MyAllowSpecificOrigins)] () => 
                           "This endpoint allows cross origin requests!");
app.MapGet("/cors2", () => "This endpoint allows cross origin requests!")
                     .RequireCors(MyAllowSpecificOrigins);

app.Run();

Untuk informasi selengkapnya, lihat Mengaktifkan Permintaan Lintas Asal (CORS) di ASP.NET Core

ValidateScopes dan ValidateOnBuild

ValidateScopes dan ValidateOnBuild diaktifkan secara default di lingkungan Pengembangan tetapi dinonaktifkan di lingkungan lain.

Ketika ValidateOnBuild adalah true, kontainer DI memvalidasi konfigurasi layanan pada waktu build. Jika konfigurasi layanan tidak valid, build gagal pada startup aplikasi, bukan pada runtime saat layanan diminta.

Ketika ValidateScopes adalah true, kontainer DI memvalidasi bahwa layanan tercakup tidak diselesaikan dari cakupan akar. Menyelesaikan layanan tercakup dari cakupan akar dapat mengakibatkan kebocoran memori karena layanan dipertahankan dalam memori lebih lama dari cakupan permintaan.

ValidateScopes dan ValidateOnBuild salah secara default dalam mode non-Pengembangan karena alasan performa.

Kode berikut menunjukkan ValidateScopes diaktifkan secara default dalam mode pengembangan tetapi dinonaktifkan dalam mode rilis:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<MyScopedService>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    Console.WriteLine("Development environment");
}
else
{
    Console.WriteLine("Release environment");
}

app.MapGet("/", context =>
{
    // Intentionally getting service provider from app, not from the request
    // This causes an exception from attempting to resolve a scoped service
    // outside of a scope.
    // Throws System.InvalidOperationException:
    // 'Cannot resolve scoped service 'MyScopedService' from root provider.'
    var service = app.Services.GetRequiredService<MyScopedService>();
    return context.Response.WriteAsync("Service resolved");
});

app.Run();

public class MyScopedService { }

Kode berikut menunjukkan ValidateOnBuild diaktifkan secara default dalam mode pengembangan tetapi dinonaktifkan dalam mode rilis:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<MyScopedService>();
builder.Services.AddScoped<AnotherService>();

// System.AggregateException: 'Some services are not able to be constructed (Error
// while validating the service descriptor 'ServiceType: AnotherService Lifetime:
// Scoped ImplementationType: AnotherService': Unable to resolve service for type
// 'BrokenService' while attempting to activate 'AnotherService'.)'
var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    Console.WriteLine("Development environment");
}
else
{
    Console.WriteLine("Release environment");
}

app.MapGet("/", context =>
{
    var service = context.RequestServices.GetRequiredService<MyScopedService>();
    return context.Response.WriteAsync("Service resolved correctly!");
});

app.Run();

public class MyScopedService { }

public class AnotherService
{
    public AnotherService(BrokenService brokenService) { }
}

public class BrokenService { }

Kode berikut menonaktifkan ValidateScopes dan ValidateOnBuild dalam Development:

var builder = WebApplication.CreateBuilder(args);

if (builder.Environment.IsDevelopment())
{
    Console.WriteLine("Development environment");
    // Doesn't detect the validation problems because ValidateScopes is false.
    builder.Host.UseDefaultServiceProvider(options =>
    {
        options.ValidateScopes = false;
        options.ValidateOnBuild = false;
    });
}

Lihat juga

• Referensi cepat API minimal
• Hasilkan dokumen OpenAPI
• Membuat respons dalam aplikasi API Minimal
• Filter di aplikasi API Minimal
• Menangani kesalahan di API inti ASP.NET
• Autentikasi dan otorisasi dalam API minimal
• Menguji aplikasi API Minimal
• Perutean sirkuit pendek
• Identity Titik akhir API
• Dukungan kontainer injeksi dependensi layanan yang dikunci
• Melihat di balik layar titik akhir API Minimal
• Mengatur API Minimal Inti ASP.NET
• Diskusi validasi yang lancar di GitHub