Skip to content

About

Service template to use to start the new service development with basic and minimal needed functionality.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Simple Service Template for .NET application

CI Lint Code Base CodeQL

Introduction

This repository is a template for a .NET microservice. It contains a single Web API project (DotNet.ServiceName.Api) with a layered structure (Application, Common), API versioning, API Key authentication, Swagger/OpenAPI documentation, structured logging, health checks with a dashboard, CORS, rate limiting, request timeouts, OpenTelemetry traces and metrics, and two local run modes: .NET Aspire orchestration and a Docker setup with a full observability stack (Grafana, Prometheus, Tempo, Loki and the Aspire dashboard).

Project structure

src/
  DotNet.ServiceName.Api/              # Web API host: controllers, Razor home page, middleware, Swagger/Scalar, auth
  DotNet.ServiceName.Application/      # Business logic, DTOs/facets, service registrations
  DotNet.ServiceName.Common/           # Shared configuration options and extension helpers
  DotNet.ServiceName.AppHost/          # Aspire AppHost: local orchestration of the API and Seq (aspire run)
  DotNet.ServiceName.ServiceDefaults/  # Aspire service defaults: OpenTelemetry, service discovery, HttpClient resilience
tests/
  DotNet.ServiceName.Application.Tests/  # xUnit unit tests (services, mappings, DI)
  DotNet.ServiceName.Api.Tests/          # xUnit integration tests (WebApplicationFactory)

Rename DotNet.ServiceName to your service name across the solution, project folders, namespaces, and the Constants.ApiName value when using the template.

Architecture

The template's runtime story is one OTLP export: the API emits logs, traces and metrics once, and the tooling around it differs only in where that export lands. Seq additionally receives structured logs through its dedicated sink.

Runtime topology of the service template

  • aspire run - the Aspire AppHost wires the export to its dashboard and to Seq; see Aspire (local orchestration).
  • docker compose up - a local OpenTelemetry Collector fans the signals out to Prometheus, Tempo, Loki and an Aspire dashboard container, with Grafana as the UI on top; see Docker observability stack.

The diagram is editable in docs/diagrams/runtime-topology.html - regenerate runtime-topology.png from it when the topology changes.

Tech stack

Application developed and used next technologies (on the backend) and components:

Logging

Service/web application use Serilog to write and generate structure logs with details how application working. It's possible to configure logs to send to the different services like Splunk to monitor in one single place or use other tools to read the logs. Depending on hosting type and where the service wil be placed. Request log entries carry the TraceId, so they can be correlated with the corresponding OpenTelemetry trace.

Authentication (API Key)

Secured endpoints require an API key sent in an HTTP header (X-API-Key by default). The scheme is implemented in ApiKeyAuthenticationHandler and applied via [Authorize(AuthenticationSchemes = ApiKeyAuthenticationHandler.SchemeName)] on controllers. Health check endpoints stay anonymous.

Configuration lives in the ApiKeyOptions section of appsettings.json:

"ApiKeyOptions": {
  "HeaderName": "X-API-Key",
  "ApiKey": "local-dev-api-key"
}

Key points:

  • The key is validated with a constant-time comparison (CryptographicOperations.FixedTimeEquals).
  • Missing/invalid key returns 401 Unauthorized; a valid key is required for all secured endpoints.
  • SwaggerAuth (true in appsettings.json) exposes the security scheme in Swagger UI (Authorize button) and Scalar (persistent authentication) so you can call secured endpoints from both UIs without leaving them.
  • Options are validated on startup (DataAnnotations; FluentValidation variant is available via AddConfigurationWithFluentValidation).
  • For real environments, override the key via environment variables (ApiKeyOptions__ApiKey) or user secrets instead of committing it to source control.

Monitoring

Traces and metrics are exported via OpenTelemetry (OTLP) - see the Telemetry section. Point the exporter at a collector such as Jaeger, Grafana Tempo, or an observability platform to store and visualize them.

Availability and Health check

The service exposes the following health check endpoints:

Endpoint Description
/healthcheck Simple readiness probe (checks tagged ready)
/health Full health report with details
/health/ready Readiness endpoint
/health/live Liveness endpoint
/healthcheck-dashboard Health Checks UI dashboard (when enabled in configuration)

Dashboard customization

The dashboard is a packaged single page application, so it is themed through a custom style sheet that is loaded after its own one. The path is configured relative to wwwroot:

"HealthCheckOptions": {
  "HeaderText": "Simple Service - Health Checks Status",
  "CustomStylesheet": "css/healthcheck-dashboard.css"
}

wwwroot/css/healthcheck-dashboard.css overrides the CSS custom properties the dashboard declares (colors, fonts, surfaces) and follows the system theme with a dark palette. Every text and background pair it introduces is checked for at least WCAG AA contrast (4.5:1) in both palettes - keep it that way when changing a color. The logo comes from wwwroot/images/healthcheck-logo.svg through the --logoImageUrl property - the default logo of the dashboard is a remote image, so replacing it also removes the external request. Use a root relative url('/images/...') in the style sheet, because it is served from /ui/resources/css. Clear CustomStylesheet to fall back to the dashboard defaults; a configured file that is missing in wwwroot is logged as a warning and also falls back to the defaults.

