AOT 5: Enforce exact loaded authentication family versions

BUILDGUIDE.md

@@ -74,6 +74,18 @@ Use `-p:PackageVersionSqlClient=<version>` for prebuilt packages and an isolated
 On Windows, select `-p:TestFramework=net462` to execute .NET Framework checks.
 Cross-building .NET Framework on Linux does not execute those scenarios.
 
+`TestAuthenticationRuntimeVersions` additionally replaces the driver DLL with a
+fixture retaining its assembly binding version but carrying an older informational
+version. Both ordinary bootstrap and bootstrap with configuration/discovery disabled
+must reject it, cache the failure, and trace upgrade/restart guidance:
+
+```bash
+dotnet build build.proj -t:TestAuthenticationRuntimeVersions -p:Configuration=Release -p:TestFramework=net10.0 -p:ReferenceType=Project
+```
+
+The same target accepts `ReferenceType=Package` and the package-preparation options above.
+The runner restores the original DLL even if a scenario fails.
+
 ### Building Projects
 
 From the root of your repository, run `dotnet build` against `build.proj` with a build target, following this pattern:

build.proj

@@ -622,6 +622,10 @@
     <Exec Command="&quot;$(DotnetPath)dotnet&quot; tool run pwsh -- -NonInteractive -NoProfile -File &quot;$(AuthenticationTestsScript)&quot; -Framework $(AuthenticationTestFramework) -ReferenceType $(ReferenceType) -Configuration $(Configuration) $(AuthenticationPackageVersionArgument)"
           WorkingDirectory="$(RepoRoot)" />
   </Target>
+  <Target Name="TestAuthenticationRuntimeVersions" DependsOnTargets="$(TestAuthenticationConfigurationDependsOn)">
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; tool run pwsh -- -NonInteractive -NoProfile -File &quot;$(AuthenticationTestsScript)&quot; -Framework $(AuthenticationTestFramework) -ReferenceType $(ReferenceType) -Configuration $(Configuration) $(AuthenticationPackageVersionArgument) -RuntimeVersions"
+          WorkingDirectory="$(RepoRoot)" />
+  </Target>
 
   <!-- BuildSqlClient: Builds all binaries for SqlClient -->
   <Target Name="BuildSqlClient" DependsOnTargets="BuildSqlClientImpl;BuildSqlClientRef;BuildSqlClientNotSupported" />
@@ -877,7 +881,7 @@
     </PropertyGroup>
     <Message Importance="High" Text=">>> Running manual tests for SqlClient"/>
     <Message Text="    Command: $(DotnetCommand)"/>
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- TestSqlClientUnit: Runs unit tests for SqlClient -->
@@ -906,7 +910,7 @@
     </PropertyGroup>
     <Message Importance="High" Text=">>> Running unit tests for SqlClient"/>
     <Message Text="    Command: $(DotnetCommand)"/>
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- ================================================================= -->

src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/AuthenticationFeatureSwitches.cs

@@ -8,7 +8,7 @@ namespace Microsoft.Data.SqlClient;
 
 /// <summary>
 /// Defines authentication bootstrap switches and capability guards so configuration loading, Azure
-/// extension discovery can be excluded from trimmed or AOT builds.
+/// extension discovery, and runtime version checks can be excluded from trimmed or AOT builds.
 /// </summary>
 /// <remarks>
 /// Configuration and discovery default to enabled to preserve existing runtime behavior.  Each
@@ -55,6 +55,14 @@ internal static class AuthenticationFeatureSwitches
 
     #region Trimming Guards
 
+    /// <summary>Indicates whether bootstrap may inspect loaded SqlClient family assembly versions.</summary>
+    // Fixed trimmed/AOT images cannot replace assemblies; their package graph is checked at build time.
+    [FeatureGuard(typeof(RequiresUnreferencedCodeAttribute))]
+    [FeatureGuard(typeof(RequiresDynamicCodeAttribute))]
+    [UnconditionalSuppressMessage("Trimming", "IL4000",
+        Justification = "Runtime assembly replacement is unavailable in fixed trimmed/AOT images; the package graph is checked at build time.")]
+    internal static bool IsRuntimeVersionValidationSupported => true;
+
     /// <summary>
     /// Guards the reflection-based authentication configuration and initializer loading path.
     /// </summary>

