Extrode.NativeWeb.Web 0.1.1

dotnet add package Extrode.NativeWeb.Web --version 0.1.1
                    
NuGet\Install-Package Extrode.NativeWeb.Web -Version 0.1.1
                    
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="Extrode.NativeWeb.Web" Version="0.1.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Extrode.NativeWeb.Web" Version="0.1.1" />
                    
Directory.Packages.props
<PackageReference Include="Extrode.NativeWeb.Web" />
                    
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 Extrode.NativeWeb.Web --version 0.1.1
                    
#r "nuget: Extrode.NativeWeb.Web, 0.1.1"
                    
#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 Extrode.NativeWeb.Web@0.1.1
                    
#: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=Extrode.NativeWeb.Web&version=0.1.1
                    
Install as a Cake Addin
#tool nuget:?package=Extrode.NativeWeb.Web&version=0.1.1
                    
Install as a Cake Tool

nativeweb.web

The pipeline every NativeWeb application puts in front of its own routes: Kestrel limits, forwarded headers, a pooled data source, telemetry, data protection, antiforgery, bot traps, rate limiting, the public-page output cache, security headers, clean URLs, flash banners and content-hashed asset URLs.

If you have written any of the following by hand, this library replaces it. That is not a hypothetical: a consumer of this framework hand-ported five of them, each with a comment naming the file it was copied from, and finished the day before this library completed. Nothing told them it was coming.

You wrote Use instead
A page shell gathering nonce, antiforgery token and locale for the layout Chrome.For(context, assets, antiforgery, locale)
CSP with a per-request nonce, HSTS, permissions policy, referrer policy SecurityHeadersMiddleware — wired by UseNativeWebPipeline
A clean-URL rewrite mapping /about to about.html, with a route map built at startup StaticPagesMiddleware, StaticPagesMiddleware.BuildRouteMap(webRoot)
A one-shot flash-message cookie read on the next render Flash.Set(context, kind, message) / Flash.Take(context)
Content-hashed asset URLs so a stylesheet can be cached forever AssetUrls
A switch on the Accept header, or on .json at the end of the path, in every handler that answers data MapNegotiated

The whole API

Two calls do the work:

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);

NativeWebOptions options = NativeWebOptions.FromConfiguration(builder.Configuration, "MyApp");
builder.AddNativeWebWeb(options, typeof(Program).Assembly);

WebApplication app = builder.Build();
app.UseNativeWebPipeline(Locales.All);
app.MapNativeWebEndpoints(options, typeof(Program).Assembly);

app.Run();

