Informations de référence rapides sur les API minimales

Ce document :

• Fournit une référence rapide pour les API minimales.
• Est destiné aux développeurs expérimentés. Pour une introduction, consultez Tutoriel : Créer une API minimale avec ASP.NET Core.

Les API minimales se composent des éléments suivants :

• WebApplication et WebApplicationBuilder
• Gestionnaires d’itinéraires

WebApplication

Le code suivant est généré par un modèle ASP.NET Core :

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

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

app.Run();

Le code précédent peut être créé via dotnet new web sur la ligne de commande ou en sélectionnant le modèle web Vide dans Visual Studio.

Le code suivant crée un WebApplication (app) sans créer explicitement de WebApplicationBuilder :

var app = WebApplication.Create(args);

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

app.Run();

WebApplication.Create initialise une nouvelle instance de la classe WebApplication avec les valeurs par défaut préconfigurées.

Utilisation des ports

Lorsqu’une application web est créée avec Visual Studio ou dotnet new, un fichier Properties/launchSettings.json est créé et spécifie les ports auxquels l’application répond. Dans les exemples de paramètres de port qui suivent, l’exécution de l’application à partir de Visual Studio renvoie une boîte de dialogue d’erreur Unable to connect to web server 'AppName'. Visual Studio retourne une erreur, car il attend le port spécifié dans Properties/launchSettings.json, mais l’application utilise le port spécifié par app.Run("http://localhost:3000"). Exécutez les exemples de modification de port suivants à partir de la ligne de commande.

Les sections suivantes définissent le port auquel l’application répond.

var app = WebApplication.Create(args);

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

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

Dans le code précédent, l’application répond au port 3000.

Plusieurs ports

Dans le code suivant, l’application répond aux ports 3000 et 4000.

var app = WebApplication.Create(args);

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

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

app.Run();

Définir le port à partir de la ligne de commande

La commande suivante permet à l’application de répondre au port 7777 :

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

Si le point de terminaison Kestrel est également configuré dans le fichier appsettings.json, l’URL spécifiée par le fichier appsettings.json est utilisée. Pour plus d’informations, consultez Configuration du point de terminaison Kestrel

Lire le port à partir de l’environnement

Le code suivant lit le port à partir de l’environnement :

var app = WebApplication.Create(args);

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

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

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

La méthode recommandée pour définir le port à partir de l’environnement consiste à utiliser la variable d’environnement ASPNETCORE_URLS, comme indiqué dans la section suivante.

Définir les ports via la variable d’environnement ASPNETCORE_URLS

La variable d’environnement ASPNETCORE_URLS est disponible pour définir le port :

ASPNETCORE_URLS=http://localhost:3000

ASPNETCORE_URLS prend en charge plusieurs URL :

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

Écouter sur toutes les interfaces

Les exemples suivants illustrent l’écoute sur toutes les 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();

Écoutez toutes les interfaces à l’aide d’ASPNETCORE_URLS

Les exemples précédents peuvent utiliser ASPNETCORE_URLS

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

Écoutez toutes les interfaces à l’aide d’ASPNETCORE_HTTPS_PORTS

Les exemples précédents peuvent utiliser ASPNETCORE_HTTPS_PORTS et ASPNETCORE_HTTP_PORTS.

ASPNETCORE_HTTP_PORTS=3000;5005
ASPNETCORE_HTTPS_PORTS=5000

Pour plus d’informations, consultez Configurer des points de terminaison pour le serveur web ASP.NET Core Kestrel

Spécifier HTTPS avec un certificat de développement

var app = WebApplication.Create(args);

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

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

app.Run();

Pour plus d’informations sur le certificat de développement, consultez Approuver le certificat de développement HTTPS ASP.NET Core sur Windows et macOS.

Spécifier HTTPS à l’aide d’un certificat personnalisé

Les sections suivantes montrent comment spécifier le certificat personnalisé à l’aide du fichier appsettings.json et via la configuration.