Home page

The root of the service (/) is a Razor Page (src/DotNet.ServiceName.Api/Pages/Index.cshtml) whose links are built from the configuration of the running environment, so a production deployment does not advertise UIs it does not expose. Its content is configured in HomePageOptions:

"HomePageOptions": {
  "Enabled": true,
  "Title": "Simple Service API",
  "Description": "Template service with API Key authorization, health checks and OpenTelemetry",
  "ShowEnvironment": true,
  "ShowDocumentation": true,
  "ShowHealthChecks": true,
  "Links": []
}
Setting Effect
Enabled Serve the page on /. When false, Razor Pages are not registered at all and / returns 404
Title, Description Heading and lead text of the page
ShowEnvironment Show the name of the current environment as a badge
ShowDocumentation Show Swagger, Scalar and Facet Dashboard links - but only when SwaggerEnabled is true for the environment. When they are expected and turned off, the page says that the documentation is not available
ShowHealthChecks Show the health status link, plus the dashboard link when the Health Checks UI is enabled
Links Extra links (title, description, URL, icon, enabled, open in new tab) for anything the configuration above does not cover
DefaultTheme Theme the page starts with: System (default), Light or Dark

The page is a slim top bar (service name, environment badge, theme switch) above the link cards - the name is the only heading of the document, so the page stays a single h1.

The theme switch has three positions (System, Light, Dark): the choice is stored in the browser and applied by wwwroot/js/theme.js before the first paint, so the page never flashes in the wrong theme. The switch is a radio group, so it works with the keyboard and screen readers, and while System is selected the page follows the operating system when its theme changes. DefaultTheme only sets where the switch starts.

Turn the whole page off with Enabled, and tune the content per environment - the shipped appsettings.Production.json is the sample of a production deployment: SwaggerEnabled: false (so no Swagger, Scalar or Facet links), no environment badge and a link to an internal runbook. Styles live in wwwroot/css/home.css and the icons in wwwroot/icons.

Security headers

Non-development environments get a set of security headers applied by NetEscapades.AspNetCore.SecurityHeaders: HSTS (365 days, subdomains included), CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, and Cross-Origin policies. See ApplicationBuilderExtensions.ConfigureSecurityHeaders for the configured policy.

CORS

Cross-origin requests are allowed for the origins listed in configuration. The policy answers preflight (OPTIONS) requests before authentication, so browser clients can send the API key header without an extra round trip:

"CorsPolicyOptions": {
  "Enabled": true,
  "AllowedOrigins": [ "http://localhost:4200", "http://localhost:3000" ],
  "AllowCredentials": false
}

HTTP methods and allowed headers default to the common REST verbs and * - see CorsPolicyOptions for the full list of settings.

Rate limiting

A global fixed-window limiter protects the API from request floods, partitioned by the client IP address (after forwarded headers are processed). Requests over the limit get 429 Too Many Requests with a ProblemDetails body and a Retry-After header. Health check endpoints are exempt so monitoring probes are never throttled:

"RateLimitingOptions": {
  "Enabled": true,
  "PermitLimit": 100,
  "WindowSeconds": 60,
  "QueueLimit": 0
}

Request timeouts

Every request is bounded by a default timeout - slow or stuck handlers are aborted with 503 Service Unavailable instead of holding connections open:

"HttpTimeoutOptions": {
  "DefaultTimeoutSeconds": 30
}

Per-endpoint overrides can be added later with the [RequestTimeout] attribute.

Telemetry (OpenTelemetry)

