Skip to content
Draft
Show file tree
Hide file tree
Changes from 7 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
13 changes: 13 additions & 0 deletions .github/instructions/testing.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ applyTo: "**/tests/**,**/*Test*.cs"
src/Microsoft.Data.SqlClient/tests/
├── Common/ # TestCommon utilities shared across test projects
├── FunctionalTests/ # Tests without SQL Server dependency
├── AuthenticationTests/ # Fresh-process configuration/runtime and trim/AOT fixtures
├── ManualTests/ # Integration tests requiring SQL Server
├── PerformanceTests/ # Benchmark-style perf validation
├── StressTests/ # Long-running stress coverage
Expand All @@ -22,6 +23,18 @@ src/Microsoft.Data.SqlClient/tests/

## Test Categories

### Authentication executable scenarios

Keep non-xUnit authentication configuration and publish consumers in
`src/Microsoft.Data.SqlClient/tests/AuthenticationTests/`, not inside Abstractions unit tests.
Use `build.proj -t:TestAuthentication` with explicit `ReferenceType=Project` or `Package`;
Package mode prepares real local sibling packages. Use an isolated `NUGET_PACKAGES` and
unique `PackageVersionSqlClient` to avoid stale family images. The focused configuration
target remains available. `AuthenticationPublish=true` adds Linux
net10.0 linux-x64 trimmed/NativeAOT publishes and executions with warnings as errors.
Windows executes net462 scenarios; Linux cross-builds are not Windows runtime validation.
`BuildAuthenticationTests` is part of `BuildTests`; ordinary unit tests stay separate.

### Unit Tests (`UnitTests/`)
- Test individual components in isolation
- No external dependencies (database, network)
Expand Down
59 changes: 55 additions & 4 deletions BUILDGUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,55 @@ package the project. The `build.proj` file provides convenient targets to accomp
> This section is not exhaustive of all targets or parameters to `build.proj`. Complete documentation is available in
> [`build.proj`](build.proj).

### Authentication configuration compatibility checks

The executable fixtures under `src/Microsoft.Data.SqlClient/tests/AuthenticationTests/`
run in separate processes to validate both current and legacy app.config section
declarations, their forwarded handler types, initializer activation and configured
provider precedence, without SQL Server or identity-service access.

```bash
dotnet build build.proj -t:TestAuthenticationConfiguration -p:Configuration=Release -p:TestFramework=net10.0 -p:ReferenceType=Project
dotnet build build.proj -t:TestAuthenticationConfiguration -p:Configuration=Release -p:TestFramework=net10.0 -p:ReferenceType=Package
```

Package mode prepares local packages unless `-p:SkipDependencyPack=true` is supplied.
Use `-p:PackageVersionSqlClient=<version>` for prebuilt packages and an isolated
`NUGET_PACKAGES` directory when validating package changes to avoid stale cache entries.
On Windows, select `-p:TestFramework=net462` to execute .NET Framework checks.
Cross-building .NET Framework on Linux does not execute those scenarios.

`TestAuthentication` runs the complete configuration/discovery/precedence matrix,
invalid provider/initializer/unsupported-provider recovery checks and
disabled switches. Add `AuthenticationPublish=true`
on Linux to publish **and execute** linux-x64 trimmed and NativeAOT consumers with
compiler/linker warnings as errors. GCC and the NativeAOT prerequisites are required.

```bash
dotnet build build.proj -t:TestAuthentication -p:Configuration=Release -p:TestFramework=net10.0 -p:ReferenceType=Project -p:AuthenticationPublish=true -p:PackageVersionSqlClient=8.0.0-stack.6
dotnet build build.proj -t:TestAuthentication -p:Configuration=Release -p:TestFramework=net10.0 -p:ReferenceType=Package -p:AuthenticationPublish=true -p:PackageVersionSqlClient=8.0.0-stack.6
```

