Align pack docs with dotnet build and harden SqlClient nuspec prep

paulmedynski · paulmedynski · commit 6da35be91a53 · 2026-05-04T14:30:48.000-03:00
diff --git a/BUILDGUIDE.md b/BUILDGUIDE.md
@@ -20,9 +20,8 @@ on operating systems that do not support .NET Framework. As such, it is not nece
 no action is required. On Linux and MacOS systems, the `pwsh` command is required to be in the `$PATH` environment
 variable. For specific instructions see: [Install PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell)
 
-The **NuGet** binary is required to package the Microsoft.Data.SqlClient project. For convenience, this can be be done
-via the PowerShell script [tools/scripts/downloadLatestNuget.ps1](tools/scripts/downloadLatestNuget.ps1), however, any
-`nuget.exe` binary can be used.
+The **NuGet** binary is optional for inspection and feed-management workflows, but build and packaging flows in this
+repository are run through `dotnet build` against `build.proj`.
 
 ## Developer Workflow
 
@@ -35,20 +34,18 @@ package the project. The `build.proj` file provides convenient targets to accomp
 > is recommended that `build.proj` is used for local development, as well.
 
 > [!TIP]
-> `build.proj` was written with the intention of being called from `msbuild`. As such, the following examples below
-> use `msbuild`. On systems where `msbuild` is not available, simply replace `msbuild` with `dotnet msbuild` to get the
-> same behavior.
+> Use `dotnet build` with `build.proj` for local and CI workflows in this repository.
 
 > [!TIP]
 > This section is not exhaustive of all targets or parameters to `build.proj`. Complete documentation is avilable in
 > [`build.proj`](build.proj).
 
 ### Building Projects
 
-From the root of your repository, run `msbuild` against `build.proj` with a build target, following this pattern:
+From the root of your repository, run `dotnet build` against `build.proj` with a build target, following this pattern:
 
 ```bash
-msbuild build.proj -t:<build_target> [optional_parameters]
+dotnet build build.proj -t:<build_target> [optional_parameters]
 ```
 
 The following build targets can be used to build the following projects. All targets will implicitly build any other
@@ -87,28 +84,28 @@ placed in `artifacts/Microsoft.Data.SqlClient.ref/Project-<configuration>/<tfm>`
 
 Build all projects:
 ```bash
-msbuild build.proj -t:Build
+dotnet build build.proj -t:Build
 ```
 
 Build Microsoft.Data.SqlClient in Release configuration:
 ```bash
-msbuild build.proj -t:BuildSqlClient -p:Configuration=Release
+dotnet build build.proj -t:BuildSqlClient -p:Configuration=Release
 ```
 
 Build v1.2.3 of Microsoft.Data.SqlClient.Extensions.Abstractions:
 ```bash
-msbuild build.proj -t:BuildAbstractions -p:PackageVersion=1.2.3
+dotnet build build.proj -t:BuildAbstractions -p:PackageVersion=1.2.3
 ```
 
 ### Testing Projects
 
 This section provides a summary and brief example of how to execute tests for projects in this repository. **For more
 information about test procedures, including config file setup, see [TESTGUIDE.md](TESTGUIDE.md).**
 
-From the root of your repository, run `msbuild` against `build.proj` with a test target, following this pattern:
+From the root of your repository, run `dotnet build` against `build.proj` with a test target, following this pattern:
 
 ```bash
-msbuild build.proj -t:<test_target> [optional_parameters]
+dotnet build build.proj -t:<test_target> [optional_parameters]
 ```
 
 | `<test_target>`            | Description                                                                                                                                         |
@@ -140,37 +137,37 @@ A selection of parameters for test targets in `build.proj` relevant to common de
 Run Microsoft.Data.SqlClient unit tests:
 
 ```bash
-msbuild build.proj -t:TestSqlClientUnit
+dotnet build build.proj -t:TestSqlClientUnit
 ```
 
 Run Microsoft.Data.SqlClient manual test set 2:
 ```bash
-msbuild build.proj -t:TestSqlClientManual -p:TestSet=2
+dotnet build build.proj -t:TestSqlClientManual -p:TestSet=2
 ```
 
 Run Microsoft.Data.SqlClient functional tests against x86 dotnet:
 ```bash
-msbuild build.proj -t:TestSqlClientFunctional -p:DotnetPath='C:\path\to\dotnet\x86\'
+dotnet build build.proj -t:TestSqlClientFunctional -p:DotnetPath='C:\path\to\dotnet\x86\'
 ```
 
 Run all Microsoft.Data.SqlClient.Extensions.Azure unit tests, including interactive, but excluding failing tests:
 ```bash
-msbuild build.proj -t:TestAzure -p:TestFilters=category!=failing
+dotnet build build.proj -t:TestAzure -p:TestFilters=category!=failing
 ```
 
 Run Microsoft.Data.SqlClient functional tests against net8.0 runtime:
 ```bash
-msbuild build.proj -t:TestSqlClientFunctional -p:TestFramework=net8.0
+dotnet build build.proj -t:TestSqlClientFunctional -p:TestFramework=net8.0
 ```
 
 ### Packaging Projects
 
 Just like bulding and testing the various projects in this repository, packaging the projects into NuGet packages is
