Consolidate package version specification and computation

.github/instructions/package-versions.instructions.md → .github/instructions/3rd-party-package-versions.instructions.md

@@ -1,9 +1,11 @@
 ---
 applyTo: "**/Directory.Packages.props,**/*.csproj,**/Directory.Build.props,**/*.nuspec"
 ---
-# Choosing Package Versions in Multi-Targeted Projects
+# Choosing Third-Party Package Dependency Versions
 
-Guidance for choosing NuGet package versions in multi-targeted projects (e.g. `net462;net8.0;net9.0`).
+Guidance for choosing versions of **external (third-party) NuGet package dependencies** in multi-targeted projects (e.g. `net462;net8.0;net9.0`).
+
+> **Scope:** This document covers dependencies consumed from NuGet — packages the SqlClient repo does NOT own. For versioning of SqlClient's own inter-sibling packages (Logging, Abstractions, SqlClient, Azure, AKV Provider, SqlServer.Server), see `sqlclient-package-versions.instructions.md`.
 
 ## Rule
 For runtime-aligned packages, **the package major must match the target runtime major**: 8.x on `net8.0`, 9.x on `net9.0`, 10.x on `net10.0`, and so on. TFMs that aren't tied to a specific runtime major (`net462`, `netstandard2.0`) get the major of the floor LTS. Other categories are versioned as described below.

.github/instructions/sqlclient-package-versions.instructions.md

@@ -0,0 +1,123 @@
+---
+applyTo: "**/Versions.props,build.proj,eng/pipelines/**/*.yml"
+---
+# SqlClient Package Version Resolution
+
+How package versions are determined across different build scenarios for the packages in this repository.
+
+## Version Properties (per package)
+
+Each package has a `Versions.props` file declaring:
+
+| Property | Purpose | Example |
+|----------|---------|---------|
+| `*NextVersion` | Version being developed; used for the next release | `7.1.0-preview1` |
+| `*PublishedVersion` | Last version shipped to NuGet | `7.0.0` |
+
+## Resolution Logic
+
+Each `Versions.props` uses a 3-tier `<Choose>` block:
+
+| Priority | Condition | PackageVersion | FileVersion |
+|----------|-----------|----------------|-------------|
+| 1 | `PackageVersion<Pkg>` explicitly provided | Used as-is | Strip prerelease + append BuildNumber |
+| 2 | `BuildNumber` provided (non-zero) | `NextVersion[-BuildSuffix+BuildNumber]` | `NextVersion.Split('-')[0].BuildNumber` |
+| 3 | Nothing provided | `NextVersion-dev` | `NextVersion.Split('-')[0].0` |
+
+## Scenarios
+
+### Developer (local `dotnet build`)
+
+**Mode:** Project (default `ReferenceType=Project`)
+
+- No `BuildNumber`, no `BuildSuffix`, no `PackageVersion*` passed.
+- Falls into Priority 3 (the `<Otherwise>` branch).
+- **Result:** `7.1.0-preview1-dev` / FileVersion `7.1.0.0`
+- Dependencies are project references — no package versions needed for siblings.
+
+**Mode:** Package (`-p:ReferenceType=Package`)
+
+- Same version resolution for the package being built.
+- Sibling dependencies are restored from local `packages/` feed (previously packed with `-dev` suffix).
+- A developer would first `dotnet build build.proj -t:Pack` to produce local packages, then consume them.
+
+### PR Pipeline (non-official CI)
+
+**`buildSuffix`** set via core template parameter:
+- `buildSuffix: 'pr'` (passed explicitly from PR pipeline)
+- `BuildNumber` = `$(DayOfYear)$(Rev:rr)` (e.g. `15401` for day-of-year 154, run 01)
+
+**Mode:** Project (typical PR validation)
+
+- Versions computed in `compute-versions-ci-stage.yml` (runs `GetVersions*` targets with `-p:BuildSuffix=pr -p:BuildNumber=...`)
+- Falls into Priority 2 with BuildSuffix present.
+- **Result:** `7.1.0-preview1-pr15401` / FileVersion `7.1.0.15401`
+- Dependencies are project references — all packages built together in-tree.
+
+**Mode:** Package (PR package-ref validation)
+
+- Same version computation via compute-versions stage.
+- Downstream stages define stage-level variables from compute-versions output using `$[ stageDependencies... ]`.
+- Each build step receives explicit `-p:PackageVersion<Pkg>=<value>` (hits Priority 1).
+- Sibling dependencies consumed from pipeline artifacts published by upstream stages.
+
+### CI Pipeline (non-official, triggered on merge)
+
+Same structure as PR but passes `buildSuffix: 'ci'` explicitly.
+
+- **Result:** `7.1.0-preview1-ci15401` / FileVersion `7.1.0.15401`
+
+### OneBranch Pipeline (official)
+
+**Mode:** Always Package (`ReferenceType=Package`)
+
+Uses the full `compute-versions-stage.yml` machinery:
+
+#### Step A: Compute Versions (dedicated early stage)
+
+1. Runs 6 `GetVersions*` MSBuild targets against `build.proj`.
+2. Each target calls `dotnet build <project> -getProperty:<Pkg>PackageVersion` with `BuildNumber` but **no BuildSuffix**.
+3. Falls into Priority 2 without BuildSuffix → `PackageVersion = NextVersion` as-is (e.g. `7.1.0-preview1`).
+4. Also extracts `PublishedVersion` (hardcoded in Versions.props, e.g. `7.0.0`).
+
+#### Step B: Resolve Effective Versions
+
+For each package, a `release<Pkg>` boolean parameter determines the outcome:
+
+| `release<Pkg>` | Effective Version | Meaning |
+|----------------|-------------------|---------|
+| `True` | `NextVersion` (e.g. `7.1.0-preview1`) | This package is being released |
+| `False` | `PublishedVersion` (e.g. `7.0.0`) | Only built as dependency; use last-shipped version |
+
+These are published as ADO output variables (e.g. `versions.SqlClientPackageVersion`).
+
+#### Step C: Build Stages Consume Pre-computed Versions
+
+Each downstream build job receives:
+- `packageVersion` parameter → passed as `-p:PackageVersion<Pkg>=<value>`
+- Dependency versions → passed as `-p:PackageVersion<Dep>=<value>`
+
+Since an explicit `PackageVersion<Pkg>` is provided, Versions.props hits Priority 1 — uses the value verbatim.
+
+#### Summary
+
+| Package Status | Version Source | Example |
+|----------------|----------------|---------|
+| Being released | `*NextVersion` from Versions.props | `7.1.0-preview1` |
+| Dependency only | `*PublishedVersion` from Versions.props | `7.0.0` |
+
+## Key Architectural Difference
+
+| Scenario | Who computes versions | How dependencies get versions |
+|----------|----------------------|-------------------------------|
+| Developer | Versions.props inline (Priority 3) | Project references (no version needed) |
+| PR/CI (Project) | `compute-versions-ci-stage` up-front | Project references (no version needed) |
+| PR/CI (Package) | `compute-versions-ci-stage` up-front | Stage variables via `$[ stageDependencies... ]` → `-p:PackageVersion<Dep>=` |
+| OneBranch | `compute-versions-stage` up-front | Explicit `-p:PackageVersion<Dep>=` from stage outputs |
+
+## Updating Versions
+
+After a release:
+1. Update `*PublishedVersion` to the version just shipped.
+2. Update `*NextVersion` to the next planned version.
+3. Both properties live in each package's `Versions.props`.