Spécifier le certificat personnalisé avec appsettings.json

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

Spécifier le certificat personnalisé via la configuration

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

Utiliser les API de certificat

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

Lire l’environnement

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

Pour plus d’informations sur l’utilisation de l’environnement, consultez ASP.NET environnements d’exécution Core

Configuration

Le code suivant est lu à partir du système de configuration :

var app = WebApplication.Create(args);

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

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

app.Run();

Pour plus d’informations, consultez Configuration dans ASP.NET Core

Logging

Le code suivant écrit un message dans le journal au démarrage de l’application :

var app = WebApplication.Create(args);

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

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

app.Run();

Pour plus d’informations, consultez Journalisation dans .NET et ASP.NET Core

Accéder au conteneur d’injection de dépendances (DI)

Le code suivant montre comment obtenir des services à partir du conteneur d’authentification unique au démarrage de l’application :

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

Le code suivant montre comment accéder aux clés d’accès à partir du conteneur d’injection de dépendances (DI) en utilisant l’attribut [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.";
}

Pour obtenir plus d’informations sur le DI, consultez Injection de dépendances dans ASP.NET Core.

WebApplicationBuilder

Cette section contient un exemple de code utilisant WebApplicationBuilder.

Modifier la racine du contenu, le nom de l’application et l’environnement

Le code suivant définit la racine du contenu, le nom de l’application et l’environnement :

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 initialise une nouvelle instance de la classe WebApplicationBuilder avec les valeurs par défaut préconfigurées.

Pour plus d’informations, consultez Vue d’ensemble des principes de base d’ASP.NET Core

Modifier la racine du contenu, le nom de l’application et l’environnement avec des variables d’environnement ou la ligne de commande

Le tableau suivant montre la variable d’environnement et l’argument de ligne de commande utilisés pour modifier la racine du contenu, le nom de l’application et l’environnement :

feature	Variable d’environnement	Argument de ligne de commande
Nom de l’application	ASPNETCORE_APPLICATIONNAME	--applicationName
Nom de l’environnement	ASPNETCORE_ENVIRONMENT	--environment
Racine du contenu	ASPNETCORE_CONTENTROOT	--contentRoot

Ajouter des fournisseurs de configuration

L’exemple suivant ajoute le fournisseur de configuration INI :

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

Pour plus d’informations, consultez Fournisseurs de configuration de fichiers dans Configuration dans ASP.NET Core.

Lire la configuration

Par défaut, WebApplicationBuilder lit la configuration à partir de plusieurs sources, notamment :

• appSettings.json et appSettings.{environment}.json
• Variables d'environnement
• Ligne de commande

Pour obtenir la liste complète des sources de configuration lues, consultez Configuration par défaut dans Configuration dans ASP.NET Core.

Le code suivant lit HelloKey à partir de la configuration et affiche la valeur au niveau du point de terminaison /. Si la valeur de configuration est null, « Hello » est affecté à message :

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Lire l’environnement

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

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

app.Run();

Ajouter des fournisseurs de journalisation

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

Ajouter des services

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

Personnaliser IHostBuilder

Les méthodes d’extension existantes sur IHostBuilder sont accessibles à l’aide de la propriété 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();

Personnaliser IWebHostBuilder

Les méthodes d’extension sur IWebHostBuilder sont accessibles à l’aide de la propriété 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();

Modifier la racine web

Par défaut, la racine web est relative à la racine de contenu dans le dossier wwwroot. La racine web est l’emplacement où le middleware de fichiers statiques recherche des fichiers statiques. La racine web peut être modifiée avec WebHostOptions, la ligne de commande ou avec la méthode UseWebRoot :

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

var app = builder.Build();

app.Run();

Conteneur d’injection de dépendances (DI) personnalisé

L’exemple suivant utilise 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();

Ajouter un intergiciel

Tout intergiciel ASP.NET Core existant peut être configuré sur WebApplication :

var app = WebApplication.Create(args);

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

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

app.Run();

