Merge remote-tracking branch 'refs/remotes/upstream/main' into dev/mdaigle/pwsh-via-dotnet-tool

# Conflicts:
#	BUILDGUIDE.md
#	eng/pipelines/onebranch/jobs/build-signed-csproj-package-job.yml
#	eng/pipelines/onebranch/jobs/build-signed-sqlclient-package-job.yml
#	tools/targets/CompareMdsRefAssemblies.targets
#	tools/targets/TrimDocsForIntelliSense.targets

Author: mdaigle

.github/copilot-instructions.md

@@ -11,17 +11,18 @@
 
 ## 📚 Project Overview
 This project is a .NET data provider for SQL Server, enabling .NET applications to interact with SQL Server databases. It supports various features like connection pooling, transaction management, and asynchronous operations.
-The project builds from a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj` that multi-targets `net462`, `net8.0`, and `net9.0`. The legacy `netfx/` and `netcore/` directories are being phased out — only their `ref/` folders (which define the public API surface) remain active.
+The project builds from a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj`. It targets `net8.0` and `net9.0` on all supported hosts, and adds `net462` only when building on Windows. The legacy `netfx/` and `netcore/` directories are being phased out — only their `ref/` folders (which define the public API surface) remain active.
 The project includes:
 - **Public APIs**: Defined in `netcore/ref/` and `netfx/ref/` directories.
 - **Implementations**: All source code in `src/Microsoft.Data.SqlClient/src/`.
 - **Tests**: Located in the `tests/` directory, covering unit and integration tests.
-  - **Unit Tests**: Located in `tests/UnitTests/` directory, which includes tests for individual components and methods.
-  - **Functional Tests**: Located in `tests/FunctionalTests/` directory, which includes tests for various features and functionalities that can be run without a SQL Server instance.
-  - **Manual Tests**: Located in `tests/ManualTests/` directory, which includes tests that require a SQL Server instance to run.
+  - **Unit Tests**: Located in `src/Microsoft.Data.SqlClient/tests/UnitTests/`.
+  - **Functional Tests**: Located in `src/Microsoft.Data.SqlClient/tests/FunctionalTests/`.
+  - **Manual Tests**: Located in `src/Microsoft.Data.SqlClient/tests/ManualTests/`.
+  - **Performance/Stress Tests**: Located in `src/Microsoft.Data.SqlClient/tests/PerformanceTests/` and `src/Microsoft.Data.SqlClient/tests/StressTests/`.
 - **Documentation**: Found in the `doc/` directory, including API documentation, usage examples.
 - **Policies**: Contribution guidelines, coding standards, and review policies in the `policy/` directory.
-- **Building**: The project uses MSBuild for building and testing, with configurations and targets defined in the `build.proj` file, whereas instructions are provided in the `BUILDGUIDE.md` file.
+- **Building**: The repo uses `build.proj` for orchestrated build/test/pack workflows, `src/Microsoft.Data.SqlClient.slnx` for solution-centric development tooling, and Azure DevOps YAML under `eng/pipelines/` plus `eng/pipelines/onebranch/` for CI and official release flows. See `BUILDGUIDE.md` for local build details.
 - **CI/CD**: ADO Pipelines for CI/CD and Pull request validation are defined in the `eng/` directory, ensuring code quality and automated testing.
 
 ## 📦 Products

.github/instructions/ado-pipelines.instructions.md

@@ -22,14 +22,14 @@ Top-level CI/PR pipeline files:
 - `dotnet-sqlclient-ci-project-reference-pipeline.yml` — CI with Project references (Release)
 - `sqlclient-pr-package-ref-pipeline.yml` — PR validation with Package references
 - `sqlclient-pr-project-ref-pipeline.yml` — PR validation with Project references
