Delen via

Aangepaste ASP.NET Core-middleware schrijven

Opmerking

Dit is niet de nieuwste versie van dit artikel. Zie de .NET 9-versie van dit artikel voor de huidige release.

Waarschuwing

Deze versie van ASP.NET Core wordt niet meer ondersteund. Zie het .NET- en .NET Core-ondersteuningsbeleid voor meer informatie. Zie de .NET 9-versie van dit artikel voor de huidige release.

Belangrijk

Deze informatie heeft betrekking op een pre-releaseproduct dat aanzienlijk kan worden gewijzigd voordat het commercieel wordt uitgebracht. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

Zie de .NET 9-versie van dit artikel voor de huidige release.

Door Fiyaz Hasan, Rick Anderson en Steve Smith

Middleware is software dat wordt geïntegreerd in een applicatiepijplijn om verzoeken en antwoorden af te handelen. ASP.NET Core biedt een uitgebreide set ingebouwde middlewareonderdelen, maar in sommige scenario's kunt u een aangepaste middleware schrijven.

In dit onderwerp wordt beschreven hoe u middleware op basis van conventies schrijft. Zie Middleware-activatie via factories in ASP.NET Core voor een benadering die gebruikmaakt van sterke typen en activering per aanvraag.

Middlewareklasse

Middleware wordt over het algemeen ingekapseld in een klasse en weergegeven met een extensiemethode. Houd rekening met de volgende inline-middleware, waarmee de cultuur voor de huidige aanvraag vanuit een querytekenreeks wordt ingesteld:

using System.Globalization;

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

app.UseHttpsRedirection();

app.Use(async (context, next) =>
{
    var cultureQuery = context.Request.Query["culture"];
    if (!string.IsNullOrWhiteSpace(cultureQuery))
    {
        var culture = new CultureInfo(cultureQuery);

        CultureInfo.CurrentCulture = culture;
        CultureInfo.CurrentUICulture = culture;
    }

    // Call the next delegate/middleware in the pipeline.
    await next(context);
});

app.Run(async (context) =>
{
    await context.Response.WriteAsync(
        $"CurrentCulture.DisplayName: {CultureInfo.CurrentCulture.DisplayName}");
});

app.Run();

De voorgaande gemarkeerde inline-middleware wordt gebruikt om te demonstreren hoe een middleware-component te maken door aan te roepen Microsoft.AspNetCore.Builder.UseExtensions.Use. Met de voorgaande Use extensiemethode wordt er een in-line gedefinieerde middleware-delegate toegevoegd aan de aanvraagpijplijn van de toepassing.

Er zijn twee overbelastingen beschikbaar voor de Use extensie:

  • Men neemt een HttpContext en een Func<Task>. Roep de Func<Task> zonder parameters aan.
  • De andere neemt een HttpContext en een RequestDelegate. Roep de RequestDelegate aan door het doorgeven van de HttpContext.

Gebruik liever de latere overbelasting omdat er twee interne toewijzingen per aanvraag worden opgeslagen die vereist zijn bij het gebruik van de andere overbelasting.

Test de middleware door de cultuur door te geven. Bijvoorbeeld: verzoek https://localhost:5001/?culture=es-es.

Zie Globalization and localization in ASP.NET Core voor de ingebouwde lokalisatieondersteuning van ASP.NET Core.

Met de volgende code wordt de middleware-gemachtigde naar een klasse verplaatst:

using System.Globalization;

namespace Middleware.Example;

public class RequestCultureMiddleware
{
    private readonly RequestDelegate _next;

    public RequestCultureMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var cultureQuery = context.Request.Query["culture"];
        if (!string.IsNullOrWhiteSpace(cultureQuery))
        {
            var culture = new CultureInfo(cultureQuery);

            CultureInfo.CurrentCulture = culture;
            CultureInfo.CurrentUICulture = culture;
        }

        // Call the next delegate/middleware in the pipeline.
        await _next(context);
    }
}

De middlewareklasse moet het volgende bevatten:

  • Een openbare constructor met een parameter van het type RequestDelegate.
  • Een openbare methode met de naam Invoke of InvokeAsync. Deze methode moet:
    • Retourneer een Task.
    • Accepteer een eerste parameter van het type HttpContext.

Aanvullende parameters voor de constructor en Invoke/InvokeAsync worden gevuld door afhankelijkheidsinjectie (DI).

Normaal gesproken wordt er een extensiemethode gemaakt om de middleware beschikbaar te maken via IApplicationBuilder:

using System.Globalization;

