Cross.Headers 1.3.0

.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. 
dotnet add package Cross.Headers --version 1.3.0
                    


                    

                
NuGet\Install-Package Cross.Headers -Version 1.3.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Cross.Headers" Version="1.3.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Cross.Headers" Version="1.3.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Cross.Headers" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Cross.Headers --version 1.3.0
                    


                    

                
#r "nuget: Cross.Headers, 1.3.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Cross.Headers@1.3.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Cross.Headers&version=1.3.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Cross.Headers&version=1.3.0
                    


                            Install as a Cake Tool

License GitHub Release Date NuGetVersion NugetDownloads Coverage issues .NET PR

Size GitHub contributors GitHub commits since latest release (by date) Activity Activity Activity

Cross.Headers

ASP.NET Core middleware boilerplate for handling correlation id, security headers (CSP), and user context based on configuration and OpenIdConnect authentication. Provides IHeadersContextAccessor as a scoped service for request-scoped access to correlation id, system/business ids, language, currency, user-agent, and authenticated user data.

Target frameworks: net6.0, net7.0, net8.0, net9.0, net10.0

Features

  • AddHeaders — registers IHeadersContextAccessor as scoped.
  • HeadersMiddleware — reads technical request headers into context and writes correlation id + CSP to the response.
  • DefaultHeadersMiddleware — applies defaults when headers are missing (SystemId, BusinessId, CountryCode, LanguageCode, CurrencyCode).
  • UserHeadersMiddleware — fills user id/name/scopes/claims from HttpContext.User (after authentication).
  • IHeadersContextAccessor.MapFrom — copies mapped context fields between accessors (including UserClaims).

Install NuGet package

Install the Cross.Headers NuGet package into your .NET project:

Install-Package Cross.Headers

or

dotnet add package Cross.Headers

Request headers

Header Context property Notes
X-Correlation-Id CorrelationId Generated when missing or invalid
X-System-Id SystemId Default 1
X-Business-Id BusinessId Default 1
X-Country-Code CountryCode ISO 3166-1 alpha-2 (e.g. UA, US); default from CountryDefault or US
X-Language-Code LanguageCode ISO 639-1 (e.g. EN, RU, UK); Ukrainian language = UK, not UA
X-Currency-Code CurrencyCode ISO 4217 (e.g. EUR, USD); default from CurrencyDefault or USD
User-Agent UserAgent / UserAgentKind Detects Android/iOS app markers and mobile browsers
Authorization UserAccessToken Optional Bearer prefix is stripped

IHeadersContextAccessor

IHeadersContextAccessor is registered as a scoped service. Inject it via DI anywhere in your application (controllers, services, middleware) to access request-scoped context populated by the middleware pipeline. Within a single HTTP request, the same instance is shared across all consumers.

public interface IHeadersContextAccessor
{
    Guid CorrelationId { get; set; }
    int SystemId { get; set; }
    int BusinessId { get; set; }
    string? CountryCode { get; set; }
    string? LanguageCode { get; set; }
    string? CurrencyCode { get; set; }
    string? UserAgent { get; set; }
    UserAgentKindEnum UserAgentKind { get; set; }
    Guid UserId { get; set; }
    string? UserName { get; set; }
    string? UserAccessToken { get; set; }
    IReadOnlyCollection<Claim> UserClaims { get; set; }
    IReadOnlyCollection<string> UserPermissions { get; set; }
    IReadOnlyCollection<string> UserScopes { get; set; }
    bool IsUser { get; set; }
}

Library usage

Services registration

builder.Services.AddHeaders(builder.Configuration);

AddHeaders registers IHeadersContextAccessor as a scoped service.

Also configure OpenIdConnect authentication and set defaults in configuration:

{
  "CountryDefault": "US",
  "LanguageDefault": "EN",
  "CurrencyDefault": "USD",
  "CSPFrameAncestors": "'self'"
}

Configure middleware

Add the middleware in this exact order:

// CORS MUST be before middleware that reads headers, so preflight (OPTIONS) requests are handled correctly
app.UseCors("UI");

// If your middleware reads headers and builds context — place it AFTER CORS, otherwise it will receive preflight requests
app.UseMiddleware<HeadersMiddleware>();
app.UseMiddleware<DefaultHeadersMiddleware>();

app.UseAuthentication();  // should be before UseMvc() / MapControllers()
app.UseMiddleware<UserHeadersMiddleware>();
app.UseAuthorization();   // should be before UseMvc() / MapControllers()

Cross.Headers middleware:

  • HeadersMiddleware — reads technical headers (correlation id, system/business/country id, language, currency, user-agent, access token, etc.), builds the main context, and adds technical headers to the response (correlation id and CSP).
  • DefaultHeadersMiddleware — fills default values in IHeadersContextAccessor when headers are missing (SystemId, BusinessId, CountryCode, LanguageCode, CurrencyCode).
  • UserHeadersMiddleware — extracts user data from HttpContext.User (UserId, UserName, IsUser, scopes/permissions, claims) into IHeadersContextAccessor.

Release notes

See ReleaseNotes.txt and GitHub Releases.

Contributing

  1. Fork the repository.
  2. Create a feature branch (git checkout -b feature/your-change).
  3. Commit your changes with a clear message.
  4. Push the branch and open a pull request.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.3.0 166 11/2/2026
1.3.0-preview.2 52 11/2/2026
1.3.0-preview.1 58 11/2/2026
1.2.1 1,357 3/25/2026
1.2.0 229 3/25/2026
1.2.0-preview.9 96 3/25/2026
1.2.0-preview.8 89 3/25/2026
1.2.0-preview.7 91 3/25/2026
1.2.0-preview.6 94 3/25/2026
1.2.0-preview.5 82 3/25/2026
1.2.0-preview.4 88 3/25/2026
1.1.1 142 3/25/2026
1.1.1-preview.2 91 3/25/2026
1.1.0 141 3/7/2026
1.1.0-preview.3 95 3/7/2026
1.0.1 141 3/6/2026
1.0.1-preview.1 90 3/6/2026
1.0.0 407 2/24/2026

Added X-Country-Code / CountryCode and CountryDefault; README and tests updated.