Skip to content
Merged
Show file tree
Hide file tree
Changes from 9 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions BUILDGUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,50 @@ dotnet build -t:TestSqlClientFunctional -p:TestFramework=net10.0

### Packaging Projects

#### Consumer family-version check

The Microsoft.Data.SqlClient package owns `ValidateSqlClientFamilyPackageVersions` and
ships it as `Microsoft.Data.SqlClient.targets` in both `build/` and `buildTransitive/`.
NuGet imports it into direct consumers and transitive PackageReference consumers (unless
build assets are excluded). When Microsoft.Data.SqlClient is present in the consuming
package graph, it anchors comparisons against installed family members. Installed Logging,
Abstractions, Extensions.Azure, and AKV packages must match the resolved SqlClient version
exactly, including prerelease labels. Optional family packages are not required; independently
versioned Microsoft.SqlServer.Server and native SNI packages are excluded. The target uses
resolved compile/runtime package metadata or the active legacy `packages.config`
(including `packages.<project-name>.config`), not
assembly versions or declared version ranges, and skips design-time builds.
Missing version metadata or a missing SqlClient anchor is not guessed.

**SQLCLIENT001** warns when installed family versions differ; by default, the check
does not fail the build. Upgrade them together; historical extension `1.0.0` versions
are not automatically mapped to driver `7.0.0`/`7.0.1`. To suppress the warning, set
`-p:SqlClientEnforceFamilyVersions=false` (or that property in the consumer
project). It suppresses this check only, not incompatibilities.
NuGet buildTransitive assets can propagate through project-reference chains when a
referenced project consumes SqlClient as a package. Project-mode repository builds
reference SqlClient's source project directly, so they do not import its packaged
targets and are not validated by this consumer target.

Run `dotnet tool restore` first to restore the repository's pinned PowerShell tool.
The regression suite also requires Pester 5.7.1:

```powershell
dotnet tool run pwsh -NoProfile -Command "Install-Module Pester -RequiredVersion 5.7.1 -Repository PSGallery -Scope CurrentUser -Force -ErrorAction Stop"
dotnet tool run pwsh -NoProfile -Command 'Import-Module Pester -RequiredVersion 5.7.1; Invoke-Pester -Path ./src/Microsoft.Data.SqlClient/tests/VersionChecks/VersionChecks.Tests.ps1 -CI'
```

The parameterized Pester suite creates small family-package fixtures in a private local
feed, with the SqlClient fixture carrying the real shipped target, and verifies automatic
imports for both direct and transitive package consumers. It also checks that the real
SqlClient nuspec packs that target into `build/` and `buildTransitive/`, so no driver
build is needed. It uses a unique directory under `tests/VersionChecks` and removes that
directory on completion; no SQL Server is required.
Add `-Tag Synthetic` to `Invoke-Pester` to run only the metadata and legacy manifest
matrix without packing consumer fixtures.
The suite is available for local execution only. PR and OneBranch pipelines do not
install Pester or run these tests.

Just like building and testing the various projects in this repository, packaging the projects into NuGet packages is
also handled by `build.proj`. From the root of your repository, run `dotnet build` against `build.proj` with a pack target,
following this pattern:
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
<!--
Licensed to the .NET Foundation under one or more agreements. The .NET Foundation licenses this
file to you under the MIT license.
-->
<Project>
Comment thread
paulmedynski marked this conversation as resolved.
Resolved
<!-- Microsoft.Data.SqlClient owns the consumer check and ships it in build/ and buildTransitive/.
When SqlClient is present in the consuming package graph, it anchors comparisons against
installed members of the lockstep family. SqlServer.Server and native SNI are independently
versioned. Project references are not package-version evidence.

This is a best-effort helper that surfaces mismatches where it can; it is not a guarantee.
Mixing family package versions is unsupported whether or not this check reports it.
Limitations:
- It relies on .NET SDK/NuGet targets and items (ResolvePackageAssets, ResolveReferences,
and the NuGetPackageId/NuGetPackageVersion metadata). SDKs, project types, or custom
pipelines that omit them, or run them in another order, silently skip the check.
- Multi-targeting outer builds do not resolve references; only inner builds are checked.
- Missing inputs are treated as "nothing to check" rather than guessed.
It does not raise errors on its own: mismatches are warnings, and failures to read inputs
(for example a malformed packages.config) are downgraded to MSBuild warnings. Consumers
that treat warnings as errors still see these as errors. -->
<PropertyGroup>
<SqlClientEnforceFamilyVersions Condition="'$(SqlClientEnforceFamilyVersions)' == ''">true</SqlClientEnforceFamilyVersions>
</PropertyGroup>

