Microsoft.AspNetCore.HeaderParsing 9.0.0

Microsoft.AspNetCore.HeaderParsing

This package provides services for strongly typed header parsing and value caching.

In particular:

• There are many different headers with subtle format differences that are hard to parse correctly in all cases. This package provides predefined parsers for commonly used headers.
• Your application may parse the same header value multiple times per request. These APIs automatically cache the parsed values of these headers to make your application faster.
• This package also provides logging and metering of bad header values.

Install the package

From the command-line:

dotnet add package Microsoft.AspNetCore.HeaderParsing

Or directly in the C# project file:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.HeaderParsing" Version="[CURRENTVERSION]" />
</ItemGroup>

Usage Example

Registering the services

The services can be registered using one of the AddHeaderParsing overloads:

public static IServiceCollection AddHeaderParsing(this IServiceCollection services)
public static IServiceCollection AddHeaderParsing(this IServiceCollection services, Action<HeaderParsingOptions> configure)
public static IServiceCollection AddHeaderParsing(this IServiceCollection services, IConfigurationSection section)

For example:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHeaderParsing();

var app = builder.Build();

Registering the parsers

For each header that you want to parse, you need to register an instance of a HeaderSetup class which will define how a named parser should be parsed, and if the resulting strongly-typed values should be cached in memory.

[!NOTE] Instances of HeaderSetup for the most common headers are available in the CommonHeaders class.

[!IMPORTANT] Instances of HeaderSetup should be reused during the application lifetime. It is recommended to keep their reference in objects registered as singletons.

var headerRegistry = app.Services.GetRequiredService<IHeaderRegistry>();

var encodingKey = headerRegistry.Register(CommonHeaders.AcceptEncoding);

Using the parsers

The following example parses the Accept-Encoding request header to return a list of values:

app.MapGet("/", string (HttpContext context) =>
{
    if (context.Request.TryGetHeaderValue(encodingKey, out var encoding))
    {
        return string.Join(", ", encoding);
    }

    return "";
});

List of available common parsers

The CommonHeaders class contains the following reusable header parsers:

• Host
• Accept
• AcceptEncoding
• AcceptLanguage
• CacheControl
• ContentDisposition
• ContentType
• Cookie
• Date
• IfMatch
• IfModifiedSince
• IfNoneMatch
• IfRange
• IfUnmodifiedSince
• Range
• Referer
• XForwardedFor (X-Forwarded-For)

Options

The HeaderParsingOptions class is used to configure common behaviors for this feature.

• You can pre-configure default values to be returned when the current HTTP request contains headers for which you have not configured parsing. See the DefaultValues option.
• You can change the number of cached values using the MaxCachedValuesPerHeader option. If not configured the DefaultMaxCachedValuesPerHeader value will be used.

Metrics

The package generates the following metrics:

Custom headers parsing

Although this package provides support for parsing many HTTP headers, you sometimes need to parse custom headers. You can easily extend the header parsing model to support your custom headers by implementing the abstract class HeaderParser and then register an instance of this class in the IHeaderRegistry interface.

Feedback & Contributing

We welcome feedback and contributions in our GitHub repo.