UKHO.GitHubCopilot.ToolKit dotnet-stack.instructions.md

Microsoft stack .NET architecture guidelines

Overview

These instructions define baseline default technical choices and architectural expectations for repositories that use the Microsoft .NET stack. Apply this guidance only when the target project is actually using .NET application technologies covered by this file.

Scope

Applies to: src/**/*.cs, src/**/*.csproj, src/**/*.sln, src/**/*.razor, src/**/*.json, infra/**/*

• Applies when creating new services, APIs, .NET web front ends, or distributed application wiring.
• Applies when selecting a database or local orchestration approach for a work item.
• The stack choices in this file are defaults for applicable .NET work, not absolute mandates for every project shape.
• When a work item needs a justified deviation from these defaults, document the reason in the relevant project or work-package documentation so the deviation remains reviewable.
• For project-specific UI component guidance, also follow any applicable scoped instruction files.

Instructions

MUST

• Use C# and the repository’s configured .NET SDK/runtime version (follow global.json if present; otherwise check Microsoft Learn to confirm the latest .NET LTS version and target it by default).

• Enable nullable reference types for new .NET projects (<Nullable>enable</Nullable>) and treat new nullable warnings as errors in touched projects when feasible.

• For new HTTP services, prefer Minimal APIs unless a concrete requirement needs an alternative.

• When exposing HTTP endpoints, provide OpenAPI output (for example via Microsoft.AspNetCore.OpenApi) and include health endpoints.

  • OpenAPI SHOULD be mapped only in the Development environment unless explicitly required.
  • Health endpoints SHOULD include separate readiness and liveness probes when the service has dependencies.

• For new .NET web UIs, prefer Blazor when it fits the project’s established technology direction.

• Prefer a Microsoft-aligned data platform choice when the project requires a relational data store.

• Use a migration-based schema workflow when the chosen persistence technology supports it.

• Keep all connection strings and credentials out of source control; use configuration + secret injection (development user-secrets; production secret store/managed identity where applicable).

• Follow /.github/instructions/configuration.instructions.md for operator-managed configuration storage and secret-handling flows.