<Target Name="ValidateSqlClientFamilyPackageVersions"
AfterTargets="ResolvePackageAssets;ResolveReferences"
Condition="'$(SqlClientEnforceFamilyVersions)' == 'true' And '$(DesignTimeBuild)' != 'true'">
<ItemGroup>
<!-- Collect first, then use qualified metadata so framework/project references without
NuGet metadata cannot cause MSB4096. Include RID-specific runtime-only assets. -->
<_SqlClientResolvedAsset Include="@(ResolvedCompileFileDefinitions);@(ReferencePath);@(RuntimeCopyLocalItems);@(RuntimeTargetsCopyLocalItems)" />
<_SqlClientFamilyAsset Include="@(_SqlClientResolvedAsset)"
Condition="'%(_SqlClientResolvedAsset.NuGetPackageId)' == 'Microsoft.Data.SqlClient' Or
'%(_SqlClientResolvedAsset.NuGetPackageId)' == 'Microsoft.Data.SqlClient.Extensions.Abstractions' Or
'%(_SqlClientResolvedAsset.NuGetPackageId)' == 'Microsoft.Data.SqlClient.Extensions.Azure' Or
'%(_SqlClientResolvedAsset.NuGetPackageId)' == 'Microsoft.Data.SqlClient.Internal.Logging' Or
'%(_SqlClientResolvedAsset.NuGetPackageId)' == 'Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider'">
<FamilyVersion>%(_SqlClientResolvedAsset.NuGetPackageVersion)</FamilyVersion>
<FamilyId>%(_SqlClientResolvedAsset.NuGetPackageId)</FamilyId>
</_SqlClientFamilyAsset>
<_SqlClientAnchorVersion Include="@(_SqlClientFamilyAsset)"
Condition="'%(_SqlClientFamilyAsset.FamilyId)' == 'Microsoft.Data.SqlClient' And '%(_SqlClientFamilyAsset.FamilyVersion)' != ''" />
</ItemGroup>
<PropertyGroup>
<!-- Compare resolved version strings, including prerelease labels, not ranges or assembly
versions. Missing package metadata is not assigned a guessed version. -->
<_SqlClientExpectedFamilyVersion>@(_SqlClientAnchorVersion->'%(FamilyVersion)'->Distinct())</_SqlClientExpectedFamilyVersion>
</PropertyGroup>
<Warning Code="SQLCLIENT001"
Condition="'%(_SqlClientFamilyAsset.FamilyVersion)' != '' And '$(_SqlClientExpectedFamilyVersion)' != '' And '%(_SqlClientFamilyAsset.FamilyVersion)' != '$(_SqlClientExpectedFamilyVersion)'"
Text="SqlClient family version mismatch: %(_SqlClientFamilyAsset.FamilyId) is %(_SqlClientFamilyAsset.FamilyVersion), but Microsoft.Data.SqlClient is $(_SqlClientExpectedFamilyVersion). Upgrade all installed family packages together, including prerelease labels. Suppress warning: SqlClientEnforceFamilyVersions=false." />
Comment thread
paulmedynski marked this conversation as resolved.
Resolved