namespace Middleware.Example;

public class RequestCultureMiddleware
{
    private readonly RequestDelegate _next;

    public RequestCultureMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        var cultureQuery = context.Request.Query["culture"];
        if (!string.IsNullOrWhiteSpace(cultureQuery))
        {
            var culture = new CultureInfo(cultureQuery);

            CultureInfo.CurrentCulture = culture;
            CultureInfo.CurrentUICulture = culture;
        }

        // Call the next delegate/middleware in the pipeline.
        await _next(context);
    }
}

public static class RequestCultureMiddlewareExtensions
{
    public static IApplicationBuilder UseRequestCulture(
        this IApplicationBuilder builder)
    {
        return builder.UseMiddleware<RequestCultureMiddleware>();
    }
}

Met de volgende code wordt de middleware aanroepen van Program.cs:

using Middleware.Example;
using System.Globalization;

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

app.UseHttpsRedirection();

app.UseRequestCulture();

app.Run(async (context) =>
{
    await context.Response.WriteAsync(
        $"CurrentCulture.DisplayName: {CultureInfo.CurrentCulture.DisplayName}");
});

app.Run();

Middleware-afhankelijkheden

Middleware moet het Principe van Expliciete Afhankelijkheden volgen door zijn afhankelijkheden in de constructor zichtbaar te maken. Middleware wordt eenmaal per levensduur van de toepassing samengesteld.

Middleware-onderdelen kunnen hun afhankelijkheden van afhankelijkheidsinjectie (DI) oplossen via constructorparameters. UseMiddleware kan ook rechtstreeks aanvullende parameters accepteren.

Middleware-afhankelijkheden per aanvraag

Middleware wordt gebouwd bij het opstarten van de app en heeft daarom de levensduur van de toepassing. Scoped-levensduurservices die worden gebruikt door middlewareconstructors, worden niet gedeeld met andere geïnjecteerde afhankelijke typen tijdens elke aanvraag. Als u een scoped service wilt delen tussen middleware en andere typen, voegt u deze services toe aan de handtekening van de InvokeAsync methode. De InvokeAsync methode kan aanvullende parameters accepteren die worden ingevuld door DI:

namespace Middleware.Example;

public class MyCustomMiddleware
{
    private readonly RequestDelegate _next;

    public MyCustomMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // IMessageWriter is injected into InvokeAsync
    public async Task InvokeAsync(HttpContext httpContext, IMessageWriter svc)
    {
        svc.Write(DateTime.Now.Ticks.ToString());
        await _next(httpContext);
    }
}

public static class MyCustomMiddlewareExtensions
{
    public static IApplicationBuilder UseMyCustomMiddleware(
        this IApplicationBuilder builder)
    {
        return builder.UseMiddleware<MyCustomMiddleware>();
    }
}

Levensduur- en registratieopties bevatten een volledig voorbeeld van middleware met scoped levensduurservices.

De volgende code wordt gebruikt om de voorgaande middleware te testen:

using Middleware.Example;
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddScoped<IMessageWriter, LoggingMessageWriter>();

var app = builder.Build();

app.UseHttpsRedirection();

app.UseMyCustomMiddleware();

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

app.Run();

De IMessageWriter interface en implementatie:

namespace Middleware.Example;

public interface IMessageWriter
{
    void Write(string message);
}

public class LoggingMessageWriter : IMessageWriter
{

    private readonly ILogger<LoggingMessageWriter> _logger;

    public LoggingMessageWriter(ILogger<LoggingMessageWriter> logger) =>
        _logger = logger;

    public void Write(string message) =>
        _logger.LogInformation(message);
}

Aanvullende bronnen

Door Rick Anderson en Steve Smith

Middleware is software dat wordt geïntegreerd in een applicatiepijplijn om verzoeken en antwoorden af te handelen. ASP.NET Core biedt een uitgebreide set ingebouwde middlewareonderdelen, maar in sommige scenario's kunt u een aangepaste middleware schrijven.

Opmerking

In dit onderwerp wordt beschreven hoe u middleware op basis van conventies schrijft. Zie Middleware-activering gebaseerd op factories in ASP.NET Core voor een benadering die gebruikmaakt van sterke typen en activering per aanvraag.

Middlewareklasse