Pour plus d’informations, consultez Intergiciel (middleware) ASP.NET Core

Page d’exceptions du développeur

WebApplication.CreateBuilder initialise une nouvelle instance de la classe WebApplicationBuilder avec les valeurs par défaut préconfigurées. La page d’exception du développeur est activée dans les valeurs par défaut préconfigurées. Lorsque le code suivant est exécuté dans l’environnement de développement, la navigation vers / présente une page conviviale qui affiche l’exception.

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

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

app.Run();

Intergiciel (middleware) ASP.NET Core

Le tableau suivant répertorie certains des intergiciels fréquemment utilisés avec des API minimales.

Middleware	Description	API
Authentication	Prend en charge l’authentification.	UseAuthentication
Authorization	Fournit la prise en charge des autorisations.	UseAuthorization
CORS	Configure le partage des ressources cross-origin (CORS).	UseCors
Gestionnaire d’exceptions	Gère globalement les exceptions levées par le pipeline d’intergiciels.	UseExceptionHandler
En-têtes transférés	Transfère les en-têtes en proxy vers la requête actuelle.	UseForwardedHeaders
HTTPS Redirection	Redirige toutes les requêtes HTTP vers HTTPS.	UseHttpsRedirection
HSTS (HTTP Strict Transport Security)	Middleware d’amélioration de la sécurité qui ajoute un en-tête de réponse spécial.	UseHsts
Journalisation des demandes	Prend en charge la journalisation des requêtes et des réponses HTTP.	UseHttpLogging
Délais d’expiration des requêtes	Permet de configurer les délais d'attente des requêtes, par défaut global et par point d'extrémité.	UseRequestTimeouts
Journalisation des requêtes W3C	Prend en charge la journalisation des requêtes et des réponses HTTP au format W3C.	UseW3CLogging
Mise en cache des réponses	Prend en charge la mise en cache des réponses.	UseResponseCaching
Compression de la réponse	Prend en charge la compression des réponses.	UseResponseCompression
Session	Prend en charge la gestion des sessions utilisateur.	UseSession
Fichiers statiques	Prend en charge le traitement des fichiers statiques et l’exploration des répertoires.	UseStaticFiles, UseFileServer
WebSockets	Autorise le protocole WebSockets.	UseWebSockets

Les sections suivantes couvrent la gestion des requêtes : routage, liaison de paramètres et réponses.

Routing

Une méthode HTTP configurée WebApplication prend en charge et Map{Verb} où MapMethods se trouve {Verb} une méthode HTTP en cas de chameau comme Get, , PostPutou 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();

Les arguments Delegate passés à ces méthodes sont appelés « gestionnaires de routes ».

Gestionnaires d’itinéraires

Les gestionnaires de routes sont des méthodes qui s’exécutent lorsque la route correspond. Les gestionnaires de routes peuvent être une expression lambda, une fonction locale, une méthode d’instance ou une méthode statique. Les gestionnaires de routes peuvent être synchrones ou asynchrones.

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

Fonction locale

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

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

app.MapGet("/", LocalFunction);

app.Run();

Méthode d’instance

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

Méthode statique

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

Point de terminaison défini à l’extérieur de Program.cs

Les API minimales n’ont pas besoin d’être situées à l’emplacement 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" });
        });
    }
}

Consultez également Groupes d’itinéraires plus loin dans cet article.

Points de terminaison nommés et génération de liens

Les points de terminaison peuvent recevoir des noms afin de générer des URL vers le point de terminaison. L’utilisation d’un point de terminaison nommé évite d’avoir à coder des chemins d’accès en dur dans une application :

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

Le code précédent affiche The link to the hello route is /hello à partir du point de terminaison /.

REMARQUE : Les noms des points de terminaison respectent la casse.

Noms de points de terminaison :

• Il doit être globalement unique.
• Sont utilisés comme ID d’opération OpenAPI lorsque la prise en charge d’OpenAPI est activée. Pour plus d’informations, consultez OpenAPI.

