Genocs.WebApi Agent Reference

This document is optimized for AI-assisted development sessions.

Genocs.WebApi Agent Reference

Purpose

This document is optimized for AI-assisted development sessions. It prioritizes fast retrieval of:

  • What Genocs.WebApi is responsible for
  • Which APIs to call for specific goals
  • Where source of truth lives
  • What constraints and runtime behaviors matter

Quick Facts

KeyValue
PackageGenocs.WebApi
Project filesrc/Genocs.WebApi/Genocs.WebApi.csproj
Target frameworksnet10.0, net9.0, net8.0
Primary roleASP.NET Core Web API conventions, endpoint mapping, request binding, and error handling for Genocs applications
Core themesWeb API bootstrap, endpoint builder DSL, request/response helpers, exception middleware, JSON serialization

Use This Package When

  • You need a consistent way to register Web API conventions with Genocs builder.
  • You want a compact endpoint DSL for GET/POST/PUT/DELETE with auth/policy wiring.
  • You need request DTO binding from body/query/route plus validation in minimal APIs.
  • You want centralized exception-to-response mapping middleware.
  • You need JSON formatter control and serializer abstraction integration.

Do Not Assume

  • AddWebApi does not add error middleware by itself; call AddErrorHandler and UseErrorHandler explicitly.
  • Handler auto-registration only works for assemblies already loaded in AppDomain.
  • UseAllForwardedHeaders resets known networks/proxies by default, which changes trust boundaries.

High-Value Entry Points

Builder and service registration

Pipeline wiring and infrastructure

Endpoint DSL and metadata

Request dispatch and handlers

JSON and formatter pipeline

HTTP context helpers

Decision Matrix For Agents

GoalPreferred APINotes
Bootstrap Web API conventionsAddWebApiRegisters serializer, MVC core, formatters, request handlers, and defaults
Add global exception mappingAddErrorHandler + UseErrorHandlerAddErrorHandler registers middleware and mapper, UseErrorHandler inserts middleware
Map HTTP endpoints with authUseEndpoints + IEndpointsBuilderSupports roles/policies/auth toggle and endpoint metadata capture
Bind query-based request modelEndpointsBuilder.Get/Delete + ReadQueryReads route and query string into DTO via serializer
Bind JSON body request modelEndpointsBuilder.Post/Put + ReadJsonAsyncHandles deserialize, optional route overlay, and validation
Dispatch application request handlersIRequestDispatcher.DispatchAsyncUses scoped handler resolution per dispatch
Return standard HTTP responsesHttpResponse extension helpersUse Ok/Created/Accepted/NoContent/NotFound/Forbidden for consistency
Forward reverse-proxy headersUseAllForwardedHeadersDefault behavior clears known proxies/networks for broad forwarding

Minimal Integration Recipe

Install 

dotnet add package Genocs.WebApi

Setup in Program.cs 

using Genocs.Core.Builders;
using Genocs.WebApi;

var builder = WebApplication.CreateBuilder(args);

IGenocsBuilder genocs = builder.AddGenocs();

genocs
    .AddWebApi()
    .AddErrorHandler<MyExceptionToResponseMapper>();

genocs.Build();

var app = builder.Build();

app.UseErrorHandler();
app.UseAllForwardedHeaders();
app.UseEndpoints(endpoints =>
{
    endpoints.Get("/health", async ctx => await ctx.Response.Ok(new { status = "ok" }));
});

app.Run();

Behavior Notes That Affect Agent Decisions

  • AddWebApi uses TryRegister(“webApi”), so repeated calls are ignored after first registration.
  • If Newtonsoft serializer is supplied, synchronous IO is enabled for Kestrel (and IIS only on supported target frameworks).
  • ReadJsonAsync can bind route values into private backing fields when BindRequestFromRoute is enabled in webApi options.
  • ReadJsonAsync performs DataAnnotations validation and returns HTTP 400 with validation payload on failure.
  • ErrorHandlerMiddleware writes mapped response as JSON and falls back to HTTP 400 with empty body when mapper returns null.

Source-Accurate Capability Map

Web API bootstrap capabilities

  • Registers serializer abstraction and HTTP context accessor.
  • Configures MVC core with custom JSON input/output formatters.
  • Registers IRequestHandler<,> implementations by assembly scanning.
  • Registers IRequestDispatcher and a default empty exception mapper.

Files:

Endpoint composition capabilities

  • Maps GET/POST/PUT/DELETE endpoints with typed and untyped overloads.
  • Applies authorization, role, or policy requirements per endpoint.
  • Builds endpoint metadata (method/path/parameters/responses) for downstream usage.
  • Supports query-style and body-style request DTO handling paths.

Files:

Request and handler dispatch capabilities

  • Defines marker request contract and typed handler interface.
  • Dispatches request handlers via DI scope isolation.
  • Provides HttpContext-based dispatch helper for endpoint code.
  • Keeps request processing abstraction independent from controller inheritance.

Files:

Error handling capabilities

  • Catches unhandled exceptions in middleware.
  • Maps exceptions via pluggable IExceptionToResponseMapper.
  • Writes mapped response payloads with JSON serializer abstraction.
  • Logs exceptions with structured logging through ILogger.

Files:

Serialization and formatting capabilities

  • Uses pluggable IJsonSerializer for request and response payloads.
  • Implements formatter-based MVC JSON read/write behavior.
  • Exposes formatter resolver for Utf8Json scenarios.
  • Includes JSON key-value parser utility for config-like payload parsing.

Files:

HTTP helper capabilities

  • Provides response helper methods for common status codes.
  • Reads query and route data into typed request objects.
  • Supports route argument extraction with conversion.
  • Supports object bind helpers for immutable-style request DTOs.

Files:

Dependencies

From src/Genocs.WebApi/Genocs.WebApi.csproj:

  • Genocs.Core
  • Open.Serialization.Json.System
  • Open.Serialization.Json.Utf8Json
  • Microsoft.AspNetCore.App framework reference
Last modified on March 21, 2026
Edit this page on GitHub
← Genocs.Saga.Integrations.Redis Agent Reference
Genocs.WebApi.CQRS Agent Reference →