Simplify SqlClient packaging with SDK pack and a generated .NET Standard contract

Start by reading the SqlClient project and packaging files, the existing reference and unsupported-platform projects, and issue #4826; prototype source-based and assembly-based contract generation as the issue requests. Then compare the generated Standard contract with its existing baseline and concrete implementation APIs, and inspect package contents and dependency groups. Done means the acceptance criteria pass, including intermediate-library consumers and signed pack flows.

Is your feature request related to a problem? Please describe.

SqlClient's packaging currently depends on separately maintained public API declarations, a reference assembly project, a generated unsupported-platform assembly project, and a hand-authored nuspec. This duplicates the implementation's API surface, adds build orchestration, and allows the contract and implementation to drift, as documented in #4826.

We want to simplify this to one packable SqlClient project and normal SDK-generated packaging while preserving all three package targets: net462, netstandard2.0, and net10.0.

The netstandard2.0 asset is a compile-time bridge for intermediate libraries. Those libraries ultimately run in an application targeting a concrete supported framework, which must resolve the real net462 or net10.0 implementation. Retaining this bridge does not imply a full .NET Standard runtime implementation.

Describe the solution you'd like

Intended package layout

lib/net462/Microsoft.Data.SqlClient.dll         # Real implementation
lib/netstandard2.0/Microsoft.Data.SqlClient.dll # Generated contract/stub assembly
lib/net10.0/Microsoft.Data.SqlClient.dll        # Real implementation

Include the appropriate XML documentation and localized satellite assemblies. Retain the package readme, icon, existing consumer family-version checks under build/ and buildTransitive/, and separate .snupkg symbols packaging. No managed assemblies should be shipped under ref/ or runtimes/.

Native SNI packages remain dependencies and retain their native runtime assets.

Proposed implementation plan

1. Prototype build-time Standard contract generation from the implementation.

   • Do not maintain a second set of API declaration source files or a handwritten API allowlist.
   • Prefer investigating source-based generation using the implementation's framework-dependent declarations; compare with assembly-based generation using GenAPI or an equivalent tool before committing to the approach.
   • Generate source only under the intermediate output directory, not in source control.
   • Produce Standard-compatible declarations with explicit PlatformNotSupportedException fallback behavior rather than a real Standard driver implementation.
   • Preserve public/protected signatures, generic constraints, constants, relevant attributes, and type forwards. Reuse existing type-forward sources where appropriate.
   • Handle framework-specific API shapes explicitly. For example, the modern SqlBatch derives from DbBatch, which is not available in .NET Standard 2.0. Blindly generating declarations from the .NET 10 assembly is insufficient.
   • Audit conditional compilation: compiling source with neither NET nor NETFRAMEWORK defined does not by itself guarantee the intended Standard API surface.
   • Fail generation when declarations cannot be represented faithfully; do not silently omit APIs.

2. Make the implementation project the single packable SqlClient project.

   • Target net462;netstandard2.0;net10.0.
   • Compile existing implementation sources for the concrete targets and generated contract sources for Standard.
   • Update the AKV provider's Project-mode reference from the reference project to the unified SqlClient project, preserving its Standard target and the intermediate-library scenario.

3. Replace the authored nuspec with normal SDK packaging.

   • Move package metadata and explicit non-binary pack items into project properties/items.
   • Remove custom nuspec token expansion, generated intermediate nuspec handling, and dependency suppression.
   • Generate dependency groups from project/package references while preserving intended bounded sibling version ranges, compile exclusions, and transitive build-asset behavior in both Project and Package reference modes.
   • Review differences between current project references and authored nuspec dependencies rather than accidentally changing the consumer graph.
   • Remove the source nuspec. SDK pack will still generate the normal package manifest.

4. Remove obsolete projects and simplify orchestration.

   • Remove separate ref/notsupported projects, duplicate declarations, solution entries, and build targets.
   • Remove GenAPI tooling only if the selected generation approach and remaining repository uses no longer need it.
   • Build the implementation once in ordinary build/pack flows.
   • Preserve release build -> binary signing -> pack --no-build ordering without rebuilding or modifying signed outputs.

5. Replace safeguards that currently depend on the reference project.

   • Compare generated Standard contracts and concrete implementation public APIs against appropriate baselines, including signatures, attributes, and type forwards.
   • Support historical baselines containing ref/ and future baselines containing only lib/.
   • Update XML documentation validation and remove the separate reference-documentation pipeline step.
   • Decide and document the IntelliSense XML policy: today ref/ has trimmed XML while lib/ has full documentation. Preserve full documentation for the API docs pipeline and explicitly account for any IntelliSense presentation change.
   • Update build orchestration tests, build documentation, and public API contribution guidance.

Acceptance criteria

• SqlClient exposes net462, netstandard2.0, and net10.0 assets under lib/ only, with no packaged ref/ assemblies or managed RID-specific assemblies.
• The Standard contract is generated from the implementation during a clean build; no separately maintained API declarations are required.
• Generated Standard APIs are compared with the existing Standard contract during migration and checked for compatibility with the concrete implementations.
• A netstandard2.0 intermediate library consuming the package builds and runs through both a net462 app and a net10.0 app, with the appropriate real implementation selected.
• The AKV provider builds and tests successfully in both Project and Package modes without retargeting solely because the reference project was removed.
• Standard stub fallback behavior is explicit, including a deliberate policy for static initialization/fields such as SqlClientFactory.Instance (see #4081).
• SDK-generated dependency groups/ranges and package contents are verified in both reference modes.
• Windows .NET Framework and Windows/Linux/macOS .NET 10 package consumers are validated, including RID-less builds, RID-specific publishing, native SNI resolution, and direct lib/ loading with required dependencies available.
• Clean and incremental builds and signed pack --no-build flows work without stale generation or signed-binary replacement.
• Documentation, localization, symbols, and API compatibility gates remain effective.

Describe alternatives you've considered

• Keep handwritten reference declarations: preserves duplicate maintenance and API-drift risk; does not meet the goal.
• Retain separate ref/notsupported projects: can preserve current behavior but does not simplify the build as intended.
• Generate from a concrete implementation assembly: potentially reuses existing GenAPI infrastructure, but requires framework-shape transformations and careful build ordering. Evaluate against source-based generation in the prototype.
• Implement the complete driver for .NET Standard 2.0: substantially larger compatibility/porting effort and unnecessary for the compile-time bridge requirement.
• Remove the Standard target or retarget all intermediate libraries: explicitly out of scope; Standard targeting must remain.

Additional context

Related open issues:

• #4239 - Replace platform-specific builds with runtime OS selection. This effort follows its managed lib/<tfm> layout simplification while retaining the Standard bridge.
• #4826 - ref/ assemblies do not match implementation assembly API surfaces. Generating the contract from implementation should remove the duplicate-maintenance root cause, with compatibility checks retained.
• #4081 - Raise exception on calling SqlClientFactory.Instance from facade assembly. Relevant to explicit, predictable behavior when the generated Standard stub is loaded instead of a concrete implementation.

This issue tracks the broader follow-up: generated Standard contracts, removal of separate ref/notsupported projects, and replacement of the authored nuspec with normal SDK packaging. The generation strategy requires a proof of concept before the detailed implementation is finalized.