Paramètres de routage

Les paramètres de routage peuvent être capturés dans le cadre de la définition du modèle de route :

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

Le code précédent retourne The user id is 3 and book id is 7 à partir de l’URI /users/3/books/7.

Le gestionnaire de routes peut déclarer les paramètres à capturer. Lorsqu’une requête est effectuée sur une route avec des paramètres déclarés pour la capture, les paramètres sont analysés et transmis au gestionnaire. Cela permet de capturer facilement les valeurs avec un type sécurisé. Dans le code précédent, userId et bookId sont tous deux de type int.

Dans le code précédent, si l’une ou l’autre valeur de route ne peut pas être convertie en int, une exception est levée. La requête GET /users/hello/books/3 lève l’exception suivante :

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

Caractères génériques et routes catch all

Les éléments suivants interceptent tous les retours de route Routing to hello à partir du point de terminaison « /posts/hello » :

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

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

app.Run();

Contraintes d'itinéraire

Les contraintes de routage limitent le comportement de correspondance d’une route.

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

Le tableau suivant montre les modèles de route précédents et leur comportement :

Modèle de routage	Exemple d’URI en correspondance
/todos/{id:int}	/todos/1
/todos/{text}	/todos/something
/posts/{slug:regex(^[a-z0-9_-]+$)}	/posts/mypost

Pour plus d’informations, consultez Référence sur la contrainte d’itinéraire dans Routage dans ASP.NET Core.

Groupes de routage

La méthode d’extension MapGroup permet d’organiser des groupes de points de terminaison avec un préfixe commun. Cela réduit le code répétitif et permet de personnaliser des groupes entiers de points de terminaison avec un seul appel à des méthodes comme RequireAuthorization et WithMetadata, qui ajoutent des métadonnées de point de terminaison.

Par exemple, le code suivant crée deux groupes de points de terminaison similaires :

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

Dans ce scénario, vous pouvez utiliser une adresse relative pour l’en-tête Location dans le résultat 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);
}

Le premier groupe de points de terminaison correspond uniquement aux requêtes précédées de /public/todos, accessibles sans authentification. Le second groupe de points de terminaison correspond uniquement aux requêtes préfixées par /private/todos, qui nécessitent une authentification.

La QueryPrivateTodosfabrique de filtre de point de terminaison est une fonction locale qui modifie les paramètres TodoDb du gestionnaire d’itinéraires pour permettre l’accès et le stockage de données todo privées.

Les groupes de routage prennent également en charge les groupes imbriqués et les modèles de préfixe complexes avec des contraintes et des paramètres de routage. Dans l’exemple suivant, un gestionnaire de routage mappé au groupe user peut capturer les paramètres de routage {org} et {group} définis dans les préfixes de groupe externe.

Le préfixe peut également être vide. Cela peut être utile pour ajouter des métadonnées ou des filtres de point de terminaison à un groupe de points de terminaison sans modifier le modèle de routage.

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

L’ajout de filtres ou de métadonnées à un groupe se comporte de la même façon que si vous les ajoutiez individuellement à chaque point de terminaison avant d’ajouter des filtres ou des métadonnées supplémentaires qui ont pu être ajoutés à un groupe interne ou à un point de terminaison spécifique.

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

Dans l’exemple ci-dessus, le filtre externe enregistre la requête entrante avant le filtre interne, même si elle a été ajoutée en deuxième. Étant donné que les filtres ont été appliqués à différents groupes, l’ordre dans lequel ils ont été ajoutés les uns par rapport aux autres n’a pas d’importance. Les filtres d’ordre ajoutés sont importants s’ils sont appliqués au même groupe ou au même point de terminaison spécifique.

Une requête sur /outer/inner/ journalisera les éléments suivants :

/outer group filter
/inner group filter
MapGet filter

Liaison de paramètres