Middleware wordt over het algemeen ingekapseld in een klasse en weergegeven met een extensiemethode. Houd rekening met de volgende middleware, waarmee de cultuur voor de huidige aanvraag vanuit een querytekenreeks wordt ingesteld:

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.Use(async (context, next) =>
        {
            var cultureQuery = context.Request.Query["culture"];
            if (!string.IsNullOrWhiteSpace(cultureQuery))
            {
                var culture = new CultureInfo(cultureQuery);

                CultureInfo.CurrentCulture = culture;
                CultureInfo.CurrentUICulture = culture;
            }

            // Call the next delegate/middleware in the pipeline
            await next();
        });

        app.Run(async (context) =>
        {
            await context.Response.WriteAsync(
                $"Hello {CultureInfo.CurrentCulture.DisplayName}");
        });

    }
}

De voorgaande voorbeeldcode wordt gebruikt om het maken van een middlewareonderdeel te demonstreren. Zie Globalization and localization in ASP.NET Core voor de ingebouwde lokalisatieondersteuning van ASP.NET Core.

Test de middleware door de cultuur door te geven. Bijvoorbeeld: verzoek https://localhost:5001/?culture=no.

Met de volgende code wordt de middleware-gemachtigde naar een klasse verplaatst:

using Microsoft.AspNetCore.Http;
using System.Globalization;
using System.Threading.Tasks;

namespace Culture
{
    public class RequestCultureMiddleware
    {
        private readonly RequestDelegate _next;

        public RequestCultureMiddleware(RequestDelegate next)
        {
            _next = next;
        }

        public async Task InvokeAsync(HttpContext context)
        {
            var cultureQuery = context.Request.Query["culture"];
            if (!string.IsNullOrWhiteSpace(cultureQuery))
            {
                var culture = new CultureInfo(cultureQuery);

                CultureInfo.CurrentCulture = culture;
                CultureInfo.CurrentUICulture = culture;

            }

            // Call the next delegate/middleware in the pipeline
            await _next(context);
        }
    }
}

De middlewareklasse moet het volgende bevatten:

  • Een openbare constructor met een parameter van het type RequestDelegate.
  • Een openbare methode met de naam Invoke of InvokeAsync. Deze methode moet:
    • Retourneer een Task.
    • Accepteer een eerste parameter van het type HttpContext.

Aanvullende parameters voor de constructor en Invoke/InvokeAsync worden gevuld door afhankelijkheidsinjectie (DI).

Middleware-afhankelijkheden

Middleware moet het Principe van Expliciete Afhankelijkheden volgen door de bijbehorende afhankelijkheden in de constructor weer te geven. Middleware wordt eenmaal per levensduur van de toepassing samengesteld. Zie de sectie Middleware-afhankelijkheden per aanvraag als u services wilt delen met middleware binnen een aanvraag.

Middleware-onderdelen kunnen hun afhankelijkheden van afhankelijkheidsinjectie (DI) oplossen via constructorparameters. UseMiddleware kan ook rechtstreeks aanvullende parameters accepteren.

Middleware-afhankelijkheden per aanvraag

Omdat middleware wordt samengesteld bij het opstarten van apps, niet per aanvraag, worden de scoped levensduurservices die door middleware-constructors worden gebruikt, niet gedeeld met andere typen afhankelijkheden die tijdens elke aanvraag worden geïnjecteerd. Als u een scoped service moet delen tussen uw middleware en andere typen, voegt u deze services toe aan de handtekening van de InvokeAsync methode. De InvokeAsync methode kan aanvullende parameters accepteren die worden ingevuld door DI:

public class CustomMiddleware
{
    private readonly RequestDelegate _next;

    public CustomMiddleware(RequestDelegate next)
    {
        _next = next;
    }

    // IMyScopedService is injected into InvokeAsync
    public async Task InvokeAsync(HttpContext httpContext, IMyScopedService svc)
    {
        svc.MyProperty = 1000;
        await _next(httpContext);
    }
}

Levensduur- en registratieopties bevatten een volledig voorbeeld van middleware met scoped levensduurservices.

Middleware-extensiemethode

De volgende extensiemethode maakt de middleware beschikbaar via IApplicationBuilder:

using Microsoft.AspNetCore.Builder;

namespace Culture
{
    public static class RequestCultureMiddlewareExtensions
    {
        public static IApplicationBuilder UseRequestCulture(
            this IApplicationBuilder builder)
        {
            return builder.UseMiddleware<RequestCultureMiddleware>();
        }
    }
}

Met de volgende code wordt de middleware aanroepen van Startup.Configure:

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        app.UseRequestCulture();

        app.Run(async (context) =>
        {
            await context.Response.WriteAsync(
                $"Hello {CultureInfo.CurrentCulture.DisplayName}");
        });
    }
}

Aanvullende bronnen