-also handle by `build.proj`. From the root of your repository, run `msbuild` against `build.proj` with a test target,
+also handle by `build.proj`. From the root of your repository, run `dotnet build` against `build.proj` with a pack target,
 following this pattern:
 
 ```bash
-msbuild build.proj -t:<pack_target> [optional_parameters]
+dotnet build build.proj -t:<pack_target> [optional_parameters]
 ```
 
 | `<build_target>`   | Desription                                                                          |
@@ -191,30 +188,34 @@ A selection of parameters for pack targets in `build.proj` relevant to common de
 | `[optional_parameter]`             | Default Value | Allowed Values        | Description                                                                                                                                                    |
 |------------------------------------|---------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `-p:Configuration=`                | `Debug`       | `Debug`, `Release`    | Build configuration. Only applies if project and dependencies are being built.                                                                                 |
-| `-p:NugetPath=`                    | `[blank]`     | eg. `C:\my\nuget.exe` | _Only applies to `PackSqlClient`._ Path to `nuget.exe` that to use. If not provided, defaults to `nuget.exe` in the PATH.                                      |
 | `-p:PackBuild=`                    | `true`        | `true`, `false`       | Whether or not to build the project before packing. If `false`, project must be built using the same parameters.                                               |
 | `-p:PackageVersion<TargetProject>` | `[blank]`     | eg. `1.2.3-dev123`    | Version to assign to the package. If `PackBuild` is `true`, the assembly and file versions will be derived from this version. See Versioning for more details. |
 
+For `PackSqlClient`, these additional parameters are required because dependency versions are injected into the SqlClient nuspec during pack:
+
+- `-p:PackageVersionAbstractions=<version>`
+- `-p:PackageVersionLogging=<version>`
+
 #### Examples
 
 Package Microsoft.Data.SqlClient.Internal.Logging into a NuGet package:
 ```bash
-msbuild build.proj -t:PackLogging
+dotnet build build.proj -t:PackLogging
 ```
 
-Package Microsoft.Data.SqlClient if `nuget.exe` is not in the `$PATH` environment variable:
+Package Microsoft.Data.SqlClient:
 ```bash
-msbuild build.proj -t:PackSqlClient -p:NugetPath="C:\my\nuget.exe"
+dotnet build build.proj -t:PackSqlClient -p:PackageVersionAbstractions=<version> -p:PackageVersionLogging=<version>
 ```
 
 Package version 1.2.3 of Microsoft.Data.SqlClient.Extensions.Abstractions:
 ```bash
-msbuild build.proj -t:PackAbstractions -p:PackageVersionAbstractions=1.2.3
+dotnet build build.proj -t:PackAbstractions -p:PackageVersionAbstractions=1.2.3
 ```
 
 Package version Microsoft.Data.SqlClient.Extensions.Azure without building it beforehand:
 ```bash
-msbuild build.proj -t:PackAzure -p:PackBuild=false
+dotnet build build.proj -t:PackAzure -p:PackBuild=false
 ```
 
 ## Versioning
@@ -276,20 +277,20 @@ and Microsoft.Data.SqlClient.Internal.Logging v2.2.2.
 
 ```bash
 # Build v2.2.2 of Logging and copy to packages
-msbuild build.proj -t:PackLogging \
+dotnet build build.proj -t:PackLogging \
   -p:ReferenceType=Package \
   -p:PackageVersionLogging=2.2.2
 cp artifacts/Microsoft.Data.SqlClient.Internal.Logging/Debug/*.*pkg packages/
 
 # Build v1.0.1 of Abstractions that depends on v2.2.2 of Logging
-msbuild build.proj -t:PackAbstractions \
+dotnet build build.proj -t:PackAbstractions \
   -p:ReferenceType=Package \
   -p:PackageVersionAbstractions=1.0.1 \
   -p:PackageVersionLogging=2.2.2 \
 cp artifacts/Microsoft.Data.SqlClient.Extensions.Abstractions/Package-Debug/*.*pkg packages/
 
 # Build SqlClient
-msbuild -t:PackSqlClient \
+dotnet build build.proj -t:PackSqlClient \
   -p:ReferenceType=Package \
   -p:PackageVersionSqlClient=7.1.1 \
   -p:PackageVersionAbstractions=1.0.1 \
@@ -299,7 +300,7 @@ cp artifacts/Microsoft.Data.SqlClient/Package-Debug/*.*pkg packages/
 
 Run Microsoft.Data.SqlClient functional tests against the versions build above:
 ```bash
