[7.0.4 Cherry-pick] Add evidence-based SqlClient code review skill

.github/copilot-instructions.md

@@ -11,9 +11,9 @@
 
 ## 📚 Project Overview
 This project is a .NET data provider for SQL Server, enabling .NET applications to interact with SQL Server databases. It supports various features like connection pooling, transaction management, and asynchronous operations.
-The project builds from a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj` that multi-targets `net462`, `net8.0`, and `net9.0`. The legacy `netfx/` and `netcore/` directories are being phased out — only their `ref/` folders (which define the public API surface) remain active.
+Driver source and public API declarations are unified under `src/Microsoft.Data.SqlClient/src/` and `src/Microsoft.Data.SqlClient/ref/`, with multi-target projects in both directories. On this release branch, `build.proj` still selects implementation and reference projects under the legacy `netfx/` and `netcore/` directories. Those projects compile the unified sources and remain active build surfaces; preserve them while directing new code and API declarations to the unified directories. Framework and platform selection is defined by the selected projects and imported build files.
 The project includes:
-- **Public APIs**: Defined in `netcore/ref/` and `netfx/ref/` directories.
+- **Public APIs**: Defined by `src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.csproj` and the reference source files beside it.
 - **Implementations**: All source code in `src/Microsoft.Data.SqlClient/src/`.
 - **Tests**: Located in the `tests/` directory, covering unit and integration tests.
   - **Unit Tests**: Located in `tests/UnitTests/` directory, which includes tests for individual components and methods.
@@ -131,7 +131,7 @@ When a new issue is created, follow these steps:
 
 ## 🧠 Contextual Awareness
 - All source code is in `src/Microsoft.Data.SqlClient/src/`. Do NOT add code to legacy `netfx/src/` or `netcore/src/` directories.
-- Only `ref/` folders in `netcore/ref/` and `netfx/ref/` remain active for defining the public API surface.
+- Public API changes must update the unified `src/Microsoft.Data.SqlClient/ref/` sources for each affected target framework.
 - Check for platform-specific differences using file suffixes (`.netfx.cs`, `.netcore.cs`, `.windows.cs`, `.unix.cs`) and conditional compilation (`#if NETFRAMEWORK`, `#if NET`, `#if _WINDOWS`, `#if _UNIX`).
 - Respect API compatibility rules across .NET versions
 - Do not introduce breaking changes without proper justification and documentation

.github/instructions/api-design.instructions.md

@@ -15,10 +15,10 @@ Microsoft.Data.SqlClient follows strict API design guidelines to ensure:
 ### Structure
 ```
 src/Microsoft.Data.SqlClient/
-├── netcore/ref/          # .NET Core/.NET public APIs
-│   └── Microsoft.Data.SqlClient.cs
-└── netfx/ref/            # .NET Framework public APIs
-    └── Microsoft.Data.SqlClient.cs
+└── ref/                              # Unified public API declarations
+    ├── Microsoft.Data.SqlClient.csproj
+    ├── Microsoft.Data.SqlClient.cs
+    └── Microsoft.Data.SqlTypes.cs     # Other namespace-specific files alongside
 ```
 
 ### API Surface
@@ -32,8 +32,8 @@ The reference assemblies do **not** use C# nullable context (`#nullable enable`)
 
 ### Updating Public APIs
 When adding or modifying public APIs:
-1. Update reference assembly in BOTH `netcore/ref/` and `netfx/ref/`
-2. Ensure signatures match across platforms
+1. Update the corresponding sources under `src/Microsoft.Data.SqlClient/ref/`
+2. Ensure signatures match the implementation for each affected framework, including conditional declarations
 3. Add XML documentation
 4. Consider backward compatibility
 5. Do not use nullable annotations (`?`) in ref assemblies (see above)

.github/instructions/architecture.instructions.md

@@ -5,17 +5,20 @@ applyTo: "**"
 
 ## Project Structure
 
-This repository contains the official Microsoft ADO.NET data provider for SQL Server. The driver is built from a **single unified project** that multi-targets all supported frameworks.
+This repository contains the official Microsoft ADO.NET data provider for SQL Server. Driver source and public API declarations are unified, but legacy projects remain active on this release branch during the unified-project migration.
 
 ```
 src/
 ├── Microsoft.Data.SqlClient/
 │   ├── add-ons/                    # Azure Key Vault provider
-│   ├── netcore/                    # ⚠️ LEGACY - being phased out
-│   │   └── ref/                    # Reference assemblies for .NET Core/.NET
-│   ├── netfx/                      # ⚠️ LEGACY - being phased out
-│   │   └── ref/                    # Reference assemblies for .NET Framework
-│   ├── ref/                        # Shared reference assembly files
+│   ├── netcore/                    # Active legacy .NET build projects
+│   │   ├── src/                    # Compiles unified implementation sources
+│   │   └── ref/                    # Compiles unified public API declarations
+│   ├── netfx/                      # Active legacy .NET Framework build projects
+│   │   ├── src/                    # Compiles unified implementation sources
+│   │   └── ref/                    # Compiles unified public API declarations
+│   ├── ref/                        # Unified public API declarations
+│   │   └── Microsoft.Data.SqlClient.csproj # Multi-target reference project
 │   ├── src/                        # ✅ PRIMARY - Unified source for all platforms
 │   │   ├── Microsoft.Data.SqlClient.csproj  # Multi-target project file
 │   │   ├── Interop/               # P/Invoke and native interop
@@ -34,18 +37,15 @@ src/
 ## Unified Project Model
 
 ### Architecture Goal
-The driver is transitioning away from separate `netfx/` and `netcore/` project files toward a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj`. This project multi-targets all supported frameworks from one codebase:
-
-```xml
-<TargetFrameworks>net462;net8.0;net9.0</TargetFrameworks>
-```
+The unified implementation and reference projects are `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj` and `src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.csproj`. They coexist with legacy projects still selected by `build.proj` on this release branch. Check the selected projects and their imported build files for framework and platform selection.
 
 **All new code MUST go into `src/Microsoft.Data.SqlClient/src/`**. Do NOT add files to the legacy `netcore/src/` or `netfx/src/` directories.
 
 ### Legacy Folders