build.proj

@@ -388,6 +388,161 @@
   -->
   <Target Name="Pack" DependsOnTargets="PackLogging;PackAbstractions;PackSqlClient;PackAzure;PackAkvProvider;PackSqlServer" />
 
+  <!-- ================================================================= -->
+  <!-- Version Extraction Targets
+       One target per project that emits 3 labeled messages at High importance:
+         PackageVersion: <value>
+         PublishedVersion: <value>
+         FileVersion: <value>
+
+       Pipelines capture these by grepping stdout with sed.
+
+       Usage:
+         dotnet build build.proj -t:GetVersionsLogging -v:m -nologo -p:BuildNumber=1234
+         # stdout contains:
+         #   PackageVersion: 1.1.0-preview1
+         #   PublishedVersion: 1.0.0
+         #   FileVersion: 1.1.0.1234
+  -->
+
+  <Target Name="GetVersionsLogging">
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(LoggingProjectPath)" -getProperty:LoggingPackageVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PackageVersion" />
+    </Exec>
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; build &quot;$(LoggingProjectPath)&quot; -getProperty:LoggingPublishedVersion" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PublishedVersion" />
+    </Exec>
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(LoggingProjectPath)" -getProperty:LoggingFileVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_FileVersion" />
+    </Exec>
+    <Message Text="PackageVersion: $(_PackageVersion)" Importance="High" />
+    <Message Text="PublishedVersion: $(_PublishedVersion)" Importance="High" />
+    <Message Text="FileVersion: $(_FileVersion)" Importance="High" />
+  </Target>
+
+  <Target Name="GetVersionsAbstractions">
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(AbstractionsProjectPath)" -getProperty:AbstractionsPackageVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PackageVersion" />
+    </Exec>
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; build &quot;$(AbstractionsProjectPath)&quot; -getProperty:AbstractionsPublishedVersion" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PublishedVersion" />
+    </Exec>
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(AbstractionsProjectPath)" -getProperty:AbstractionsFileVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_FileVersion" />
+    </Exec>
+    <Message Text="PackageVersion: $(_PackageVersion)" Importance="High" />
+    <Message Text="PublishedVersion: $(_PublishedVersion)" Importance="High" />
+    <Message Text="FileVersion: $(_FileVersion)" Importance="High" />
+  </Target>
+
+  <Target Name="GetVersionsSqlClient">
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(SqlClientProjectPath)" -getProperty:SqlClientPackageVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PackageVersion" />
+    </Exec>
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; build &quot;$(SqlClientProjectPath)&quot; -getProperty:SqlClientPublishedVersion" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PublishedVersion" />
+    </Exec>
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(SqlClientProjectPath)" -getProperty:SqlClientFileVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_FileVersion" />
+    </Exec>
+    <Message Text="PackageVersion: $(_PackageVersion)" Importance="High" />
+    <Message Text="PublishedVersion: $(_PublishedVersion)" Importance="High" />
+    <Message Text="FileVersion: $(_FileVersion)" Importance="High" />
+  </Target>
+
+  <Target Name="GetVersionsAzure">
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(AzureProjectPath)" -getProperty:AzurePackageVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PackageVersion" />
+    </Exec>
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; build &quot;$(AzureProjectPath)&quot; -getProperty:AzurePublishedVersion" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PublishedVersion" />
+    </Exec>
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(AzureProjectPath)" -getProperty:AzureFileVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_FileVersion" />
+    </Exec>
+    <Message Text="PackageVersion: $(_PackageVersion)" Importance="High" />
+    <Message Text="PublishedVersion: $(_PublishedVersion)" Importance="High" />
+    <Message Text="FileVersion: $(_FileVersion)" Importance="High" />
+  </Target>
+
+  <Target Name="GetVersionsAkvProvider">
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(AkvProviderProjectPath)" -getProperty:AkvProviderPackageVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PackageVersion" />
+    </Exec>
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; build &quot;$(AkvProviderProjectPath)&quot; -getProperty:AkvProviderPublishedVersion" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PublishedVersion" />
+    </Exec>
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(AkvProviderProjectPath)" -getProperty:AkvProviderFileVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_FileVersion" />
+    </Exec>
+    <Message Text="PackageVersion: $(_PackageVersion)" Importance="High" />
+    <Message Text="PublishedVersion: $(_PublishedVersion)" Importance="High" />
+    <Message Text="FileVersion: $(_FileVersion)" Importance="High" />
+  </Target>
+
+  <Target Name="GetVersionsSqlServer">
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(SqlServerProjectPath)" -getProperty:SqlServerPackageVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PackageVersion" />
+    </Exec>
+    <Exec Command="&quot;$(DotnetPath)dotnet&quot; build &quot;$(SqlServerProjectPath)&quot; -getProperty:SqlServerPublishedVersion" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_PublishedVersion" />
+    </Exec>
+    <PropertyGroup>
+      <_Cmd>"$(DotnetPath)dotnet" build "$(SqlServerProjectPath)" -getProperty:SqlServerFileVersion $(BuildNumberArgument) $(BuildSuffixArgument)</_Cmd>
+      <_Cmd>$([System.Text.RegularExpressions.Regex]::Replace($(_Cmd), "\s+", " "))</_Cmd>
+    </PropertyGroup>
+    <Exec Command="$(_Cmd)" ConsoleToMsBuild="true" StandardOutputImportance="High">
+      <Output TaskParameter="ConsoleOutput" PropertyName="_FileVersion" />
+    </Exec>
+    <Message Text="PackageVersion: $(_PackageVersion)" Importance="High" />
+    <Message Text="PublishedVersion: $(_PublishedVersion)" Importance="High" />
+    <Message Text="FileVersion: $(_FileVersion)" Importance="High" />
+  </Target>
+
   <!--
     Test: Run all test targets for all packages.
     Note: This will run for a *very* long time and it is not recommended, even in automated test