-msbuild build.proj -t:TestSqlClientFunctional \
+dotnet build build.proj -t:TestSqlClientFunctional \
   -p:ReferenceType=Package \
   -p:PackageVersionSqlClient=7.1.1 \
   -p:PackageVersionAbstractions=1.0.1 \
diff --git a/TESTGUIDE.md b/TESTGUIDE.md
@@ -23,13 +23,7 @@ These projects target `net8.0`, `net9.0`, and `net10.0` on all platforms. On Win
 Use [build.proj](build.proj) from the repository root:
 
 ```bash
-msbuild build.proj -t:<test_target> [optional_parameters]
-```
-
-If `msbuild` is not available, use `dotnet msbuild`:
-
-```bash
-dotnet msbuild build.proj -t:<test_target> [optional_parameters]
+dotnet build build.proj -t:<test_target> [optional_parameters]
 ```
 
 Test targets build the projects they depend on, so a separate build step is not required for normal test runs.
@@ -51,55 +45,55 @@ Test targets build the projects they depend on, so a separate build step is not
 Run the SqlClient unit tests:
 
 ```bash
-msbuild build.proj -t:TestSqlClientUnit
+dotnet build build.proj -t:TestSqlClientUnit
 ```
 
 Run the SqlClient functional tests:
 
 ```bash
-msbuild build.proj -t:TestSqlClientFunctional
+dotnet build build.proj -t:TestSqlClientFunctional
 ```
 
 Run the SqlClient manual tests:
 
 ```bash
-msbuild build.proj -t:TestSqlClientManual
+dotnet build build.proj -t:TestSqlClientManual
 ```
 
 Run only manual test set 2:
 
 ```bash
-msbuild build.proj -t:TestSqlClientManual -p:TestSet=2
+dotnet build build.proj -t:TestSqlClientManual -p:TestSet=2
 ```
 
 Run manual test sets 1 and 3:
 
 ```bash
-msbuild build.proj -t:TestSqlClientManual -p:TestSet=13
+dotnet build build.proj -t:TestSqlClientManual -p:TestSet=13
 ```
 
 Run Always Encrypted manual tests:
 
 ```bash
-msbuild build.proj -t:TestSqlClientManual -p:TestSet=AE
+dotnet build build.proj -t:TestSqlClientManual -p:TestSet=AE
 ```
 
 Run a specific target framework:
 
 ```bash
-msbuild build.proj -t:TestSqlClientFunctional -p:TestFramework=net8.0
+dotnet build build.proj -t:TestSqlClientFunctional -p:TestFramework=net8.0
 ```
 
 Run functional tests against an x86 `dotnet` installation:
 
 ```bash
-msbuild build.proj -t:TestSqlClientFunctional -p:DotnetPath='C:\path\to\dotnet\x86\'
+dotnet build build.proj -t:TestSqlClientFunctional -p:DotnetPath='C:\path\to\dotnet\x86\'
 ```
 
 Run all Azure extension tests, including `interactive` tests, while still excluding tests marked `failing` or `flaky`:
 
 ```bash
-msbuild build.proj -t:TestAzure -p:TestFilters=category!=failing
+dotnet build build.proj -t:TestAzure -p:TestFilters=category!=failing
 ```
 
 ## Test Parameters
@@ -132,13 +126,13 @@ Examples:
 
 ```bash
 # Run a single test by fully-qualified name.
-msbuild build.proj -t:TestSqlClientUnit -p:TestFilters=FullyQualifiedName=Namespace.ClassName.MethodName
+dotnet build build.proj -t:TestSqlClientUnit -p:TestFilters=FullyQualifiedName=Namespace.ClassName.MethodName
 
 # Run only flaky tests while investigating quarantine failures.
-msbuild build.proj -t:TestSqlClientManual -p:TestFilters=category=flaky
+dotnet build build.proj -t:TestSqlClientManual -p:TestFilters=category=flaky
 
 # Disable the default filter.
-msbuild build.proj -t:TestSqlClientFunctional -p:TestFilters=none
+dotnet build build.proj -t:TestSqlClientFunctional -p:TestFilters=none
 ```
 
 When passing filter expressions that contain shell-sensitive characters such as `&`, quote or escape the value as