<!-- Legacy packages.config consumers import build/ explicitly through NuGet installation.
Read installed versions from the manifest, independently of assembly reference metadata. -->
<PropertyGroup>
<!-- Match NuGet: prefer the project-specific manifest, replacing spaces with underscores. -->
<_SqlClientConfigPath Condition="'$(RestoreProjectStyle)' == 'PackagesConfig' Or
('$(RestoreProjectStyle)' == '' And '@(PackageReference)' == '')">$(MSBuildProjectDirectory)/packages.$(MSBuildProjectName.Replace(' ', '_')).config</_SqlClientConfigPath>
<_SqlClientConfigPath Condition="('$(RestoreProjectStyle)' == 'PackagesConfig' Or
('$(RestoreProjectStyle)' == '' And '@(PackageReference)' == '')) And
!Exists('$(_SqlClientConfigPath)')">$(MSBuildProjectDirectory)/packages.config</_SqlClientConfigPath>
</PropertyGroup>
<XmlPeek XmlInputPath="$(_SqlClientConfigPath)"
Query="/packages/package[translate(@id, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')='microsoft.data.sqlclient']/@version"
Condition="Exists('$(_SqlClientConfigPath)')"
ContinueOnError="WarnAndContinue">
<Output TaskParameter="Result" PropertyName="_SqlClientConfigExpectedVersion" />
</XmlPeek>
<XmlPeek XmlInputPath="$(_SqlClientConfigPath)"
Query="/packages/package[(translate(@id, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')='microsoft.data.sqlclient.internal.logging' or translate(@id, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')='microsoft.data.sqlclient.extensions.abstractions' or translate(@id, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')='microsoft.data.sqlclient' or translate(@id, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')='microsoft.data.sqlclient.extensions.azure' or translate(@id, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', 'abcdefghijklmnopqrstuvwxyz')='microsoft.data.sqlclient.alwaysencrypted.azurekeyvaultprovider') and @version!='$(_SqlClientConfigExpectedVersion)']"
Condition="'$(_SqlClientConfigExpectedVersion)' != ''"
ContinueOnError="WarnAndContinue">
<Output TaskParameter="Result" ItemName="_SqlClientConfigMismatch" />
</XmlPeek>
<Warning Code="SQLCLIENT001"
Condition="'@(_SqlClientConfigMismatch)' != ''"
Text="SqlClient family version mismatch in $(_SqlClientConfigPath): %(_SqlClientConfigMismatch.Identity), but Microsoft.Data.SqlClient is $(_SqlClientConfigExpectedVersion). Upgrade all installed family packages together, including prerelease labels. Suppress warning: SqlClientEnforceFamilyVersions=false." />
</Target>
</Project>
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,10 @@
<file src="..\tools\icons\dotnet.png" target="" />
<file src="..\src\Microsoft.Data.SqlClient\src\PackageReadme.md" target="README.md" />

<!-- Consumer family version check; NuGet imports targets named after the package ID. -->
<file src="..\src\Microsoft.Data.SqlClient\build\Microsoft.Data.SqlClient.targets" target="build\" />
<file src="..\src\Microsoft.Data.SqlClient\build\Microsoft.Data.SqlClient.targets" target="buildTransitive\" />
Comment thread
paulmedynski marked this conversation as resolved.
Resolved

<!--
All file paths are relative to the artifacts directory created by the build, so
the pack flow sets NuspecBasePath to that artifacts directory.
Expand Down
32 changes: 32 additions & 0 deletions src/Microsoft.Data.SqlClient/src/PackageReadme.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,38 @@ This package supports:
The implementation targets `net462;net10.0`. Reference and unsupported-platform assemblies also
retain `netstandard2.0`; that target does not extend supported driver runtimes.

### SqlClient family version validation

This package ships a consumer MSBuild target in `build/` and `buildTransitive/`.
NuGet imports it for direct package consumers and transitive PackageReference
consumers. After package/reference resolution it compares installed
`Microsoft.Data.SqlClient.Internal.Logging`, `Microsoft.Data.SqlClient.Extensions.Abstractions`,
`Microsoft.Data.SqlClient.Extensions.Azure`, and
`Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider` package versions
against the **resolved Microsoft.Data.SqlClient package version**. Optional packages are
not required. `Microsoft.SqlServer.Server` and native SNI packages are excluded.

Versions must match exactly, including prerelease labels; a mismatch emits the
**SQLCLIENT001** warning rather than failing the build by default. Upgrade all installed
family packages together.
Historical extensions numbered `1.0.0` are not mapped to driver `7.0.0`/`7.0.1`.
The check uses resolved compile/runtime asset metadata for PackageReference and
installed versions in the active `packages.config` for legacy consumers. A
`packages.<project-name>.config` file takes precedence over `packages.config`;
spaces in the project name are replaced with underscores, matching NuGet.
It does not check assembly versions, restore ranges, or API compatibility. Assets
missing version metadata and builds without a Microsoft.Data.SqlClient version anchor
are skipped. Design-time builds are skipped.

To suppress the warning, set `SqlClientEnforceFamilyVersions=false` in the
consumer project or pass `-p:SqlClientEnforceFamilyVersions=false`. This disables
only this build check; it does not make mixed versions compatible. Excluding the
package's build assets also prevents target import. NuGet buildTransitive targets
can propagate through project-reference chains when a referenced project consumes
Microsoft.Data.SqlClient as a package. A direct project reference to SqlClient's
source project does not import its packaged targets, so this check does not enforce
in-tree Project-mode versions.

## Installation

Install the package via NuGet:
Expand Down
Loading
Loading