@@ -532,7 +687,7 @@
     </PropertyGroup>
 
     <Message Text=">>> Building SqlClient for Unix via command: $(DotnetCommand)"/>
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- BuildSqlClientWindows: Builds all windows-specific SqlClient binaries -->
@@ -654,7 +809,7 @@
       <DotnetCommand>$([System.Text.RegularExpressions.Regex]::Replace($(DotnetCommand), "\s+", " "))</DotnetCommand>
     </PropertyGroup>
     <Message Text=">>> Running functional tests for SqlClient via command: $(DotnetCommand)" />
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- TestSqlClientManual: Runs manual tests for SqlClient -->
@@ -686,7 +841,7 @@
       <DotnetCommand>$([System.Text.RegularExpressions.Regex]::Replace($(DotnetCommand), "\s+", " "))</DotnetCommand>
     </PropertyGroup>
     <Message Text=">>> Running manual tests for SqlClient via command: $(DotnetCommand)" />
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- TestSqlClientUnit: Runs unit tests for SqlClient -->
@@ -714,7 +869,7 @@
       <DotnetCommand>$([System.Text.RegularExpressions.Regex]::Replace($(DotnetCommand), "\s+", " "))</DotnetCommand>
     </PropertyGroup>
     <Message Text=">>> Running unit tests for SqlClient via command: $(DotnetCommand)" />
     <Exec ConsoleToMsBuild="true" Command="$(DotnetCommand)" />
   </Target>
 
   <!-- ================================================================= -->