The Package target prepares Logging, Abstractions, SqlServer, SqlClient and Azure
through the normal pack targets. The fixtures use conditional package references,
verify local family packages exist and inspect restored assets; Package mode never
falls back to project references. Use a unique family version and isolated
`NUGET_PACKAGES` for each changed package image. Build number, suffix, file/package
versions, configuration and reference mode flow to all fixtures; the runner freezes
the computed family version before building so every fixture uses the same package graph.

`BuildAuthenticationTests` builds scenario fixtures without executing them and is
included in `BuildTests`. When `TestFramework` is unset, it builds both net462 and
net10.0; an explicit value selects a single framework. Scenario execution preserves
generated runtime settings, including .NET Framework assembly-binding redirects,
and restores the original configuration afterward. Both fixtures are in the solution.
The focused targets remain available; ordinary xUnit tests are unchanged. See the
[authentication harness README](src/Microsoft.Data.SqlClient/tests/AuthenticationTests/README.md).
The modern `sqlclient-pr` pipeline's authentication stage independently builds and runs
Project **and** Package jobs
on Linux (net10.0, trim/AOT) and Windows (net462), with isolated caches and no assumed
artifact downloads. The legacy PR/CI pipelines do not run this stage.

### Building Projects

From the root of your repository, run `dotnet build` against `build.proj` with a build target, following this pattern:
Expand Down Expand Up @@ -213,6 +262,9 @@ dotnet build -t:<test_target> [optional_parameters]
|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| `Test` | Runs the driver and extension test targets. Without `TestFramework`, all declared frameworks are attempted, including .NET Framework. _This takes considerable time and requires configured servers_. |
| `TestAbstractions` | Runs all tests for Microsoft.Data.SqlClient.Extensions.Abstractions |
| `TestAuthenticationConfiguration` | Runs the dedicated current/legacy app.config compatibility scenarios without SQL Server. |
| `TestAuthentication` | Runs all authentication executable scenarios; optionally publishes and executes trimmed/NativeAOT consumers with `AuthenticationPublish=true`. |
| `BuildAuthenticationTests` | Builds the scenario fixtures without executing them; included in `BuildTests`. |
| `TestAkvProvider` | Runs the unit test project for Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider. |
| `TestAzure` | Runs all tests for Microsoft.Data.SqlClient.Extensions.Azure |
| `TestSqlClient` | Runs the unit, functional, and manual test projects for Microsoft.Data.SqlClient. |
Expand Down Expand Up @@ -241,10 +293,9 @@ grant in Package mode. Pass `-p:ReferenceType=Package` together with `SigningKey
The test project still references Abstractions directly; its Logging dependency follows the
selected reference mode. Signed Project builds intentionally omit test access.

The executable current/legacy app.config compatibility harness is deferred to
[#4817](https://github.com/dotnet/SqlClient/pull/4817); its scenario project and test target are
not available in this layer. Executing `net462` tests requires Windows; a Linux cross-build is
not runtime validation.
The executable current/legacy app.config compatibility harness is available through
`TestAuthenticationConfiguration` and `TestAuthentication`, as described above.
Executing `net462` tests requires Windows; a Linux cross-build is not runtime validation.

> [!TIP]
> In project-reference mode, test targets automatically build their dependencies. In package mode,
Expand Down
32 changes: 31 additions & 1 deletion build.proj
Original file line number Diff line number Diff line change
Expand Up @@ -608,13 +608,43 @@
<SqlClientFunctionalTestProjectPath>$(SqlClientSrcRoot)tests/FunctionalTests/Microsoft.Data.SqlClient.FunctionalTests.csproj</SqlClientFunctionalTestProjectPath>
<SqlClientManualTestProjectPath>$(SqlClientSrcRoot)tests/ManualTests/Microsoft.Data.SqlClient.ManualTests.csproj</SqlClientManualTestProjectPath>
<SqlClientUnitTestProjectPath>$(SqlClientSrcRoot)tests/UnitTests/Microsoft.Data.SqlClient.UnitTests.csproj</SqlClientUnitTestProjectPath>
<AuthenticationTestsScript>$(SqlClientSrcRoot)tests/AuthenticationTests/RunAuthenticationTests.ps1</AuthenticationTestsScript>

<!-- Tools/Specs Paths -->
<GenApiPath>$(RepoRoot)tools/GenAPI/Microsoft.DotNet.GenAPI/</GenApiPath>
<GenApiProjectPath>$(GenApiPath)Microsoft.DotNet.GenAPI.csproj</GenApiProjectPath>
</PropertyGroup>

<!-- Build SqlClient Targets =============================================== -->
<PropertyGroup>
<AuthenticationTestFramework Condition="'$(TestFramework)' != ''">$(TestFramework)</AuthenticationTestFramework>
<AuthenticationTestFramework Condition="'$(AuthenticationTestFramework)' == ''">net10.0</AuthenticationTestFramework>
<AuthenticationPackageVersionArgument Condition="'$(PackageVersionSqlClient)' != ''">-PackageVersionSqlClient "$(PackageVersionSqlClient)"</AuthenticationPackageVersionArgument>
<AuthenticationFileVersionArgument Condition="'$(FileVersionSqlClient)' != ''">-FileVersionSqlClient "$(FileVersionSqlClient)"</AuthenticationFileVersionArgument>
<AuthenticationSqlServerVersionArgument Condition="'$(PackageVersionSqlServer)' != ''">-PackageVersionSqlServer "$(PackageVersionSqlServer)"</AuthenticationSqlServerVersionArgument>
<AuthenticationBuildNumberArgument Condition="'$(BuildNumber)' != ''">-BuildNumber "$(BuildNumber)"</AuthenticationBuildNumberArgument>
<AuthenticationBuildSuffixArgument Condition="'$(BuildSuffix)' != ''">-BuildSuffix "$(BuildSuffix)"</AuthenticationBuildSuffixArgument>
<AuthenticationPublishArgument Condition="'$(AuthenticationPublish)' == 'true'">-Publish</AuthenticationPublishArgument>
<AuthenticationCommand>&quot;$(DotnetPath)dotnet&quot; tool run pwsh -- -NonInteractive -NoProfile -File &quot;$(AuthenticationTestsScript)&quot; -ReferenceType $(ReferenceType) -Configuration $(Configuration) $(AuthenticationPackageVersionArgument) $(AuthenticationFileVersionArgument) $(AuthenticationSqlServerVersionArgument) $(AuthenticationBuildNumberArgument) $(AuthenticationBuildSuffixArgument)</AuthenticationCommand>
<TestAuthenticationConfigurationDependsOn Condition="'$(ReferenceType)' == 'Package' AND '$(SkipDependencyPack)' != 'true'">PackSqlClient;PackAzure</TestAuthenticationConfigurationDependsOn>
</PropertyGroup>
<Target Name="TestAuthenticationConfiguration" DependsOnTargets="$(TestAuthenticationConfigurationDependsOn)">
<Exec Command="$(AuthenticationCommand) -Framework $(AuthenticationTestFramework)"
WorkingDirectory="$(RepoRoot)" />
</Target>
<Target Name="TestAuthentication" DependsOnTargets="$(TestAuthenticationConfigurationDependsOn)">
<Exec Command="$(AuthenticationCommand) -Framework $(AuthenticationTestFramework) -AllScenarios $(AuthenticationPublishArgument)"

Check failure on line 636 in build.proj

View check run for this annotation

Azure Pipelines / sqlclient-pr (Authentication configuration and publishing Authentication Linux Project)

build.proj#L636

build.proj(636,5): Error MSB3073: The command ""dotnet" tool run pwsh -- -NonInteractive -NoProfile -File "/mnt/vss/_work/1/s/src/../src/Microsoft.Data.SqlClient/tests/AuthenticationTests/RunAuthenticationTests.ps1" -ReferenceType Project -Configuration Debug -PackageVersionSqlClient "8.0.0-auth.192864" -BuildNumber "0" -Framework net10.0 -AllScenarios -Publish" exited with code 1.

Check failure on line 636 in build.proj

View check run for this annotation

Azure Pipelines / sqlclient-pr (Authentication configuration and publishing Authentication Linux Package)

build.proj#L636

build.proj(636,5): Error MSB3073: The command ""dotnet" tool run pwsh -- -NonInteractive -NoProfile -File "/mnt/vss/_work/1/s/src/../src/Microsoft.Data.SqlClient/tests/AuthenticationTests/RunAuthenticationTests.ps1" -ReferenceType Package -Configuration Debug -PackageVersionSqlClient "8.0.0-auth.192864" -BuildNumber "0" -Framework net10.0 -AllScenarios -Publish" exited with code 1.

Check failure on line 636 in build.proj

View check run for this annotation

Azure Pipelines / sqlclient-pr (Authentication configuration and publishing Authentication Windows Project)

build.proj#L636

build.proj(636,5): Error MSB3073: The command ""dotnet" tool run pwsh -- -NonInteractive -NoProfile -File "D:\a\_work\1\s\src\..\src/Microsoft.Data.SqlClient/tests/AuthenticationTests/RunAuthenticationTests.ps1" -ReferenceType Project -Configuration Debug -PackageVersionSqlClient "8.0.0-auth.192864" -BuildNumber "0" -Framework net462 -AllScenarios " exited with code 1.

Check failure on line 636 in build.proj

View check run for this annotation

Azure Pipelines / sqlclient-pr (Authentication configuration and publishing Authentication Windows Package)

build.proj#L636

build.proj(636,5): Error MSB3073: The command ""dotnet" tool run pwsh -- -NonInteractive -NoProfile -File "D:\a\_work\1\s\src\..\src/Microsoft.Data.SqlClient/tests/AuthenticationTests/RunAuthenticationTests.ps1" -ReferenceType Package -Configuration Debug -PackageVersionSqlClient "8.0.0-auth.192864" -BuildNumber "0" -Framework net462 -AllScenarios " exited with code 1.
WorkingDirectory="$(RepoRoot)" />
</Target>
<Target Name="BuildAuthenticationTests" DependsOnTargets="$(TestAuthenticationConfigurationDependsOn)">
<ItemGroup>
<_AuthenticationBuildFramework Include="net462;net10.0" Condition="'$(TestFramework)' == ''" />
<_AuthenticationBuildFramework Include="$(TestFramework)" Condition="'$(TestFramework)' != ''" />
</ItemGroup>
<Exec Command="$(AuthenticationCommand) -Framework %(_AuthenticationBuildFramework.Identity) -BuildOnly"
WorkingDirectory="$(RepoRoot)" />
</Target>

<!-- BuildSqlClient: Builds all binaries for SqlClient -->
<Target Name="BuildSqlClient" DependsOnTargets="BuildSqlClientRef;BuildSqlClientNotSupported;BuildSqlClientImpl" />

Expand Down Expand Up @@ -1396,7 +1426,7 @@
</PropertyGroup>

<!-- BuildTests: Builds the driver test projects for their declared target frameworks. -->
<Target Name="BuildTests" DependsOnTargets="BuildAbstractionsTests;BuildAkvProviderTests;BuildSqlClientTestsUnit;BuildSqlClientTestsFunctional;BuildSqlClientTestsManual;BuildSqlClientTestsPerformance;BuildSqlClientTestsStress;BuildAzureTests" />
<Target Name="BuildTests" DependsOnTargets="BuildAbstractionsTests;BuildAkvProviderTests;BuildSqlClientTestsUnit;BuildSqlClientTestsFunctional;BuildSqlClientTestsManual;BuildSqlClientTestsPerformance;BuildSqlClientTestsStress;BuildAzureTests;BuildAuthenticationTests" />
Comment thread
paulmedynski marked this conversation as resolved.
Resolved

<!-- BuildAkvProviderTests: Builds the AKV Provider test project (OS-agnostic). -->
<Target Name="BuildAkvProviderTests">
Expand Down
8 changes: 8 additions & 0 deletions eng/pipelines/pr/sqlclient-pr-pipeline.yml
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,14 @@ stages:
poolName: $(general_purpose_pool_name)
poolImage: ADO-UB24

# Stage 1c: Validate authentication configuration and publishing independently
- template: /eng/pipelines/pr/stages/authentication-validation-stage.yml@self
parameters:
poolName: $(general_purpose_pool_name)
linuxPoolImage: ADO-UB24
windowsPoolImage: ADO-Win25
buildConfiguration: Debug

# Stage 2a: Validate documentation in parallel with tests, using the packed artifacts.
- template: /eng/pipelines/pr/stages/validate-xml-docs-stage.yml@self
parameters:
Expand Down
81 changes: 81 additions & 0 deletions eng/pipelines/pr/stages/authentication-validation-stage.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
#################################################################################
# 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. #
#################################################################################

parameters:
- name: poolName
type: string
- name: linuxPoolImage
type: string
- name: windowsPoolImage
type: string
- name: referenceTypes
type: object
default: [Project, Package]
- name: buildConfiguration
type: string
values: [Debug, Release]

stages:
- stage: test_authentication
displayName: Authentication configuration and publishing
# Each job builds its own inputs through standard targets; no artifact download is assumed.
dependsOn: []
jobs:
- ${{ each referenceType in parameters.referenceTypes }}:
- job: authentication_linux_${{ referenceType }}
displayName: Authentication Linux ${{ referenceType }}
timeoutInMinutes: 90
pool:
name: ${{ parameters.poolName }}
demands:
- imageOverride -equals ${{ parameters.linuxPoolImage }}
variables:
NUGET_PACKAGES: $(Pipeline.Workspace)/authentication-linux-${{ referenceType }}/nuget
steps:
- template: /eng/pipelines/common/steps/install-dotnet.yml@self
parameters:
runtimes: [10.x]
- template: /eng/pipelines/common/steps/restore-dotnet-tools.yml@self
- task: DotNetCoreCLI@2
displayName: Scenarios, trimmed and NativeAOT execution
inputs:
command: custom
custom: build
workingDirectory: $(Build.SourcesDirectory)
arguments: >-
build.proj -t:TestAuthentication
-p:ReferenceType=${{ referenceType }}
-p:Configuration=${{ parameters.buildConfiguration }}
-p:TestFramework=net10.0
-p:PackageVersionSqlClient=8.0.0-auth.$(Build.BuildId)
-p:AuthenticationPublish=true

- job: authentication_windows_${{ referenceType }}
displayName: Authentication Windows ${{ referenceType }}
timeoutInMinutes: 90
pool:
name: ${{ parameters.poolName }}
demands:
- imageOverride -equals ${{ parameters.windowsPoolImage }}
variables:
NUGET_PACKAGES: $(Pipeline.Workspace)/authentication-windows-${{ referenceType }}/nuget
steps:
- template: /eng/pipelines/common/steps/install-dotnet.yml@self
parameters:
runtimes: [10.x]
- template: /eng/pipelines/common/steps/restore-dotnet-tools.yml@self
- task: DotNetCoreCLI@2
displayName: .NET Framework scenarios execution
inputs:
command: custom
custom: build
workingDirectory: $(Build.SourcesDirectory)
arguments: >-
build.proj -t:TestAuthentication
-p:ReferenceType=${{ referenceType }}
-p:Configuration=${{ parameters.buildConfiguration }}
-p:TestFramework=net462
-p:PackageVersionSqlClient=8.0.0-auth.$(Build.BuildId)
Loading
Loading