You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c3c2814
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,9 +11,9 @@
11
11
12
12
## 📚 Project Overview
13
13
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.
14
-
The project builds from a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj`. It targets `net8.0` and `net9.0` on all supported hosts, and adds `net462` only when building on Windows. The legacy `netfx/` and `netcore/` directories are being phased out — only their `ref/` folders (which define the public API surface) remain active.
14
+
The project builds from a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj`, targeting `net462;net10.0`(minimum runtime compatibility: .NET Framework 4.6.2 and .NET 10). Public API declarations are unified under `src/Microsoft.Data.SqlClient/ref/`; reference and unsupported-platform projects additionally preserve `netstandard2.0`. The legacy `netfx/` and `netcore/` directories are no longer used.
15
15
The project includes:
16
-
-**Public APIs**: Defined in `netcore/ref/` and `netfx/ref/` directories.
16
+
-**Public APIs**: Defined by `src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.csproj` and the reference source files beside it.
17
17
-**Implementations**: All source code in `src/Microsoft.Data.SqlClient/src/`.
18
18
-**Tests**: Located in the `tests/` directory, covering unit and integration tests.
19
19
-**Unit Tests**: Located in `src/Microsoft.Data.SqlClient/tests/UnitTests/`.
@@ -51,12 +51,12 @@ This project includes several key products and libraries that facilitate SQL Ser
51
51
-**Logging and Diagnostics**: Provides event source tracing diagnostic capabilities for troubleshooting.
52
52
-**Failover Support**: Handles automatic failover scenarios for high availability.
53
53
- Compatibility switch: `Switch.Microsoft.Data.SqlClient.UseLegacyFailoverAlternationOnLoginSqlErrors` (default `false`) can restore legacy alternation behavior in `LoginWithFailover` for login-phase SQL errors.
54
-
-**Cross-Platform Support**: Compatible with both .NET Framework and .NET Core, allowing applications to run on Windows, Linux, and macOS.
54
+
-**Cross-Platform Support**: Compatible with .NET Framework 4.6.2+ on Windows and .NET 10+ on Windows, Linux, and macOS.
55
55
-**Column Encryption AKV Provider**: Supports Azure Key Vault (AKV) provider for acquiring keys from Azure Key Vault to be used for encryption and decryption.
56
56
57
57
## 🧩 SNI Implementations
58
58
There are two implementations of the SQL Server Network Interface (SNI) layer used in this project:
59
-
-**Managed SNI**: A managed implementation of SNI that is used in .NET Core and .NET 5+ environments. It provides cross-platform support for SQL Server connectivity.
59
+
-**Managed SNI**: A managed implementation of SNI that is used in .NET 10+ environments. It provides cross-platform support for SQL Server connectivity.
60
60
-**Native SNI**: A native implementation of SNI that is used in .NET Framework and .NET Core environments on Windows. It's shipped as part of the `Microsoft.Data.SqlClient.SNI` and `Microsoft.Data.SqlClient.SNI.Runtime` packages.
61
61
-**Microsoft.Data.SqlClient.SNI**: This package provides the native SNI layer for .NET Framework applications.
62
62
-**Microsoft.Data.SqlClient.SNI.Runtime**: This package provides the native SNI layer for .NET Core applications on Windows.
@@ -137,7 +137,7 @@ When a new issue is created, follow these steps:
137
137
138
138
## 🧠 Contextual Awareness
139
139
- All source code is in `src/Microsoft.Data.SqlClient/src/`. Do NOT add code to legacy `netfx/src/` or `netcore/src/` directories.
140
-
-Only `ref/` folders in `netcore/ref/` and `netfx/ref/`remain active for defining the public API surface.
140
+
-Public API changes must update the unified `src/Microsoft.Data.SqlClient/ref/`sources for each affected target framework.
141
141
- 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`).
142
142
- Respect API compatibility rules across .NET versions
143
143
- Do not introduce breaking changes without proper justification and documentation
Guidance for choosing versions of **external (third-party) NuGet package dependencies** in multi-targeted projects (e.g. `net462;net8.0;net9.0`).
6
+
Guidance for choosing versions of **external (third-party) NuGet package dependencies** in multi-targeted projects (e.g. `net462;net10.0`).
7
7
8
8
> **Scope:** This document covers dependencies consumed from NuGet — packages the SqlClient repo does NOT own. For versioning of SqlClient's own inter-sibling packages (Logging, Abstractions, SqlClient, Azure, AKV Provider, SqlServer.Server), see `sqlclient-package-versions.instructions.md`.
9
9
10
10
## Rule
11
-
For runtime-aligned packages, **the package major must match the target runtime major**: 8.x on `net8.0`, 9.x on `net9.0`, 10.x on `net10.0`, and so on. TFMs that aren't tied to a specific runtime major (`net462`, `netstandard2.0`) get the major of the floor LTS. Other categories are versioned as described below.
11
+
For runtime-aligned packages, **the package major must match the target runtime major**: 10.x on `net10.0` in this branch. TFMs that aren't tied to a specific runtime major (`net462`, `net481`, `netstandard2.0`) get the major of the floor LTS. Other categories are versioned as described below.
12
12
13
13
Split package references into three categories:
14
14
@@ -22,21 +22,19 @@ Packages whose major version ships with (or is tightly coupled to) a specific .N
Use the major version that matches the TFM. For TFMs without a corresponding runtime major (`net462`, `netstandard2.0`, etc.), use the major of the **lowest supported modern TFM** — typically the floor LTS (e.g. `8.x` while net8 is supported). This keeps the legacy targets on a long-lived, well-patched band and avoids dragging in transitive deps from a newer major:
25
+
Use the major version that matches the TFM. For TFMs without a corresponding runtime major (`net462`, `net481`, `netstandard2.0`, etc.), use the major of the **lowest supported modern TFM** — currently .NET 10. This keeps the legacy targets on a long-lived, well-patched band and avoids dragging in transitive deps from a newer major:
26
26
27
27
```xml
28
-
<!-- Defaults: lowest supported runtime band (e.g. net8 LTS); also applies to net462 / netstandard2.0 -->
28
+
<!-- Defaults: .NET 10 LTS; also applies to net462 / net481 / netstandard2.0 -->
### 3. Polyfills — **conditional presence, single version**
59
57
60
58
Packages that only exist (or are only needed) on older TFMs. The polyfill major doesn't have to match any runtime band (older TFMs have no in-box equivalent), so pick the latest stable available:
61
59
62
60
```xml
63
-
<ItemGroupCondition="'$(TargetFramework)' == 'netstandard2.0' OR '$(TargetFramework)' == 'net462'">
61
+
<ItemGroupCondition="'$(TargetFramework)' == 'netstandard2.0' OR '$(TargetFramework)' == 'net462' OR '$(TargetFramework)' == 'net481'">
@@ -96,7 +94,7 @@ Look at the "Frameworks" tab on nuget.org or open the `.nupkg`:
96
94
97
95
### 4. Functional test — remove the reference and rebuild
98
96
99
-
The decisive test for the polyfill-vs-runtime-aligned boundary: remove the `PackageReference` on a modern TFM (e.g. net8) and build.
97
+
The decisive test for the polyfill-vs-runtime-aligned boundary: remove the `PackageReference` on the modern TFM (`net10.0`) and build.
100
98
101
99
- Builds clean → package was acting as a polyfill on that TFM. Confirm category 3.
102
100
- Fails with `CS0246`/`CS1061` (missing type or method) → the package contributes API the in-box BCL doesn't have. Treat as runtime-aligned (category 1), even if the description sounds polyfill-ish.
@@ -143,13 +141,13 @@ The reverse (customer's direct version higher than your transitive) resolves cle
143
141
| 10.x | 10.x or higher | Clean |
144
142
| 8.x | 8.x or higher | Clean |
145
143
146
-
Pinning runtime-aligned packages to the **band matching each TFM** means a net8 consumer transitively gets 8.x (no friction with their own 8.x reference), and a net10 consumer transitively gets 10.x.
144
+
For libraries supporting multiple modern runtimes, pinning runtime-aligned packages to the **band matching each TFM** means, for example, a net8 consumer transitively gets 8.x (no friction with their own 8.x reference), and a net10 consumer transitively gets 10.x.
147
145
148
-
Pinning everything to the latest major (e.g. `10.x` unconditionally) forces every net8 customer to roll their direct references forward or hit NU1605.
146
+
In that example, pinning everything to the latest major (e.g. `10.x` unconditionally) forces every net8 customer to roll their direct references forward or hit NU1605. This branch no longer targets net8; its only modern band is `net10.0`, so the current default is 10.x.
149
147
150
148
### Independent packages don't have this problem
151
149
152
-
`Newtonsoft.Json 13.x`, `Azure.Identity 1.17.x`, etc. aren't tied to a runtime version. Customers don't have a "matching" version in mind, and the package's own multi-targeted assets handle TFM selection internally. One version is simpler and avoids needless conditional blocks.
150
+
`Newtonsoft.Json 13.x`, `Azure.Core 1.62.x`, etc. aren't tied to a runtime version. Customers don't have a "matching" version in mind, and the package's own multi-targeted assets handle TFM selection internally. One version is simpler and avoids needless conditional blocks.
153
151
154
152
### Framework-provided assemblies win at runtime anyway
0 commit comments