From 8d13c2fefb0bdb585ec26a793c1edd574b9802b5 Mon Sep 17 00:00:00 2001 From: recsventures-ops Date: Sat, 12 Sep 2026 17:39:16 +0000 Subject: [PATCH] Add EF Core and async safety Copilot instructions Pins .NET 8+ failures generic csharp.instructions.md does not: no .Result/.Wait, CancellationToken, AsNoTracking, N+1, pagination, DTO projection, thin controllers. MIT. No paid product mention. --- docs/README.instructions.md | 1 + .../ef-core-async-safety.instructions.md | 41 +++++++++++++++++++ 2 files changed, 42 insertions(+) create mode 100644 instructions/ef-core-async-safety.instructions.md diff --git a/docs/README.instructions.md b/docs/README.instructions.md index e6011891a0..f29c704529 100644 --- a/docs/README.instructions.md +++ b/docs/README.instructions.md @@ -99,6 +99,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-instructions) for guidelines on | [DevOps Core Principles](../instructions/devops-core-principles.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdevops-core-principles.instructions.md) | Foundational instructions covering core DevOps principles, culture (CALMS), and key metrics (DORA) to guide GitHub Copilot in understanding and promoting effective software delivery. | | [Dotnet Wpf](../instructions/dotnet-wpf.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdotnet-wpf.instructions.md) | .NET WPF component and application patterns | | [draw.io Diagram Standards](../instructions/draw-io.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdraw-io.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fdraw-io.instructions.md) | Use when creating, editing, or reviewing draw.io diagrams and mxGraph XML in .drawio, .drawio.svg, or .drawio.png files. | +| [EF Core and async safety (ASP.NET Core)](../instructions/ef-core-async-safety.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fef-core-async-safety.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fef-core-async-safety.instructions.md) | EF Core and async safety for ASP.NET Core: no sync-over-async, no N+1, AsNoTracking, pagination, DTO projection | | [Exclude Prompt Data](../instructions/exclude-prompt-data.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fexclude-prompt-data.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fexclude-prompt-data.instructions.md) | Write only the resulting content into files. Never echo prompt instructions, rationale, or meta-commentary into documentation, comments, or code being produced from a prompt. | | [Fedora Administration Guidelines](../instructions/fedora-linux.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ffedora-linux.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Ffedora-linux.instructions.md) | Guidance for Fedora (Red Hat family) systems, dnf workflows, SELinux, and modern systemd practices. | | [Genaiscript](../instructions/genaiscript.instructions.md)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenaiscript.instructions.md)
[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://aka.ms/awesome-copilot/install/instructions?url=vscode-insiders%3Achat-instructions%2Finstall%3Furl%3Dhttps%3A%2F%2Fraw.githubusercontent.com%2Fgithub%2Fawesome-copilot%2Fmain%2Finstructions%2Fgenaiscript.instructions.md) | AI-powered script generation guidelines | diff --git a/instructions/ef-core-async-safety.instructions.md b/instructions/ef-core-async-safety.instructions.md new file mode 100644 index 0000000000..fa7e4d6e4d --- /dev/null +++ b/instructions/ef-core-async-safety.instructions.md @@ -0,0 +1,41 @@ +--- +description: 'EF Core and async safety for ASP.NET Core: no sync-over-async, no N+1, AsNoTracking, pagination, DTO projection' +applyTo: '**/*.cs' +--- + +# EF Core and async safety (ASP.NET Core) + +Frontier C# models still copy JavaScript-shaped patterns: `.Result` on tasks, returning tracked entities from controllers, and N+1 reads. These instructions exist because generic C# guidance does not pin those failures. + +Target .NET 8+ / C# 12+. Assume nullable enabled. + +## Async I/O + +- Async I/O methods return `Task` / `Task` and are suffixed `Async`. Use `ValueTask` only on hot paths that often complete synchronously. +- Never `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()` in application code. Those block a thread and can deadlock. +- No `async void` except real event handlers. Exceptions from `async void` cannot be awaited. +- Flow `CancellationToken cancellationToken = default` as the last parameter through EF Core, `HttpClient`, streams, and delays. +- Do not wrap synchronous I/O in `Task.Run` and call it async. + +## EF Core reads + +- Use `AsNoTracking()` on read-only queries. Change tracking is only for entities you will `SaveChangesAsync`. +- Prevent N+1: `Include` / `ThenInclude`, or project with `Select`. Prefer projection for read models. +- Do not enable lazy-loading proxies in web apps. They hide N+1 during serialization. +- Paginate unbounded queries (`.Skip().Take()` or keyset). Never materialize a whole table. +- Use `AnyAsync(...)` for existence, not `CountAsync() > 0`. +- Do not combine `Include` with a `Select` projection — pick one. +- Consider `AsSplitQuery()` for multiple collection `Include`s. +- Use async EF APIs and pass `CancellationToken`. + +## HTTP boundary + +- Controllers are thin: bind, dispatch, map. No business logic and no direct EF in the controller if a service exists. +- Bind request DTOs. Never bind a domain entity (overposting). +- Return response DTOs, not entities. +- `201 Created` with `Location` for creates; `404` for missing; validation failures as `ProblemDetails`. + +## Logging + +- Use `ILogger` with message templates, not string interpolation. +- Never log secrets or unnecessary PII. Never expose full exception messages to end users.