-- `stress-tests-pipeline.yml` — Stress tests triggered after successful CI-Package runs
+- `stress/stress-tests-pipeline.yml` — Stress test pipeline and templates
 
 Reusable templates are organized under:
 - `common/templates/jobs/` — Job templates (`ci-build-nugets-job`, `ci-code-coverage-job`, `ci-run-tests-job`)
 - `common/templates/stages/` — Stage templates (`ci-run-tests-stage`)
 - `common/templates/steps/` — Step templates (build, test, config, publish)
 - `jobs/` — Package-specific CI jobs (pack/test Abstractions, Azure, Logging, stress)
-- `stages/` — Package-specific CI stages (build Logging → Abstractions → SqlClient → Azure → verify → stress)
+- `stages/` — Package-specific CI stages (generate secrets, build SqlServer/Logging/Abstractions/SqlClient/Azure, verify packages)
 - `libraries/` — Shared variables (`ci-build-variables.yml`)
 - `steps/` — SDK install steps
 
@@ -43,25 +43,28 @@ Key parameters:
 - `testJobTimeout` (required) — test job timeout in minutes
 - `targetFrameworks` — Windows test TFMs; default `[net462, net8.0, net9.0, net10.0]`
 - `targetFrameworksUnix` — Unix test TFMs; default `[net8.0, net9.0, net10.0]`
+- `netcoreVersionTestUtils` — default runtime for shared test utilities; default `net10.0`
 - `testSets` — test partitions; default `[1, 2, 3]`
 - `useManagedSNI` — SNI variants to test; default `[false, true]`
 - `runAlwaysEncryptedTests` — include AE test set; default `true`
-- `enableStressTests` — enable stress test stage; default `false`
+- `runLegacySqlTests` — include SQL Server 2016/2017 manual-test legs; default `true`
 - `debug` — enable debug output; default `false`
 - `dotnetVerbosity` — MSBuild verbosity; default `normal`
 
 ## Build Stage Order
 
 Stages execute in dependency order (Package reference mode requires artifacts from prior stages):
 1. `generate_secrets` — Generate test secrets
-2. `build_logging_package_stage` — Build Logging package
-3. `build_abstractions_package_stage` — Build Abstractions (depends on Logging)
-4. `build_sqlclient_package_stage` — Build SqlClient + AKV Provider (depends on Abstractions + Logging)
-5. `build_azure_package_stage` — Build Azure extensions (depends on Abstractions + Logging + SqlClient)
-6. `verify_nuget_packages_stage` — Verify NuGet package metadata
-7. `stress_tests_stage` — Optional stress tests
+2. `build_sqlserver_package_stage` — Build `Microsoft.SqlServer.Server`
+3. `build_logging_package_stage` — Build Logging package
+4. `build_abstractions_package_stage` — Build Abstractions (package mode depends on Logging)
+5. `build_sqlclient_package_stage` — Build SqlClient and produce the AKV provider package
+6. `build_azure_package_stage` — Build Azure extensions
+7. `verify_nuget_packages_stage` — Verify NuGet package metadata
 8. `ci_run_tests_stage` — Run MDS and AKV test suites
 
+Stress testing is no longer a stage threaded through `dotnet-sqlclient-ci-core.yml`; it lives under `eng/pipelines/stress/` as a separate pipeline flow.
+
 When adding a new build stage, respect the dependency graph and pass artifact names/versions to downstream stages.
 
 ## PR vs CI Pipeline Differences
@@ -70,12 +73,12 @@ PR pipelines:
 - Trigger on PRs to `dev/*`, `feat/*`, `main`; exclude `eng/pipelines/onebranch/*` paths
 - Use reduced TFM matrix: `[net462, net8.0, net9.0]` (excludes net10.0)
 - Timeout: 90 minutes
-- Package-ref PR disables Always Encrypted tests in Debug config
+- Package-ref PR disables Always Encrypted tests in Debug config and also disables legacy SQL Server test legs to keep validation fast
 
 CI pipelines:
 - Trigger on push to `main` (GitHub) and `internal/main` (ADO) with `batch: true`
 - Scheduled weekday builds (see individual pipeline files for cron times)
-- Full TFM matrix including net10.0
+- Full TFM matrix including net10.0 test legs and legacy SQL Server manual-test coverage
 
 ## Test Configuration
 
@@ -97,7 +100,7 @@ Flaky test quarantine:
 
 SNI testing — `useManagedSNI` controls testing with native SNI (`false`) or managed SNI (`true`)
 
-Test timeout — `--blame-hang-timeout 10m` (configured in `build.proj`); tests exceeding 10 minutes are killed
+Test timeout — `--blame-hang-timeout 10m` (configured in `build.proj` and threaded through CI test steps); tests exceeding 10 minutes are killed
 
 ## Variables
 

.github/instructions/architecture.instructions.md

@@ -34,10 +34,11 @@ src/
 ## Unified Project Model
 
 ### Architecture Goal
-The driver is transitioning away from separate `netfx/` and `netcore/` project files toward a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj`. This project multi-targets all supported frameworks from one codebase:
+The driver is transitioning away from separate `netfx/` and `netcore/` project files toward a **single unified project** at `src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj`. This project targets the modern .NET TFMs on every host and conditionally adds .NET Framework on Windows:
 
 ```xml
-<TargetFrameworks>net462;net8.0;net9.0</TargetFrameworks>
+<TargetFrameworks>net8.0;net9.0</TargetFrameworks>
+<TargetFrameworks Condition="'$(NormalizedTargetOs)' == 'windows_nt'">$(TargetFrameworks);net462</TargetFrameworks>
 ```
 
 **All new code MUST go into `src/Microsoft.Data.SqlClient/src/`**. Do NOT add files to the legacy `netcore/src/` or `netfx/src/` directories.
@@ -82,7 +83,7 @@ When writing code that differs by platform, use these preprocessor directives:
 | `#if _UNIX` | Code for Unix/Linux/macOS OS (any framework) |
 
 Guidelines:
-1. All code must compile for all target frameworks (`net462`, `net8.0`, `net9.0`)
+1. All code must compile for the TFMs supported by the current target OS: `net8.0`/`net9.0` everywhere, plus `net462` on Windows builds
 2. Use `#if NETFRAMEWORK` or `#if NET` for framework-specific code paths
 3. Use `#if _WINDOWS` or `#if _UNIX` for OS-specific code paths
 4. Avoid APIs that don't exist on a target platform without conditional compilation
@@ -104,11 +105,15 @@ The `ref/` directories define the public API surface:
 **IMPORTANT**: Any public API changes MUST update the corresponding reference assembly in the appropriate `ref/` directory.
 
 ### Build Output
-Build artifacts are organized by framework and OS:
+Build artifacts are organized by reference mode, configuration, OS, and framework:
 ```
-artifacts/Microsoft.Data.SqlClient/{Configuration}/{TargetOs}/{TargetFramework}/
+artifacts/Microsoft.Data.SqlClient/{ReferenceType}-{Configuration}/{NormalizedTargetOs}/{TargetFramework}/
 ```
 
+`ReferenceType` is a first-class build dimension in this branch. Local and CI builds may run in:
+- `Project` mode — sibling packages referenced as projects
+- `Package` mode — sibling packages restored from locally produced NuGet packages
+
 ## SNI (SQL Server Network Interface) Layer
 
 Two implementations exist:

.github/instructions/onebranch-pipeline-design.instructions.md

@@ -34,7 +34,9 @@ Defined in `stages/build-stages.yml`. Four build stages plus validation, ordered
 - **`build_abstractions`** (Stage 2) — Abstractions; `dependsOn: build_independent`; downloads Logging artifact
 - **`build_dependent`** (Stage 3) — SqlClient and Extensions.Azure in parallel; `dependsOn: build_abstractions`; downloads Abstractions + Logging artifacts
 - **`build_addons`** (Stage 4) — AKV Provider; `dependsOn: build_dependent`; downloads SqlClient + Abstractions + Logging artifacts
-- **`mds_package_validation`** — Validates signed SqlClient package; `dependsOn: build_dependent`; runs in parallel with Stage 4
+- **`sqlclient_package_validation`** — Validates signed SqlClient package; `dependsOn: build_dependent`; runs in parallel with Stage 4
+
+Each build job copies PDB files into `$(JOB_OUTPUT)/symbols/` so they are included in the auto-published pipeline artifact alongside the NuGet packages in `$(JOB_OUTPUT)/packages/`.
 
 Stage conditional rules:
 - Wrap stages/jobs in `${{ if }}` compile-time conditionals based on build parameters
@@ -45,16 +47,30 @@ Stage conditional rules:
 
 ## Job Templates
 
-- **`build-signed-csproj-package-job.yml`** — Generic job for csproj-based packages (Logging, SqlServer.Server, Abstractions, Azure, AKV Provider). Flow: Build DLLs → ESRP DLL signing → NuGet pack (`NoBuild=true`) → ESRP NuGet signing
-- **`build-signed-sqlclient-package-job.yml`** — SqlClient-specific job (nuspec-based). Flow: Build all configurations → ESRP DLL signing (main + resource DLLs) → NuGet pack via nuspec → ESRP NuGet signing
+- **`build-buildproj-job.yml`** — Shared build.proj-driven package job used for all shipped packages. Flow: build via `build.proj` → optional ESRP DLL signing → pack via `build.proj` → optional ESRP NuGet signing → copy outputs for APIScan/artifacts
 - **`validate-signed-package-job.yml`** — Validates signed MDS package (signature, strong names, folder structure, target frameworks)
 - **`publish-nuget-package-job.yml`** — Reusable release job using OneBranch `templateContext.type: releaseJob` with `inputs` for artifact download; pushes via `NuGetCommand@2`
+- **`publish-symbols-job.yml`** — Reusable symbols job: downloads a build artifact, locates PDBs under `symbols/`, and invokes `publish-symbols-step.yml`
 
-When adding a new csproj-based package:
-- Use `build-signed-csproj-package-job.yml` with appropriate `packageName`, `packageFullName`, `versionProperties`, and `downloadArtifacts`
-- Add build and pack targets to `build.proj`
+When adding a new package to the OneBranch flow:
+- Extend `build-buildproj-job.yml` inputs with the new package metadata and dependency artifacts
+- Add or update the corresponding build/pack targets in `build.proj`
 - Add version variables to `variables/common-variables.yml`
-- Add artifact name variable to `variables/onebranch-variables.yml`
+- Add artifact name variables to `variables/onebranch-variables.yml`
+
+## Symbols Publishing Stage
+
+- Defined in `stages/publish-symbols-stage.yml`; produces stage `publish_symbols`
+- Entire stage excluded at compile time when `publishSymbols` is false
+- `dependsOn` is conditional based on which `build*` parameters are set, mirroring the build stage dependency graph
+- One job per package (`publish-symbols-job.yml`), each downloading its build artifact and publishing PDBs from `symbols/`
+- Each package's PDBs are published separately with unique artifact names and version information
+- Build jobs copy PDBs into `$(JOB_OUTPUT)/symbols/` so they are included in the auto-published artifact
+- The `publish-symbols-step.yml` accepts a `symbolsFolder` parameter to point at the downloaded PDB location
+- The publish step calls an extracted `publish-symbols.ps1` script with structured error handling and diagnostic logging
+- Symbols publishing credentials come from the `Symbols Publishing` variable group
+- In the official pipeline, symbol server destination follows `releaseToProduction`: Production when true, PPE when false
+- Non-official pipeline always targets the PPE symbol server
 
 ## Release Stage
 
@@ -84,7 +100,9 @@ Release parameters (all boolean, default `false`):
 - `releaseSqlServerServer`, `releaseLogging`, `releaseAbstractions`, `releaseSqlClient`, `releaseAzure`, `releaseAKVProvider`
 
 Official-only parameter:
-- `releaseToProduction` — push to NuGet Production feed (default `false`)
+- `releaseToProduction` — controls both NuGet target feed and symbol server destination (default `false`):
+  - `true` → NuGet Production feed + Production symbol server
+  - `false` → NuGet Test feed + PPE symbol server
 
 When `isPreview` is true, pipeline resolves `effective*Version` variables to preview versions; otherwise GA versions. All versions defined in `variables/common-variables.yml`.
 
@@ -98,32 +116,34 @@ When `isPreview` is true, pipeline resolves `effective*Version` variables to pre
 - When adding a new package, add GA version, preview version, and assembly file version entries
 
 Variable groups:
-- `Release Variables` — release configuration (in `common-variables.yml`)
-- `Symbols publishing` — symbol publishing credentials (in `common-variables.yml`)
+- `Symbols Publishing` — symbol publishing credentials (in `onebranch-variables.yml`)
 - `ESRP Federated Creds (AME)` — ESRP signing credentials (in `common-variables.yml`)
 
 ## Code Signing (ESRP)
 
 - Uses ESRP v6 tasks (`EsrpMalwareScanning@6`, `EsrpCodeSigning@6`) with MSI/federated identity authentication
 - Signing only runs when `isOfficial: true` — non-official pipelines skip ESRP steps
-- csproj-based packages: sign DLLs first → pack with `NoBuild=true` → sign NuGet package (ensures NuGet contains signed DLLs)
-- SqlClient: sign DLLs (including resource DLLs) → nuspec pack → sign NuGet package
+- The shared OneBranch job signs DLLs before packing and signs the resulting NuGet package afterward so the published package contains signed binaries
 - DLL signing uses keyCode `CP-230012` (Authenticode); NuGet signing uses keyCode `CP-401405`
 - All ESRP credentials come from variable groups — never hardcode secrets in YAML
 
 ## SDL and Compliance
 
 - TSA: enabled only in official pipeline; disabled in non-official to avoid spurious alerts
 - ApiScan: enabled in both; currently `break: false` pending package registration
-- Each build job sets `ob_sdl_apiscan_*` variables pointing to `$(Build.SourcesDirectory)/apiScan/<PackageName>/`
+- Each build job sets `ob_sdl_apiscan_softwareFolder` to `$(JOB_OUTPUT)/assemblies` and `ob_sdl_apiscan_symbolsFolder` to `$(JOB_OUTPUT)/symbols`
 - CodeQL, SBOM, Policheck (`break: true`): enabled in both pipelines
 - asyncSdl `enabled: false` in both; individual sub-tools (CredScan, BinSkim, Armory, Roslyn) configured underneath
 - Policheck exclusions: `$(REPO_ROOT)\.config\PolicheckExclusions.xml`
 - CredScan suppressions: `$(REPO_ROOT)/.config/CredScanSuppressions.json`
 
 ## Artifact Conventions
 
-- `ob_outputDirectory` set to `$(PACK_OUTPUT)` (= `$(REPO_ROOT)/output`) — OneBranch auto-publishes this directory
+- `ob_outputDirectory` set to `$(JOB_OUTPUT)` (= `$(REPO_ROOT)/output`) — OneBranch auto-publishes this directory
+- Each published artifact uses subdirectories to separate file types:
+  - `assemblies/` — DLL assemblies for APIScan (preserving TFM folder structure)
+  - `packages/` — NuGet packages (`.nupkg`, `.snupkg`)
+  - `symbols/` — PDB symbol files (preserving TFM folder structure, shared by APIScan and symbol publishing)
 - Artifact names follow `drop_<stageName>_<jobName>` — defined in `variables/onebranch-variables.yml`
 - Downstream jobs download artifacts via `DownloadPipelineArtifact@2` into `$(Build.SourcesDirectory)/packages`
 - Downloaded packages serve as a local NuGet source for `dotnet restore`