@@ -222,14 +216,14 @@ For SQL Server in a Linux container, WSL, or another host where SQL authenticati
 You can override the config file path with the `MDS_TEST_CONFIG` environment variable:
 
 ```bash
-MDS_TEST_CONFIG=/path/to/config.json msbuild build.proj -t:TestSqlClientManual -p:TestSet=2
+MDS_TEST_CONFIG=/path/to/config.json dotnet build build.proj -t:TestSqlClientManual -p:TestSet=2
 ```
 
 On PowerShell:
 
 ```powershell
 $env:MDS_TEST_CONFIG = "C:\path\to\config.json"
-msbuild build.proj -t:TestSqlClientManual -p:TestSet=2
+dotnet build build.proj -t:TestSqlClientManual -p:TestSet=2
 ```
 
 ## Configuration Properties
@@ -289,23 +283,23 @@ If `TestSet` is omitted, all sets are compiled and run. You can combine sets by
 Test results are written to `test_results` by default. Override the location with `TestResultsFolderPath`:
 
 ```bash
-msbuild build.proj -t:TestSqlClientUnit -p:TestResultsFolderPath=/tmp/sqlclient-test-results
+dotnet build build.proj -t:TestSqlClientUnit -p:TestResultsFolderPath=/tmp/sqlclient-test-results
 ```
 
 Hang blame collection is enabled by default with a `10m` timeout. To increase the timeout:
 
 ```bash
-msbuild build.proj -t:TestSqlClientManual -p:TestBlameTimeout=30m
+dotnet build build.proj -t:TestSqlClientManual -p:TestBlameTimeout=30m
 ```
 
 To disable hang blame collection:
 
 ```bash
-msbuild build.proj -t:TestSqlClientManual -p:TestBlameTimeout=0
+dotnet build build.proj -t:TestSqlClientManual -p:TestBlameTimeout=0
 ```
 
 Code coverage is enabled by default. To disable it for a faster local run:
 
 ```bash
-msbuild build.proj -t:TestSqlClientUnit -p:TestCodeCoverage=false
+dotnet build build.proj -t:TestSqlClientUnit -p:TestCodeCoverage=false
 ```
diff --git a/src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj b/src/Microsoft.Data.SqlClient/src/Microsoft.Data.SqlClient.csproj
@@ -83,7 +83,7 @@
     <SqlClientPackNuspecGeneratedPath Condition="'$(SqlClientPackNuspecGeneratedPath)' == ''">$(BaseIntermediateOutputPath)Microsoft.Data.SqlClient.pack.nuspec</SqlClientPackNuspecGeneratedPath>
 
     <NuspecVersion Condition="'$(NuspecVersion)' == ''">$(Version)</NuspecVersion>
-    <NuspecFile Condition="'$(NuspecFile)' == ''">$(RepoRoot)tools/specs/Microsoft.Data.SqlClient.nuspec</NuspecFile>
+    <NuspecFile Condition="'$(NuspecFile)' == ''">$(SqlClientPackNuspecTemplatePath)</NuspecFile>
     <NuspecBasePath Condition="'$(NuspecBasePath)' == ''">$([System.IO.Path]::GetDirectoryName('$(SqlClientPackNuspecTemplatePath)'))</NuspecBasePath>
     <IncludeSymbols Condition="'$(IncludeSymbols)' == ''">true</IncludeSymbols>
     <SymbolPackageFormat Condition="'$(SymbolPackageFormat)' == ''">snupkg</SymbolPackageFormat>
@@ -99,6 +99,13 @@
   <Target Name="PrepareSqlClientPackNuspec"
           BeforeTargets="GenerateNuspec"
           Condition="'$(NuspecFile)' == '$(SqlClientPackNuspecTemplatePath)'">
+      <Error Text="PrepareSqlClientPackNuspec requires AbstractionsPackageVersion. Specify -p:PackageVersionAbstractions=&lt;version&gt;."
+        Condition="'$(AbstractionsPackageVersion)' == ''" />
+      <Error Text="PrepareSqlClientPackNuspec requires LoggingPackageVersion. Specify -p:PackageVersionLogging=&lt;version&gt;."
+        Condition="'$(LoggingPackageVersion)' == ''" />
+      <Error Text="PrepareSqlClientPackNuspec requires NuspecVersion. Specify -p:NuspecVersion=&lt;version&gt;."
+        Condition="'$(NuspecVersion)' == ''" />
+
     <PropertyGroup>
       <_SqlClientPackNuspecExpandedText>$([System.IO.File]::ReadAllText('$(SqlClientPackNuspecTemplatePath)').Replace('$AbstractionsPackageVersion$','$(AbstractionsPackageVersion)').Replace('$LoggingPackageVersion$','$(LoggingPackageVersion)').Replace('<version>1.0.0</version>','<version>$(NuspecVersion)</version>'))</_SqlClientPackNuspecExpandedText>
     </PropertyGroup>