The two take different arguments. UseNativeWebPipeline takes the locale ids the application ships — Locales.All, generated from its own locales/*.json — and an optional Action<IApplicationBuilder> that registers authentication at the one position where antiforgery validation still sees the user. MapNativeWebEndpoints takes the options, which carry the security contact and the readiness window, and the assembly /version reports.

AddNativeWebWeb registers eleven things and hides none of them. Each is a public extension method on NativeWebPipeline, so an application that needs to sit between two of them writes the eleven calls out instead of the one:

Call What it registers
AddNativeWebKestrel the request-body ceiling, and Kestrel's https support — CreateSlimBuilder ships without it
AddNativeWebRequestTimeouts the per-request timeout policy
AddNativeWebDataSource the pooled NpgsqlDataSource
AddNativeWebForwardedHeaders the X-Forwarded-For and X-Forwarded-Proto headers, unwound for the configured known proxies
AddNativeWebResponseCompression Brotli for rendered HTML — configured, see below
AddNativeWebTelemetry OpenTelemetry, opt-in and off by default
AddNativeWebDataProtection the key ring, persisted to the configured directory
AddNativeWebAntiforgery the antiforgery service and cookie
AddNativeWebBotTraps the canary and timing trap
AddNativeWebRateLimiting the general and csp-report policies
AddNativeWebOutputCache the public-page cache policy

Compression is configured but not turned on: AddNativeWebWeb registers it and UseNativeWebPipeline does not call app.UseResponseCompression(). The paved deployment compresses at Caddy instead, which measured 44% faster on the same page and offers zstd. An application with no compressing proxy in front of it adds that one line and picks this configuration up.

AddNativeWebUserSecrets<TProgram> is not part of AddNativeWebWeb and is called separately. It loads user secrets in Development only, and inserts them below the environment variables rather than above: appending is what AddUserSecrets does by default, and it makes the store outrank a real environment variable. That was measured to bite — an integration fixture wrote rows to the database an exported connection string named while the app under test read the one in user secrets, and no failure said why.

Endpoints it maps

MapNativeWebEndpoints mounts /healthz, /readyz, /version, the CSP report collector and /security.txt — the last only when {Section}:SecurityContact is set. MapNativeWebReadiness is separate so an application can mount readiness without the rest.

Rate-limit policy names

NativeWebPipeline.GeneralRateLimitPolicy and CspReportRateLimitPolicy are the string constants to pass to RequireRateLimiting; PublicPagePolicy is the output-cache policy name. ClientIpKey(context) is the partition key those policies use, and is public because a product adding its own policy should partition the same way.

Configuration

One method reads it all: NativeWebOptions.FromConfiguration(configuration, applicationName), with an optional third argument when the configuration section is not the application name. Every key, its default and its failure mode is in docs/02-reference/configuration.md, which a test holds to the source.

Three settings stop the process rather than defaulting — telemetry, the data-protection key directory and the security contact — because the silent version of each failure is invisible. StartupConfigGuards.FailStartup is how: stderr, then exit 78 (StartupConfigGuards.ConfigurationErrorExitCode). Never a modal dialog, which under NativeAOT on Windows a supervisor reads as a hung service rather than an error.

Cacheable public pages

Chrome.Anonymous exists for pages served from the output cache. Every field that would differ between two otherwise-identical responses is empty — no antiforgery token (it would mint a fresh masked token and set a cookie, and OutputCache refuses to store a response carrying Set-Cookie), no nonce (the response is authorized by build-generated script hashes instead), no bot canary (it signs the render instant, so it differs on every call).

A product that grows sign-in adds its identity fields to Chrome as constants in Anonymous: that factory is reached only for a request carrying no session cookie, and passing an identity through it would leak that user's name into a shared cache entry.

Negotiated routes

One route, several representations (spec 021):

app.MapNegotiated("/articles", [Format.Html, Format.Json, Format.Csv], async (http, format) =>
{
    IReadOnlyList<PublishedArticle> rows = await Rows(http);
    return format == Format.Json ? FormatResults.Json(rows, AppJson.Default.IReadOnlyListPublishedArticle)
        : format == Format.Csv ? FormatResults.Csv(Headers, rows.Select(Row))
        : Page(http, rows);
})
.RequireRateLimiting(NativeWebPipeline.GeneralRateLimitPolicy)
.AsPublicPage(csp);

That maps /articles and /articles.{format} to one handler and tells it which of the offers the request chose. The choice is made before the handler runs, by Negotiation.Choose:

Input Chooses
/articles.json, whatever the Accept header says JSON
/articles, Accept: text/csv;q=0.9, text/html;q=0.5 CSV: quality first, then specificity, then header order
/articles, Accept: */* or no header The first offer
/articles.xml 404, text/plain, body Offered: text/html, application/json, text/csv
/articles, Accept: image/png 406, the same body

Neither refusal reaches the handler or its data. The extensionless route says Vary: Accept on every response, wildcard and absent header included; the extension route does not, because its answer does not depend on the header. There is no ?format= query parameter: a query key would have to join the cache's allowlist, and links carrying one rot differently from links carrying an extension. The chosen Format is in HttpContext.Items under Negotiation.ItemKey.