La liaison de paramètres est le processus de conversion des données de requête en paramètres fortement typés qui sont exprimés par les gestionnaires de routes. Une source de liaison détermine à partir d’où les paramètres sont liés. Les sources de liaison peuvent être explicites ou déduites en fonction de la méthode HTTP et du type de paramètre.

Sources de liaison prises en charge :

• Valeurs de routage
• Chaîne de requête
• Header
• Corps (JSON)
• Valeurs de formulaire
• Services fournis par l’injection de dépendances
• Custom

Le gestionnaire de routage GET suivant utilise certaines de ces sources de liaison de paramètres :

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

Fonctionnalités de liaison de paramètres clés

• Liaison explicite : utilisez des attributs tels que [FromRoute], , [FromQuery][FromHeader], [FromBody], , [FromForm]et [FromServices] pour spécifier explicitement des sources de liaison.
• Liaison de données de formulaire : lier des valeurs de formulaire à l’aide d’attribut de [FromForm], prenant en charge IFormFile et IFormFileCollection pour le téléversement de fichiers.
• Types complexes : lier des collections et des types complexes à partir de formulaires, de chaînes de requête et d’en-têtes.
• Liaison personnalisée : implémentez une logique de liaison personnalisée à l'aide de TryParse, de BindAsync, ou de l’interface IBindableFromHttpContext<T>.
• Paramètres facultatifs : prend en charge les types nullables et les valeurs par défaut pour les paramètres facultatifs.
• Injection de dépendances : les paramètres sont automatiquement liés à partir des services enregistrés dans le conteneur DI.
• Types spéciaux : liaison automatique pour HttpContext, , HttpRequestHttpResponseCancellationToken, ClaimsPrincipal, , Streamet .PipeReader

---

Pour en savoir plus: Pour plus d’informations sur la liaison de paramètres, notamment les scénarios avancés, la validation, la priorité de liaison et la résolution des problèmes, consultez Liaison de paramètre dans les applications API minimales.

Désérialisation Json+PipeReader dans des API minimales

À compter de .NET 10, les zones fonctionnelles suivantes de ASP.NET Core utilisent des surcharges basées JsonSerializer.DeserializeAsync sur PipeReader au lieu de Stream :

• API minimales (liaison de paramètre, corps de la demande de lecture)
• MVC (formateur d’entrée, modèle)
• Méthodes HttpRequestJsonExtensions d’extension pour lire le corps de la requête en tant que JSON.

Pour la plupart des applications, une transition entre Stream et PipeReader offre de meilleures performances sans nécessiter de modifications dans le code de l’application. Toutefois, si votre application a un convertisseur personnalisé, le convertisseur peut ne pas gérer Utf8JsonReader.HasValueSequence correctement. Si ce n’est pas le cas, le résultat peut être des erreurs telles que ArgumentOutOfRangeException ou des données manquantes lors de la désérialisation. Vous disposez des options suivantes pour que votre convertisseur fonctionne sans erreurs liées à PipeReader.

Option 1 : Solution de contournement temporaire

La solution rapide consiste à revenir à l'utilisation de Stream sans la prise en charge de PipeReader. Pour implémenter cette option, définissez le commutateur AppContext « Microsoft.AspNetCore.UseStreamBasedJsonParsing » sur « true ». Nous vous recommandons de procéder uniquement comme solution de contournement temporaire et de mettre à jour votre convertisseur pour prendre en charge HasValueSequence dès que possible. Le commutateur peut être supprimé dans .NET 11. Son seul objectif était de donner aux développeurs le temps d’obtenir leurs convertisseurs mis à jour.

Option 2 : Un correctif rapide pour les implémentations JsonConverter

Pour ce correctif, vous allouez un tableau de données à partir du ReadOnlySequence. Cet exemple montre à quoi ressemblerait le code :

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

Option 3 : Un correctif plus compliqué mais plus performant

Ce correctif implique la configuration d’un chemin de code distinct pour la ReadOnlySequence gestion :

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

Pour plus d'informations, consultez la rubrique

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

Prise en charge de la validation dans les API minimales