-The `netcore/` and `netfx/` directories are legacy artifacts from the old dual-project model:
-- `netcore/src/` and `netfx/src/` — **DEPRECATED**. These contain legacy project files that are being phased out. Do not add new code here.
-- `netcore/ref/` and `netfx/ref/` — **STILL ACTIVE**. Reference assemblies remain in these directories and define the public API surface for each target framework.
+The `netcore/` and `netfx/` directories remain active build surfaces on this release branch:
+- `build.proj` selects their implementation and reference projects for restore and build.
+- `tools/targets/CompareMdsRefAssemblies.targets` builds and compares both legacy reference projects and the unified reference project.
+- The legacy projects compile sources from the unified `src/` and `ref/` directories. Add new code and API declarations there, not in the legacy trees, and preserve the legacy project files while they remain in use.
 
 ### OS Targeting with `TargetOs`
 The unified project uses a `TargetOs` MSBuild property to handle OS-specific compilation:
@@ -96,12 +96,14 @@ The unified project uses conditional `ItemGroup` elements for dependencies:
 - **Shared**: `Azure.Core`, `Azure.Identity`, `Microsoft.Bcl.Cryptography`, `Microsoft.Extensions.Caching.Memory`, `Microsoft.IdentityModel.*`, `System.Security.Cryptography.Pkcs`
 
 ### Reference Assemblies
-The `ref/` directories define the public API surface:
-- `netcore/ref/` — Public APIs for .NET Core/.NET (includes `Microsoft.Data.SqlClient.cs`, `Microsoft.Data.SqlClient.Manual.cs`)
-- `netfx/ref/` — Public APIs for .NET Framework (includes `Microsoft.Data.SqlClient.cs`)
-- `ref/` — Shared reference assembly files (e.g., `Microsoft.Data.SqlClient.Batch.cs`, `Microsoft.Data.SqlClient.Batch.NetCoreApp.cs`)
-
-**IMPORTANT**: Any public API changes MUST update the corresponding reference assembly in the appropriate `ref/` directory.
+`src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.csproj` builds the unified
+reference sources for `net462`, `net8.0`, `net9.0`, and `netstandard2.0`. Declarations
+are grouped by namespace, with conditional compilation for framework differences.
+The active `netcore/ref/` and `netfx/ref/` projects compile these same source files;
+`CompareMdsRefAssemblies` validates both legacy and unified reference assemblies.
+
+**IMPORTANT**: Public API changes MUST update the corresponding files under
+`src/Microsoft.Data.SqlClient/ref/` for every affected target framework.
 
 ### Build Output
 Build artifacts are organized by framework and OS:

.github/prompts/fix-bug.prompt.md

@@ -37,7 +37,7 @@ Follow this workflow step-by-step:
 - Ensure the fix compiles for ALL target frameworks: `net462`, `net8.0`, `net9.0`.
 - If the fix requires platform-specific code, use the appropriate conditional compilation directives.
 - Do NOT introduce breaking changes to public APIs.
-- If a public API must change, update the reference assemblies in `netcore/ref/` and `netfx/ref/`.
+- If a public API must change, update the corresponding sources under `src/Microsoft.Data.SqlClient/ref/`, including conditional declarations for each affected framework.
 
 ## 5. Validate
 - Verify the failing test now passes with the fix applied.

.github/prompts/implement-feature.prompt.md

@@ -27,10 +27,8 @@ Before writing code, produce a brief implementation plan covering:
 - **Documentation plan** — XML docs, samples, release notes entries.
 
 ## 3. Update Reference Assemblies (if public API changes)
-- If adding new public APIs, update reference assemblies FIRST:
-  - `netcore/ref/Microsoft.Data.SqlClient.cs` and/or `Microsoft.Data.SqlClient.Manual.cs` for .NET Core/.NET APIs
-  - `netfx/ref/Microsoft.Data.SqlClient.cs` for .NET Framework APIs
-  - `ref/` shared files if the API applies to batch or cross-framework features
+- If adding or changing public APIs, update the corresponding namespace-specific sources under `src/Microsoft.Data.SqlClient/ref/` FIRST.
+- Ensure signatures match the implementation for each affected framework, including conditional declarations.
 - Include only the method/property signatures with no implementation.
 - Add XML documentation comments on all public members.