Traces and metrics are collected with OpenTelemetry and exported over OTLP. When OtlpEndpoint is empty, the standard OTEL_EXPORTER_OTLP_* environment variables are honored (default endpoint: http://localhost:4317):

"TelemetryOptions": {
  "Enabled": true,
  "ServiceName": "dotnet-servicename",
  "ConsoleExporter": false
}

Instrumented out of the box: incoming ASP.NET Core requests, outgoing HttpClient calls, and runtime metrics (GC, threads, memory). Set ConsoleExporter to true to print telemetry locally without a collector. Every Serilog request entry also carries the TraceId, so logs can be correlated with the corresponding trace.

The registration lives in the DotNet.ServiceName.ServiceDefaults project (see Aspire) - Program.cs only calls builder.AddServiceDefaults().

Aspire (local orchestration)

The template ships an Aspire AppHost (DotNet.ServiceName.AppHost) that orchestrates the API and a Seq container for local development, with the Aspire dashboard for structured logs, traces and metrics:

# install the Aspire CLI once (https://aspire.dev/get-started/install-cli/)
curl -sSL https://aspire.dev/install.sh | bash

# run the AppHost from the repository root
aspire run --project src/DotNet.ServiceName.AppHost/DotNet.ServiceName.AppHost.csproj

The dashboard URL is printed by the CLI. What is wired:

  • the seq container is pinned to host port 5341, so the Seq sink configured in appsettings.Local.json keeps working unchanged, and the API waits for it to start
  • the AppHost injects the dashboard OTLP endpoint into the API process (OTEL_EXPORTER_OTLP_ENDPOINT), so traces and metrics flow into the dashboard without any configuration - the service defaults exporter already honors those environment variables
  • Serilog logs are forwarded to the same endpoint as OTLP logs while that variable is present

The DotNet.ServiceName.ServiceDefaults project carries the cross-service plumbing every service of the solution gets: the OpenTelemetry registration driven by TelemetryOptions, a liveness health check, service discovery, and a standard resilience pipeline for outbound HttpClient calls. Unlike the stock Aspire service defaults it does not map its own health endpoints, because the template maps /health, /health/live and /health/ready itself.

docker-compose.yml remains the standalone option (docker compose up --build) - it runs the same API and Seq pair plus a full observability stack without Aspire (see Docker observability stack).

Docker observability stack

When the service runs through docker compose up --build, its telemetry does not stop at the logs: the app exports every signal once to a local OpenTelemetry Collector (docker/otel-collector), which fans it out to four local backends:

Service URL Role
grafana http://localhost:3000 UI over the stored metrics and traces, with the official "ASP.NET Core" dashboards and a provisioned "Service overview" dashboard (no login for local development)
aspire-dashboard http://localhost:18888 the same Aspire dashboard UI as under aspire run, receiving live logs, traces and metrics from the collector
prometheus http://localhost:9090 metrics storage, scraped from the collector; the service_name label allows filtering per service
loki http://localhost:3100 logs storage, pushed as OTLP by the collector; queryable from Grafana (LogQL)
tempo http://localhost:3200 traces storage, queryable from Grafana (TraceQL)

Logs keep flowing to Seq (http://localhost:5341) exactly as before, and the collector also stores them in Loki and forwards them to the Aspire dashboard. The stack is configured entirely through files under docker/ - collector pipeline, Prometheus scrape config, Tempo and Loki storage and Grafana provisioning (datasources + dashboards).

Grafana is provisioned with five dashboards. Four come from the community, vendored into the repository because grafana.com downloads are geo-blocked in some regions: the official "ASP.NET Core" and "ASP.NET Core Endpoint" (from the aspire repository), the runtime-focused "ASP.NET OTEL Metrics" (CPU, memory, GC, thread pool), and the "ASP.NET Core | System overview"

  • the latter originally queries prometheus-net / EventCounters metrics and was adapted to the OpenTelemetry metric names this stack emits (endpoints instead of controllers). The fifth is a small template-specific "Service overview".

Running behind a proxy / load balancer

Forwarded headers are processed, but only a loopback proxy is trusted by default so clients cannot spoof X-Forwarded-*. When running behind a reverse proxy or load balancer, list its IP address in configuration:

"ForwardedHeaders": {
  "KnownProxies": ["10.0.0.5"]
}

Tests

Two xUnit projects cover the solution (40 tests in total):

  • DotNet.ServiceName.Application.Tests - unit tests for services, DTO mapping and DI registration (NSubstitute for mocks).
  • DotNet.ServiceName.Api.Tests - integration tests that boot the whole API in-process with WebApplicationFactory: API Key authentication (401/403/200), ProblemDetails responses, CORS policy (preflight, allowed and disallowed origins), rate limiting (429 with ProblemDetails, health endpoints exempt), health check endpoints, OpenAPI document, and telemetry wiring.
# run everything
dotnet test DotNet.ServiceName.sln

# run a single project or filter by name
dotnet test tests/DotNet.ServiceName.Api.Tests
dotnet test --filter "FullyQualifiedName~RateLimiting"

Build Process for Local Development

  • You have Docker installed - ideally latest version of the tool.
  • You have .NET 10 installed (SDK and runtime). The required version is pinned in global.json; run dotnet --version inside the repository to verify it resolves.
  • Visual Studio 2022 (17.14+) or JetBrains Rider (2024.1+) or Visual Studio Code as IDE - one of them, better for you, all them is appropriate.

Common commands

# restore + build + test
dotnet build DotNet.ServiceName.sln -c Release
dotnet test DotNet.ServiceName.sln -c Release

# format / code style check (CI-friendly)
dotnet format DotNet.ServiceName.sln --verify-no-changes

# build and run in Docker (container listens on port 8080 internally)
docker compose up --build
# then open http://localhost:5050/swagger/index.html or http://localhost:5050/scalar
# observability: http://localhost:3000 (Grafana), http://localhost:18888 (Aspire dashboard),
# http://localhost:9090 (Prometheus), http://localhost:3200 (Tempo), http://localhost:5341 (Seq)

# run with Aspire orchestration (API + Seq + dashboard)
aspire run --project src/DotNet.ServiceName.AppHost/DotNet.ServiceName.AppHost.csproj

# call a secured endpoint (default local key)
curl -H "X-API-Key: local-dev-api-key" http://localhost:5050/api/v1/values

Links

  1. Download .NET

About

Service template to use to start the new service development with basic and minimal needed functionality.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages