Merge | Ref Projects

[benrr101]

Description

As much as I want to remove the ref projects, they are tightly coupled to the netstandard binaries and the AnyOS "not supported" binaries. Detangling those will be a headache that we don't need to do right now. So instead, let's at least merge the ref projects into a common ref project just like we did for MDS projects.

The files were broken up differently from netcore, netfx, and netstandard, so I opted to break them down into one file per namespace. This made merging easier, and will likely make maintenance easier in the future.

No changes to the builds were made. Projects were updated to point to the merged files, and a common ref project was added. The solution file was modified slightly to make it clearer the difference between common ref project and common mds project.

This should unblock packing the common project.

Testing

Local builds of the ref projects still works, I presume they will continue to work in CI builds.

[Copilot]

Pull request overview

This PR consolidates the various reference-assembly source files into a shared src/Microsoft.Data.SqlClient/ref/ set (organized roughly by namespace), updates the existing netcore/ref and netfx/ref projects to compile those shared files, and adjusts the solution layout to include the new common ref project—aiming to unblock packing the common project without removing ref projects.

Changes:

• Added a new common ref project (src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.csproj) and split ref sources into multiple shared files under src/Microsoft.Data.SqlClient/ref/.
• Updated src/Microsoft.Data.SqlClient/netcore/ref and src/Microsoft.Data.SqlClient/netfx/ref csproj files to compile the shared ref sources from ../../ref/.
• Updated the solution to add a ref solution folder and include the new common ref project (and re-add the common src project).

Reviewed changes

Copilot reviewed 13 out of 16 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.cs	Adds ref stubs for Microsoft.Data surface (currently has namespace mismatch issues).
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.Sql.cs	Adds ref stubs for Microsoft.Data.Sql surface (contains an auto-property stub issue).
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.csproj	New common multi-targeted ref project for shared ref sources.
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Server.cs	Adds server namespace ref stubs (contains incorrect <include> pathing).
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Diagnostics.cs	Adds diagnostics ref stubs (contains namespace mismatch + malformed XML doc comments + auto-property stub issue).
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.DataClassification.cs	Adds DataClassification ref stubs.
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlTypes.cs	Adds SqlTypes ref stubs (SqlJson/SqlVector/SqlFileStream).
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.cs	Removes old batch ref file (now expected to be covered by merged ref sources).
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlClient.Batch.NetCoreApp.cs	Removes netcoreapp-only batch ref file (now expected to be covered by merged ref sources).
src/Microsoft.Data.SqlClient/netfx/ref/Microsoft.Data.SqlClient.csproj	Points netfx ref project at shared ../../ref/* files (currently missing Diagnostics ref file).
src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.csproj	Points netcore ref project at shared ../../ref/* files (currently missing Diagnostics ref file).
src/Microsoft.Data.SqlClient/netcore/ref/Microsoft.Data.SqlClient.Manual.cs	Removes old manual ref file (expected to be covered by merged ref sources).
src/Microsoft.Data.SqlClient.sln	Adds a ref folder and the new common ref project; adjusts project entries (project type GUID inconsistency).

[paulmedynski]

I have questions about internal/private items being declared, and a lack of access modifiers.

I'm also wondering if it's worth adding a check to the pipelines to ensure that the APIs declared in the ref project are identical to those declared in the implementation. Or perhaps a build target to catch problems pre-commit. It's critical that the APIs are identical, and we've released packages with discrepancies before.

[mdaigle]

I would also like to find a way to more easily compare before and after. Maybe we can leverage this? https://learn.microsoft.com/en-us/dotnet/standard/assembly/inspect-contents-using-metadataloadcontext

[edwardneal]

I think there's already tooling to compare ref assemblies to implementation assemblies - the ApiCompat packages may be useful here.

There are also other similar tools located here (although netstandard2.0 ref assemblies make GenAPI very difficult.) An earlier version of GenAPI is already in the SqlClient source tree.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 20 changed files in this pull request and generated 5 comments.

[paulmedynski]

This will be an interesting experiment to see how well the AI can be instructed to produce precisely the code that we want.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 20 changed files in this pull request and generated 2 comments.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 0.00%. Comparing base (fbf872e) to head (9101645).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@     Coverage Diff      @@
##   main   #3963   +/-   ##
============================
============================

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.