L’activation de la validation permet au runtime ASP.NET Core d’effectuer des validations définies sur les éléments suivants :

• Query
• Header
• Corps de la requête

Les validations sont définies à l’aide d’attributs dans l’espace de noms DataAnnotations.

Lorsqu’un paramètre à un point de terminaison d’API minimal est un type de classe ou d’enregistrement, les attributs de validation sont automatiquement appliqués. Par exemple:

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

Les développeurs personnalisent le comportement du système de validation en :

• Création d’implémentations d’attributs personnalisés[Validation].
• Implémentation de l’interface IValidatableObject pour une logique de validation complexe.

En cas d’échec de la validation, le runtime retourne une réponse 400 - Demande incorrecte avec des détails sur les erreurs de validation.

Activer la prise en charge intégrée de la validation pour les API minimales

Activez la prise en charge intégrée de la validation pour les API minimales en appelant la AddValidation méthode d’extension pour inscrire les services requis dans le conteneur de services de votre application :

builder.Services.AddValidation();

L’implémentation découvre automatiquement les types définis dans les gestionnaires d’API minimal ou en tant que types de base définis dans les gestionnaires d’API minimal. Un filtre de point de terminaison effectue la validation sur ces types et est ajouté pour chaque point de terminaison.

La validation peut être désactivée pour des points de terminaison spécifiques à l’aide de la DisableValidation méthode d’extension, comme dans l’exemple suivant :

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

Personnaliser les réponses d’erreur de validation à l’aide d’IProblemDetailsService

Personnalisez les réponses d’erreur à partir d’une logique de validation d’API minimale avec une IProblemDetailsService implémentation. Inscrivez ce service dans la collection de services de votre application pour permettre des réponses d’erreur plus cohérentes et spécifiques à l’utilisateur. La prise en charge de la validation d’API minimale a été introduite dans ASP.NET Core dans .NET 10.

Pour implémenter des réponses d’erreur de validation personnalisées :

• Implémenter IProblemDetailsService ou utiliser l’implémentation par défaut
• Inscrire le service dans le conteneur d’adresses di
• Le système de validation utilise automatiquement le service inscrit pour mettre en forme les réponses d’erreur de validation

Pour plus d’informations sur la personnalisation des réponses d’erreur de validation avec IProblemDetailsService, consultez Créer des réponses dans les applications API minimales.

Responses

Les gestionnaires de routes prennent en charge les types de valeurs de retour suivants :

1. Basé sur IResult : cela inclut Task<IResult> et ValueTask<IResult>
2. string - Cela comprend Task<string> et ValueTask<string>
3. T (Tout autre type) : cela inclut Task<T> et ValueTask<T>

Valeur retournée	Behavior	Content-Type
IResult	Le framework appelle IResult.ExecuteAsync	Décidé par l’implémentation IResult
string	Le framework écrit la chaîne directement dans la réponse	text/plain
T (Tout autre type)	Le JSON du framework sérialise la réponse	application/json

Pour obtenir un guide plus détaillé sur les valeurs de retour du gestionnaire de routes, consultez Créer des réponses dans les applications API minimales.

Exemples de valeurs de retour

Valeurs de retour string

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

Valeurs de retour JSON

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

Retour TypedResults

Le code suivant retourne TypedResults :

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

Le retour de TypedResults est préférable au retour Results. Pour plus d'informations, consultez TypedResults vs Results.

Valeurs de retour IResult

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

L’exemple suivant utilise les types de résultats intégrés pour personnaliser la réponse :

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

Code d’état personnalisé

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

Pour plus d’exemples, consultez Créer des réponses dans les applications API minimales.

Redirect

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

File

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

Résultats intégrés

Des assistants de résultats communs existent dans les classes Results et TypedResults statiques. Le retour de TypedResults est préférable au retour Results. Pour plus d'informations, consultez TypedResults vs Results.

Modification des en-têtes

Utilisez l’objet HttpResponse pour modifier les en-têtes de réponse :

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