The returned NegotiatedRouteBuilder applies a convention to both routes, so .CacheOutput, .RequireRateLimiting and .AsPublicPage read as they do on any route. Under the public-page policy, PublicPageCachePolicy runs the same chooser and keys the entry on the chosen media type, and refuses to store a response whose Content-Type is not that type, so two cookie-free representations of one path are cached separately and a handler that answered the wrong type is never stored under a key promising the right one. A route whose HTML embeds an antiforgery token takes no cache policy at all: the first visit sets the cookie and is refused, but a return visit sets nothing, is stored, and is served to the next stranger, whose cookie cannot match the token on the page. apps/sample leaves /articles uncached for that reason and declares its cookie-free neighbours (/feed, /sitemap.xml, /robots.txt, /about) with AsPublicPage. The policy never widens what the default policy refused: a request carrying Authorization or an authenticated user neither reads nor fills the shared store.

Templates it delivers

Four partials ship with this library and are contributed to the consumer's compilation by build/NativeWeb.Web.targets, exactly as wwwroot/_nativeweb/ is (spec 029). They render this library's own markup, so a fix to one reaches a product the way a fix to Chrome.cs does.

template filled by
shared/antiforgery.html the token input, named as IAntiforgery names it — Chrome.For supplies both, or a handler reads GetAndStoreTokens itself
shared/bot-traps.html the five fields BotTraps.Inspect reads back, plus the canary from BotTraps.IssueCanary — again via Chrome.For or directly
shared/banner-ok.html Flash.Take's Ok
shared/banner-error.html Flash.Take's Error

Call them by their logical names and nothing else is needed:

{{> shared/antiforgery FieldName=AntiforgeryFieldName Token=AntiforgeryToken}}
{{> shared/bot-traps Canary=BotCanary}}

The {{if}} guard on a banner lives at the call site, not in the partial. A partial whose body is a bare else-less {{if}} is an unclean splice that bails the build-time HTML formatter for every page in the product, so layout/page.html writes:

{{if FlashOk.Length != 0}}{{> shared/banner-ok Message=FlashOk}}{{/if}}

Keeping your own copy of one is a declaration, not a coincidence. Two files at one logical path is a silent last-wins in the render generator, so an undeclared clash is a build error naming the file. Declare <NativeWebTemplateOverride Include="shared\bot-traps.html" /> to keep yours, or set <NativeWebImportTemplates>false</NativeWebImportTemplates> to take none.

What this library does not do

  • No routing, no views, no controllers. Rendering is nativeweb.render; declarative CRUD is nativeweb.scaffold; form binding is nativeweb.forms.
  • No authentication. nativeweb.signin is the relying party; the primitives it builds on are in nativeweb.security.
  • No robots.txt or sitemap.xml of its own. /security.txt is here because it is a fixed-format file with one configurable value. The other two need a route inventory the framework does not own; FormatResults.Sitemap and FormatResults.Text in nativeweb.render write them, and apps/sample/PublicDocuments.cs shows both mapped.

Proved by

tests/nativeweb.web.tests.unit — the options binder, every startup guard, the security headers, the static-page route map and its collision guard, the readiness cache, and the negotiation chooser, routes and cache keys (NegotiationTests, NegotiatedEndpointsTests, NegotiatedCacheTests). BotTrapTemplateTests reads the trap-field constants off BotTraps by reflection and asserts set equality against the name="…" attributes in shared/bot-traps.html, in both directions: the template naming an extra field is as wrong as it naming one fewer. tests/nativeweb.repo.tests.unit/FrameworkTemplateTests.cs refuses a copy reintroduced under a consumer without a declared override, and tests/nativeweb.sample.tests.integration/ContactFlashTests.cs drives shared/banner-ok.html through a real post-redirect-get, and asserts that the response rendering it expires the cookie and that the next one does not render it. shared/banner-error.html has no request-level coverage: nothing in apps/sample sets an error flash, because its one failure path re-renders the form in place to keep what the visitor typed. apps/sample exercises the whole pipeline through a real entry point, and tests/nativeweb.scaffold.tests.e2e drives the published NativeAOT binary.

Product Compatible and additional computed target framework versions.
.NET 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
0.1.1 104 11/3/2026
0.1.0 102 11/3/2026