eng/pipelines/dotnet-sqlclient-ci-core.yml

@@ -94,6 +94,11 @@ parameters:
     type: boolean
     default: true
 
+  # Build suffix appended to the prerelease tag. PR pipelines pass 'pr',
+  # CI pipelines pass 'ci'. Official builds leave this empty.
+  - name: buildSuffix
+    type: string
+
   - name: dotnetVerbosity
     type: string
     default: normal
@@ -123,6 +128,12 @@ variables:
     value: SqlServer.Artifacts
 
 stages:
+  # Compute all package versions up-front. Downstream stages consume these via
+  # stage dependency output variables (e.g. $(loggingPackageVersion)).
+  - template: /eng/pipelines/stages/compute-versions-ci-stage.yml@self
+    parameters:
+      buildSuffix: ${{ parameters.buildSuffix }}
+
   # Generate secrets used throughout the pipeline.
   - template: /eng/pipelines/stages/generate-secrets-ci-stage.yml@self
     parameters:

eng/pipelines/dotnet-sqlclient-ci-package-reference-pipeline.yml

@@ -41,6 +41,9 @@
 #   https://sqlclientdrivers.visualstudio.com/ADO.Net/_build?definitionId=1933
 
 # Set the pipeline run name to the day-of-year and the daily run counter.
+# This becomes BuildNumber, used as the revision component of AssemblyFileVersion
+# (Major.Minor.Patch.Revision). Revision must fit in a 16-bit unsigned int (max 65535).
+# Format $(DayOfYear)$(Rev:rr) yields e.g. 15401 (day 154, run 01) — always < 65535.
 name: $(DayOfYear)$(Rev:rr)
 
 # Do not trigger this pipeline for PRs.
@@ -166,6 +169,7 @@ extends:
   parameters:
     buildConfiguration: ${{ parameters.buildConfiguration }}
     buildPlatforms: ${{ parameters.buildPlatforms }}
+    buildSuffix: 'ci'
     referenceType: Package
     debug: ${{ parameters.debug }}
     dotnetVerbosity: ${{ parameters.dotnetVerbosity }}

eng/pipelines/dotnet-sqlclient-ci-project-reference-pipeline.yml

@@ -41,6 +41,9 @@
 #   https://sqlclientdrivers.visualstudio.com/ADO.Net/_build?definitionId=1825
 
 # Set the pipeline run name to the day-of-year and the daily run counter.
+# This becomes BuildNumber, used as the revision component of AssemblyFileVersion
+# (Major.Minor.Patch.Revision). Revision must fit in a 16-bit unsigned int (max 65535).
+# Format $(DayOfYear)$(Rev:rr) yields e.g. 15401 (day 154, run 01) — always < 65535.
 name: $(DayOfYear)$(Rev:rr)
 
 # Do not trigger this pipeline for PRs.
@@ -166,6 +169,7 @@ extends:
   parameters:
     buildConfiguration: ${{ parameters.buildConfiguration }}
     buildPlatforms: ${{ parameters.buildPlatforms }}
+    buildSuffix: 'ci'
     referenceType: Project
     debug: ${{ parameters.debug }}
     dotnetVerbosity: ${{ parameters.dotnetVerbosity }}