src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/PackageReadme.md

@@ -22,7 +22,7 @@ This package supports:
 ## Authentication registration
 
 The provider registry and bootstrap live in this package. `GetProvider` and `SetProvider`
-work directly, including under NativeAOT, without loading SqlClient through reflection.
+work directly, including under NativeAOT, without a reflective registration bridge to SqlClient.
 Configuration providers and configured initializers take precedence over application
 registrations; application registrations take precedence over the discovered Azure default.
 Registry initialization failures return `null` and `false`, respectively. Null providers,
@@ -48,6 +48,23 @@ each required authentication method before opening connections. The Azure provid
 by `Microsoft.Data.SqlClient.Extensions.Azure`. Publish-time overrides use
 `RuntimeHostConfigurationOption` with `Trim="true"`; runtime changes cannot affect trimming.
 
+## Package version policy
+
+Upgrade all installed SqlClient family packages to the same exact version, including
+prerelease labels: SqlClient, Abstractions, Azure, Logging and AKV. SqlServer.Server
+and native SNI are independently versioned.
+
+Logging supplies the consumer build/transitive checks (`SQLCLIENT001`). Untrimmed
+registry bootstrap also compares the loaded SqlClient and discovered Azure assemblies'
+informational versions against Abstractions, excluding source-control build metadata.
+Mismatches are cached and traced with upgrade/restart guidance; `GetProvider` and
+`SetProvider` return `null` and `false`. Disabling configuration or Azure discovery
+does not disable the SqlClient runtime check.
+
+Trimmed/NativeAOT fixed images remove reflective runtime validation and rely on
+build-time package validation. The emergency `SqlClientEnforceFamilyVersions=false`
+build opt-out does not disable runtime checks or make mixed versions supported.
+
 ## Authentication configuration
 
 The public `SqlAuthenticationProviderConfigurationSection` (legacy

src/Microsoft.Data.SqlClient.Extensions/Abstractions/src/SqlAuthenticationProviderRegistry.cs

@@ -43,7 +43,7 @@ internal sealed class SqlAuthenticationProviderRegistry
     private ExceptionDispatchInfo? _bootstrapFailure;
 
     /// <summary>
-    /// Runs the enabled configuration and Azure discovery steps on first access.
+    /// Runs the enabled version validation, configuration and Azure discovery steps on first access.
     /// </summary>
     /// <remarks>
     /// Reentrant initializer registrations can use the registry while bootstrap is in progress.
@@ -62,6 +62,10 @@ private void EnsureInitialized()
             _initializing = true;
             try
             {
+                if (AuthenticationFeatureSwitches.IsRuntimeVersionValidationSupported)
+                {
+                    ValidateSqlClientVersion();
+                }
                 if (AuthenticationFeatureSwitches.IsAppConfigSupported)
                 {
                     LoadConfiguration();
@@ -125,7 +129,7 @@ private void LoadConfiguration()
     /// Discovers the optional Azure extension and registers its provider as the authentication default.
     /// </summary>
     /// <remarks>
-    /// Validates the extension's public key token in signed builds.
+    /// Validates the extension's family version and, in signed builds, its public key token.
     /// Defaults do not replace existing registrations. Handled loading or construction failures
     /// are logged and leave the application responsible for supplying a provider.
     /// </remarks>
@@ -205,6 +209,7 @@ private void LoadAzureExtension()
                 return;
             }
 
+            ValidateFamilyVersion(assembly);
             SqlClientEventSource.Log.TryTraceEvent(
                 nameof(SqlAuthenticationProviderRegistry) +
                 ": Azure extension assembly={0} found; " +
@@ -693,6 +698,53 @@ private bool Register(SqlAuthenticationMethod authenticationMethod,
         return default;
     }
 
+    /// <summary>Loads SqlClient and validates its exact family version against Abstractions.</summary>
+    /// <remarks>A missing SqlClient assembly is logged and does not prevent registration.</remarks>
+    /// <exception cref="InvalidOperationException">The family versions differ or cannot be determined.</exception>
+    [RequiresUnreferencedCode("The SqlClient assembly is loaded by name for version validation.")]
+    [RequiresDynamicCode("The SqlClient assembly is loaded dynamically.")]
+    private static void ValidateSqlClientVersion()
+    {
+        Assembly assembly;
+        try
+        {
+            assembly = Assembly.Load("Microsoft.Data.SqlClient");
+        }
+        catch (FileNotFoundException e)
+        {
+            SqlClientEventSource.Log.TryTraceEvent(
+                "SqlClient version validation skipped: assembly not installed. {0}", e.Message);
+            return;
+        }
+        ValidateFamilyVersion(assembly);
+    }
+
+    /// <summary>Enforces exact family-version agreement between an assembly and Abstractions.</summary>
+    /// <param name="assembly">The loaded SqlClient family assembly to validate.</param>
+    /// <exception cref="InvalidOperationException">The family versions differ or cannot be determined.</exception>
+    internal static void ValidateFamilyVersion(Assembly assembly)
+    {
+        string expected = GetFamilyVersion(typeof(SqlAuthenticationProvider).Assembly);
+        string actual = GetFamilyVersion(assembly);
+        if (!string.Equals(expected, actual, StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException(
+                $"SqlClient family version mismatch: {assembly.GetName().Name} is {actual}, " +
+                $"but Microsoft.Data.SqlClient.Extensions.Abstractions is {expected}. " +
+                "Upgrade all SqlClient family packages together.");
+        }
+    }
+
+    /// <summary>Reads an assembly's informational version without build metadata.</summary>
+    /// <param name="assembly">The assembly whose family version is required.</param>
+    /// <returns>The version including any prerelease label, but excluding the build metadata suffix.</returns>
+    /// <exception cref="InvalidOperationException">The assembly has no informational version attribute.</exception>
+    private static string GetFamilyVersion(Assembly assembly) =>
+        assembly.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?
+            .InformationalVersion.Split('+')[0]
+            ?? throw new InvalidOperationException(
+                $"Cannot determine the exact SqlClient family version of {assembly.GetName().Name}.");
+
     /// <summary>Maps a configured authentication method name to its enum value, ignoring case.</summary>
     /// <param name="authentication">The authentication method name from a configured provider entry.</param>
     /// <returns>The corresponding supported Active Directory authentication method.</returns>

src/Microsoft.Data.SqlClient.Extensions/Abstractions/test/RuntimeFamilyVersionTest.cs

@@ -0,0 +1,63 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Reflection;
+using System.Reflection.Emit;
+
+namespace Microsoft.Data.SqlClient.Extensions.Abstractions.Test;
+
+/// <summary>Checks exact loaded-family versions independently of assembly binding versions.</summary>
+public class RuntimeFamilyVersionTest
+{
+    /// <summary>The owning assembly is always accepted as the expected family version.</summary>
+    [Fact]
+    public void MatchingRuntimeVersionSucceeds() =>
+        SqlAuthenticationProviderRegistry.ValidateFamilyVersion(typeof(SqlAuthenticationProvider).Assembly);
+
+    /// <summary>Source-control build metadata does not change an otherwise identical package version.</summary>
+    [Fact]
+    public void MatchingVersionWithDifferentBuildMetadataSucceeds()
+    {
+        string expected = typeof(SqlAuthenticationProvider).Assembly
+            .GetCustomAttribute<AssemblyInformationalVersionAttribute>()!.InformationalVersion.Split('+')[0];
+        SqlAuthenticationProviderRegistry.ValidateFamilyVersion(CreateAssembly(expected + "+different.commit"));
+    }
+
+    /// <summary>Different stable or prerelease versions fail with exact versions and upgrade guidance.</summary>
+    [Theory]
+    [InlineData("7.0.1")]
+    [InlineData("1.0.0")]
+    [InlineData("8.0.0-different-preview")]
+    public void MixedRuntimeVersionThrows(string actual)
+    {
+        InvalidOperationException error = Assert.Throws<InvalidOperationException>(
+            () => SqlAuthenticationProviderRegistry.ValidateFamilyVersion(CreateAssembly(actual)));
+        Assert.Contains("version mismatch", error.Message);
+        Assert.Contains(actual, error.Message);
+        Assert.Contains("Microsoft.Data.SqlClient.Extensions.Abstractions", error.Message);
+        Assert.Contains("Upgrade all SqlClient family packages together", error.Message);
+    }
+
+    /// <summary>Assemblies lacking version evidence are rejected rather than silently accepted.</summary>
+    [Fact]
+    public void MissingInformationalVersionThrows()
+    {
+        InvalidOperationException error = Assert.Throws<InvalidOperationException>(
+            () => SqlAuthenticationProviderRegistry.ValidateFamilyVersion(CreateAssembly(null)));
+        Assert.Contains("Cannot determine the exact SqlClient family version", error.Message);
+    }
+
+    /// <summary>Creates an in-memory assembly with controlled version metadata and no filesystem side effects.</summary>
+    private static Assembly CreateAssembly(string? version)
+    {
+        var assembly = AssemblyBuilder.DefineDynamicAssembly(
+            new AssemblyName("RuntimeVersionFixture"), AssemblyBuilderAccess.Run);
+        if (version is not null)
+        {
+            ConstructorInfo constructor = typeof(AssemblyInformationalVersionAttribute).GetConstructor([typeof(string)])!;
+            assembly.SetCustomAttribute(new CustomAttributeBuilder(constructor, [version]));
+        }
+        return assembly;
+    }
+}

src/Microsoft.Data.SqlClient.slnx

@@ -204,6 +204,7 @@
   </Folder>
   <Folder Name="/test/AuthenticationTests/">
     <Project Path="Microsoft.Data.SqlClient/tests/AuthenticationTests/ConfigurationTest/ConfigurationTest.csproj" />
+    <Project Path="Microsoft.Data.SqlClient/tests/AuthenticationTests/RuntimeVersionTest/RuntimeVersionTest.csproj" />
   </Folder>
   <Folder Name="/test/Stress/">
     <Project Path="Microsoft.Data.SqlClient/tests/StressTests/IMonitorLoader/IMonitorLoader.csproj" />

src/Microsoft.Data.SqlClient/src/PackageReadme.md

@@ -78,6 +78,14 @@ on first access. Failed initialization or registration returns `null`/`false` an
 diagnostic guidance through `Microsoft.Data.SqlClient.EventSource` (Informational level,
 Trace keyword `0x2`). Bootstrap failures are cached; correct the cause and restart the application.
 
+Upgrade SqlClient, Abstractions, Azure, Logging and AKV together to the same exact package
+version, including prerelease labels. Logging supplies the `SQLCLIENT001` consumer build
+check. Untrimmed bootstrap also validates loaded SqlClient and discovered Azure informational
+versions against Abstractions; source-control build metadata is ignored. Disabling app.config
+or discovery does not disable the SqlClient runtime check. Fixed trimmed/AOT images remove
+reflective runtime validation and rely on build-time package checks. SqlServer.Server and
+native SNI remain independently versioned.
+
 With this package reference, you can continue to use Entra ID authentication modes directly in your connection string:
 
 ```csharp

src/Microsoft.Data.SqlClient/tests/AuthenticationTests/ConfigurationTest/Program.cs

@@ -4,8 +4,40 @@
 
 using Microsoft.Data.SqlClient;
 using System.Configuration;
+using System.Collections.Concurrent;
+using System.Diagnostics.Tracing;
 
 string scenario = args.Single();
+if (scenario is "bad-runtime" or "bad-runtime-disabled")
+{
+    if (scenario == "bad-runtime-disabled")
+    {
+        AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableAppConfig", false);
+        AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableAzureExtensionDiscovery", false);
+        Require(!SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryDefault, new TestProvider()),
+            "Disabling configuration and discovery bypassed runtime version enforcement.");
+    }
+    else
+    {
+        Require(SqlAuthenticationProvider.GetProvider(SqlAuthenticationMethod.ActiveDirectoryDefault) is null,
+            "Mismatched driver bootstrap returned a provider.");
+    }
+
+    using var listener = new AuthenticationTraceListener();
+    Require(SqlAuthenticationProvider.GetProvider(SqlAuthenticationMethod.ActiveDirectoryDefault) is null,
+        "Cached version failure did not return null.");
+    Require(!SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryDefault, new TestProvider()),
+        "Cached version failure did not return false.");
+    Require(listener.Messages.Any(message => message.Contains("version mismatch") &&
+        message.Contains("7.0.1") && message.Contains("Upgrade all SqlClient family packages together")),
+        "Cached runtime mismatch diagnostics omitted the exact version or corrective guidance.");
+    Require(listener.Messages.Any(message => message.Contains("GetProvider") && message.Contains("restart")) &&
+        listener.Messages.Any(message => message.Contains("SetProvider") && message.Contains("restart")),
+        "Cached version failures did not diagnose both registry entry points.");
+    Console.WriteLine("PASS: " + scenario);
+    return;
+}
+
 string sectionName = scenario switch
 {
     "configured" => "SqlClientAuthenticationProviders",
@@ -57,3 +89,27 @@ public sealed class TestProvider : SqlAuthenticationProvider
     public override Task<SqlAuthenticationToken> AcquireTokenAsync(SqlAuthenticationParameters parameters) =>
         throw new NotSupportedException();
 }
+
+/// <summary>Captures diagnostics when tracing is enabled after the original bootstrap failure.</summary>
+internal sealed class AuthenticationTraceListener : EventListener
+{
+    internal ConcurrentQueue<string> Messages { get; } = new();
+
+    /// <inheritdoc />
+    protected override void OnEventSourceCreated(EventSource eventSource)
+    {
+        if (eventSource.Name == "Microsoft.Data.SqlClient.EventSource")
+        {
+            EnableEvents(eventSource, EventLevel.Informational, (EventKeywords)2);
+        }
+    }
+
+    /// <inheritdoc />
+    protected override void OnEventWritten(EventWrittenEventArgs eventData)
+    {
+        if (eventData.EventId == 3 && eventData.Payload?[0] is string message)
+        {
+            Messages.Enqueue(message);
+        }
+    }
+}

src/Microsoft.Data.SqlClient/tests/AuthenticationTests/RunAuthenticationTests.ps1

@@ -9,7 +9,8 @@ param(
     [string]$ReferenceType = 'Project',
     [ValidateSet('Debug', 'Release')]
     [string]$Configuration = 'Release',
-    [string]$PackageVersionSqlClient
+    [string]$PackageVersionSqlClient,
+    [switch]$RuntimeVersions
 )
 
 $ErrorActionPreference = 'Stop'
@@ -53,3 +54,26 @@ try {
 } finally {
     [System.IO.File]::WriteAllBytes($configPath, $originalConfig)
 }
+
+if ($RuntimeVersions) {
+    $replacementProject = Join-Path $PSScriptRoot 'RuntimeVersionTest/RuntimeVersionTest.csproj'
+    Invoke-DotNet -CommandArguments (@('build', $replacementProject, '-c', $Configuration, '-f', $Framework) + $buildOptions)
+    $driver = Join-Path $output 'Microsoft.Data.SqlClient.dll'
+    $backup = "$driver.$([guid]::NewGuid().ToString('n')).original"
+    Copy-Item -LiteralPath $driver -Destination $backup
+    try {
+        Copy-Item -LiteralPath (Join-Path $PSScriptRoot "RuntimeVersionTest/bin/$Configuration/$Framework/Microsoft.Data.SqlClient.dll") `
+            -Destination $driver -Force
+        foreach ($scenario in @('bad-runtime', 'bad-runtime-disabled')) {
+            if ($Framework -eq 'net462') {
+                & $app $scenario
+                if ($LASTEXITCODE -ne 0) { throw "Runtime version test failed: $scenario" }
+            } else {
+                Invoke-DotNet -CommandArguments @($app, $scenario)
+            }
+        }
+    } finally {
+        Copy-Item -LiteralPath $backup -Destination $driver -Force
+        Remove-Item -LiteralPath $backup
+    }
+}

src/Microsoft.Data.SqlClient/tests/AuthenticationTests/RuntimeVersionTest/RuntimeVersionTest.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <AssemblyName>Microsoft.Data.SqlClient</AssemblyName>
+    <TargetFrameworks>net462;net10.0</TargetFrameworks>
+    <Version>7.0.1</Version>
+    <AssemblyVersion>$(SqlClientAssemblyVersion)</AssemblyVersion>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+</Project>