Personnalisation des résultats

Les applications peuvent contrôler les réponses en implémentant un type IResult personnalisé. Le code suivant est un exemple de type de résultat 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);
    }
}

Nous vous recommandons d’ajouter une méthode d’extension à Microsoft.AspNetCore.Http.IResultExtensions pour rendre ces résultats personnalisés plus détectables.

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

Résultats typés

L’interface IResult peut représenter des valeurs retournées à partir d’API minimales qui n’utilisent pas la prise en charge implicite de la sérialisation JSON de l’objet retourné vers la réponse HTTP. La classe statique Results est utilisée pour créer différents objets IResult qui représentent différents types de réponses. Par exemple, la définition du code d’état de la réponse ou la redirection vers une autre URL.

Les types implémentant IResult sont publics, ce qui permet les assertions de type lors des tests. Par exemple:

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

Vous pouvez examiner les types de retour des méthodes correspondantes sur la classe statique TypedResults pour trouver le type IResult public approprié vers lequel effectuer la conversion.

Pour plus d’exemples, consultez Créer des réponses dans les applications API minimales.

Filters

Pour plus d’informations, consultez Filtres dans les applications API minimales.

Authorization

Les itinéraires peuvent être protégés à l’aide de stratégies d’autorisation. Celles-ci peuvent être déclarées via l’attribut [Authorize] ou à l’aide de la méthode RequireAuthorization :

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

Le code précédent peut être écrit avec RequireAuthorization :

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

L’exemple suivant utilise l’autorisation basée sur la stratégie :

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

Autoriser les utilisateurs non authentifiés à accéder à un point de terminaison

[AllowAnonymous] permet aux utilisateurs non authentifiés d’accéder aux points de terminaison :

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


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

CORS

Les itinéraires peuvent avoir CORS activé à l’aide de stratégies CORS. CORS peut être déclaré via l’attribut [EnableCors] ou à l’aide de la méthode RequireCors. Les exemples suivants activent 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();

Pour plus d’informations, consultez Activation les requêtes cross-origin (CORS) dans ASP.NET Core

ValidateScopes et ValidateOnBuild

ValidateScopes et ValidateOnBuild sont activés par défaut dans l’environnement de Développement, mais désactivés dans d’autres environnements.

Quand ValidateOnBuild est true, le conteneur d’injection de dépendances valide la configuration du service au moment de la génération. Si la configuration du service n’est pas valide, la génération échoue au démarrage de l’application, plutôt qu’au moment de l’exécution (runtime) lorsque le service est demandé.

Quand ValidateScopes est true, le conteneur d’injection de dépendances valide qu’un service délimité n’est pas résolu à partir de l’étendue racine. La résolution d’un service délimité à partir de l’étendue racine peut entraîner une fuite de mémoire, car le service est conservé en mémoire plus longtemps que l’étendue de la requête.

ValidateScopes et ValidateOnBuild ont la valeur false par défaut dans les modes autres que Développement pour des raisons de performances.

Le code suivant montre que ValidateScopes est activé par défaut en mode développement, mais désactivé en mode mise en production :

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

Le code suivant montre que ValidateOnBuild est activé par défaut en mode développement, mais désactivé en mode mise en production :

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

Le code suivant désactive ValidateScopes et ValidateOnBuild dans 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;
    });
}

Voir aussi

• Informations de référence rapides sur les API minimales
• Générer des documents OpenAPI
• Créer des réponses dans les applications API minimales
• Filtres dans les applications d’API minimales
• Gérer les erreurs dans les API ASP.NET Core
• Authentification et autorisation dans les API minimales
• Tester les applications API minimales
• Routage en court-circuit
• Identity Points de terminaison de l'API
• Prise en charge du conteneur d’injection de dépendances de service à clé
• Un regard en arrière-plan des points de terminaison d’API minimales
• Organisation des API ASP.NET Core Minimal
• Discussion sur la validation Fluent sur GitHub