Cadenza Web

Cadenza.Web

Minimal APIs without ceremony. Top-level Get, Post, Put, Delete. Records bind to JSON. Run starts Kestrel.

#:sdk Cadenza.Web@1.0.15

Base SDK	Microsoft.NET.Sdk.Web
Output	Kestrel-hosted HTTP service
AOT-clean	Yes
Default deploy	Self-contained binary, or container (Deployment Container)

Minimal example

#!/usr/bin/env dotnet run
#:sdk Cadenza.Web@1.0.15

Get("/", () => "Hello from Cadenza.Web");
Get("/health", () => new { status = "ok", time = DateTime.UtcNow });
Post("/echo", (EchoRequest req) => new EchoResponse(req.Message.ToUpper()));

await Run();

record EchoRequest(string Message);
record EchoResponse(string Echoed);

How it works:

• Get / Post / Put / Delete / Map are bare names that wrap ASP.NET Core's Minimal API endpoint routing.
• Records bind from request bodies as JSON automatically.
• Run() builds the WebApplication and starts Kestrel on the configured URLs (default http://localhost:5000 / https://localhost:5001).

Tier 1 surface

Get(path, handler)         // map GET   — returns RouteHandlerBuilder
Post(path, handler)        // map POST  — returns RouteHandlerBuilder
Put(path, handler)         // map PUT
Delete(path, handler)      // map DELETE
Map(path, handler)         // map all methods
Run()                      // build + start Kestrel
UseHttps()                 // UseHttpsRedirection
UseCors(policy = "default")
Web.Services               // IServiceCollection — add DI before any route maps
Web.App                    // raw WebApplication — for middleware not surfaced here

See Tier 1 API for the full catalog including the shared Fs / Sh / Http / Env / Json / Prompt modules.

Configuring the bind URL

Cadenza.Web does not expose its own host configuration helper. Use the standard ASP.NET Core mechanisms.

1. Environment variable (recommended in containers)

ASPNETCORE_URLS=http://0.0.0.0:8080 dotnet run app.cs

2. CLI argument

dotnet run app.cs --urls http://0.0.0.0:8080

3. From code, before Run()

Get("/", () => "hi");

Web.App.Urls.Clear();
Web.App.Urls.Add("http://0.0.0.0:8080");

await Run();

Inside a container, always bind to 0.0.0.0 (not localhost) or external requests can't reach the process. See Deployment Container.

Adding DI services

Web.Services.AddSingleton<IGreeter, HelloGreeter>();

Get("/", (IGreeter g) => g.Greet());

await Run();

interface IGreeter { string Greet(); }
class HelloGreeter : IGreeter { public string Greet() => "hi"; }

The first access to Web.App (including the first Get / Post / Map) builds the WebApplication and freezes the service collection — register everything before any route.

CORS

Web.Services.AddCors(o => o.AddDefaultPolicy(p =>
    p.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader()));

UseCors();   // applies the "default" policy

Get("/", () => "hi");
await Run();

UseCors(name) applies a named policy. Set the policy up via Web.Services first.

Dropping down to ASP.NET Core

The bare names cover the common cases. For everything else, reach for Web.App:

Web.App.UseStaticFiles();
Web.App.UseAuthentication();
Web.App.UseAuthorization();
Web.App.MapHub<ChatHub>("/chat");

Web.App is the actual WebApplication — anything in the ASP.NET Core Minimal API surface works.

When to use it

• HTTP services you want to ship as a single file or container
• Webhooks, internal tools, demo APIs
• The "API half" of a small app where the worker half lives elsewhere

When not to use it

• Multi-project solutions with shared libraries → use a regular .csproj
• Razor / Blazor server apps where the runtime model is the whole point
• Anything that needs static site generation, source generators, or multiple Program.cs entry points

Samples

• samples/web-minimal.cs — Get, Post, record binding
• samples/web-todo-api.cs — small CRUD API in one file

See Samples for the full annotated list.

Shipping

# Single binary
dotnet publish app.cs -c Release --self-contained -r linux-x64

# Container (no Dockerfile)
dotnet publish app.cs --os linux --arch x64 /t:PublishContainer

See Deployment Single Binary and Deployment Container.

See also

• Tier 1 API
• Cadenza Worker — when the same process also runs background loops
• Deployment Container — the 0.0.0.0 caveat in detail