My standard dotnet copilot-instructions.md

copilot-instructions.md

GitHub Copilot Instructions

These instructions define how GitHub Copilot should assist with this project. The goal is to ensure consistent, high-quality code generation aligned with our conventions, stack, and best practices.

🧠 Context

• Project Type: Web Application
• Language: C#
• Framework / Libraries: .NET 9 / ASP.NET Core / Entity Framework Core
• Testing Framework: xUnit, NSubstitute, AwesomeAssertions, TestContainers
• Architecture: Prefer modular monolith over microservices

🔧 General Guidelines

• Use C#-idiomatic patterns and follow .NET coding conventions.
• Use the .editorconfig to configure all style conventions.
• Use PascalCase for class names and methods; camelCase for local variables and parameters.
• Use named methods instead of anonymous lambdas in business logic.
• Use nullable reference types (#nullable enable) and async/await.
• Format using dotnet format or IDE auto-formatting tools.
• Use dotnet outdated to keep dependencies up to date.
• Prioritize readability, testability, and SOLID principles.

🧶 Patterns

✅ Patterns to Follow

• Follow best practices for design patterns (such as Vertical Slice Architecture and API versioning)
• Write XML comments for methods, classes, and properties.
• Use Dependency Injection for services and repositories.
• Use ILogger<T> in all services, controllers, and repositories with debug logging.
• Abstract business logic into services - controllers should be thin.

🚫 Patterns to Avoid

• Don’t use static state or service locators.
• Avoid logic in controllers—delegate to services/handlers.
• Don’t hardcode config—use appsettings.json and IOptions.
• Don’t expose entities directly in API responses.
• Avoid fat controllers and God classes.

Projects, Packages, and Dependencies

• Create a solution using dotnet new sln.
• Create projects using dotnet new with appropriate templates:
  • dotnet new web
  • dotnet new classlib
  • dotnet new xunit
  • dotnet new aspire-apphost
  • dotnet new aspire-servicedefaults
• Use dotnet add package to add NuGet packages. Use the latest stable versions.
• Use dotnet add reference to link projects within the solution.
• Use dotnet sln add to add projects to the solution.
• Avoid editing the .sln and .csproj files manually unless necessary.

Database Guidelines

• Use PostgreSQL postgres:17-alpine (using TestContainers for integration tests)
• Use CITEXT (case-insensitive) and TEXT (normal text) instead of VARCHAR
• Use UUID-OSSP for UUID generation
• Use DbUp based schema upgrades, packaging as a separate console app (for better integration with Aspire)
• Always use a separate (non-"public") schema for storing application tables

🧪 Testing Guidelines

• Use xUnit for unit and integration testing.
• Use NSubstitute for mocking dependencies.
• Use TestContainers for integration tests that require external services (e.g., databases).
• Use AwesomeAssertions for fluent assertions in tests.
• Use AngleSharp for parsing HTML and XML.
• Follow Arrange-Act-Assert pattern in tests.
• Validate edge cases and exceptions.
• Prefer TDD for critical business logic and application services.
• Prefer integration tests with a TestContainer-based database over in-memory tests

UI Implementations

• Desktop: WinUI3
• Web: MVC, Razor Views, organized in areas.
• Client Frameworks: Bootstrap 5, jQuery, bootstrap-icons
• Use Libman to organize libraries

Approved libraries

• AngleSharp
• AutoMapper
• AutoFixture
• AwesomeAssertions
• DbUp
• FastEndpoints
• FluentValidation
• Hangfire
• HotChocolate
• MediatR
• Npgsql
• NSubstitute
• NSwag
• OpenIddict
• Polly
• Quartz.NET
• RabbitMQ
• Refit
• Scalar
• StackExchange.Redis
• TestContainers
• xUnit

Libraries you MUST NOT USE (with Alternatives)

• FluentAssertions (use AwesomeAssertions)
• IdentityServer (use OpenIddict)
• Moq (use NSubstitute)
• NUnit or MSTest (use xUnit)
• Serilog or NLog (use built-in logging for ASP.NET Core or .NET Generic Host)

🔁 Iteration & Review

• Copilot output should be reviewed and modified before committing.
• If code isn’t following these instructions, regenerate with more context or split the task.
• Use /// XML documentation comments to clarify intent for Copilot and future devs.
• Use Visual Studio code inspections to catch violations early.

📚 References

• Microsoft C# Coding Conventions
• ASP.NET Core Documentation
• Entity Framework Core Docs
• xUnit Documentation