Skip to content

Commit 407ad04

Browse files
benrr101benrr101
committed
Merge branch 'main' into dev/russellben/en-manual-tests-certificate-gen
2 parents 8d7c393 + c5e3c40 commit 407ad04

File tree

288 files changed

+13488
-23641
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

288 files changed

+13488
-23641
lines changed

‎BUILDGUIDE.md

Lines changed: 111 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Once the environment is setup properly, execute the desired set of commands belo
3030
|`RunTests`|Runs the functional and manual tests for the .NET Framework and .NET drivers|
3131
|`RunFunctionalTests`|Runs just the functional tests for the .NET Framework and .NET drivers|
3232
|`RunManualTests`|Runs just the manual tests for the .NET Framework and .NET drivers|
33+
|`BuildAkv`|Builds the Azure Key Vault Provider package for all supported platforms.|
3334

3435

3536
### Parameters
@@ -338,14 +339,118 @@ dotnet test <test_properties...> --collect:"XPlat Code Coverage"
338339

339340
## Run Performance Tests
340341

341-
### Running Performance test project directly
342+
The performance tests live here:
343+
`src\Microsoft.Data.SqlClient\tests\PerformanceTests\`
342344

343-
Project location from Root: `src\Microsoft.Data.SqlClient\tests\PerformanceTests\Microsoft.Data.SqlClient.PerformanceTests.csproj`
344-
Configure `runnerconfig.json` file with connection string and preferred settings to run Benchmark Jobs.
345+
They can be run from the command line by following the instructions below.
346+
347+
Launch a shell and change into the project directory:
348+
349+
PowerShell:
350+
351+
```pwsh
352+
> cd src\Microsoft.Data.SqlClient\tests\PerformanceTests
353+
```
354+
355+
Bash:
356+
357+
```bash
358+
$ cd src/Microsoft.Data.SqlClient/tests/PerformanceTests
359+
```
360+
361+
### Create Database
362+
363+
Create an empty database for the benchmarks to use. This example assumes
364+
a local SQL server instance using SQL authentication:
345365

346366
```bash
347-
cd src\Microsoft.Data.SqlClient\tests\PerformanceTests
348-
dotnet run -c Release -f net8.0
367+
$ sqlcmd -S localhost -U sa -P password
368+
1> create database [sqlclient-perf-db]
369+
2> go
370+
1> quit
371+
```
372+
373+
The default `runnerconfig.json` expects a database named `sqlclient-perf-db`,
374+
but you may change the config to use any existing database. All tables in
375+
the database will be dropped when running the benchmarks.
376+
377+
### Configure Runner
378+
379+
Configure the benchmarks by editing the `runnerconfig.json` file directly in the
380+
`PerformanceTests` directory with an appropriate connection string and benchmark
381+
settings:
382+
383+
```json
384+
{
385+
"ConnectionString": "Server=tcp:localhost; Integrated Security=true; Initial Catalog=sqlclient-perf-db;",
386+
"UseManagedSniOnWindows": false,
387+
"Benchmarks":
388+
{
389+
"SqlConnectionRunnerConfig":
390+
{
391+
"Enabled": true,
392+
"LaunchCount": 1,
393+
"IterationCount": 50,
394+
"InvocationCount":30,
395+
"WarmupCount": 5,
396+
"RowCount": 0
397+
},
398+
...
399+
}
400+
}
349401
```
350402

351-
_Only "**Release** Configuration" applies to Performance Tests_
403+
Individual benchmarks may be enabled or disabled, and each has several
404+
benchmarking options for fine tuning.
405+
406+
After making edits to `runnerconfig.json` you must perform a build which will
407+
copy the file into the `artifacts` directory alongside the benchmark DLL. By
408+
default, the benchmarks look for `runnerconfig.json` in the same directory as
409+
the DLL.
410+
411+
Optionally, to avoid polluting your git workspace and requring a build after
412+
each config change, copy `runnerconfig.json` to a new file, make your edits
413+
there, and then specify the new file with the RUNNER_CONFIG environment
414+
variable.
415+
416+
PowerShell:
417+
418+
```pwsh
419+
> copy runnerconfig.json $HOME\.configs\runnerconfig.json
420+
421+
# Make edits to $HOME\.configs\runnerconfig.json
422+
423+
# You must set the RUNNER_CONFIG environment variable for the current shell.
424+
> $env:RUNNER_CONFIG="${HOME}\.configs\runnerconfig.json"
425+
```
426+
427+
Bash:
428+
429+
```bash
430+
$ cp runnerconfig.json ~/.configs/runnerconfig.json
431+
432+
# Make edits to ~/.configs/runnerconfig.json
433+
434+
# Optionally export RUNNER_CONFIG.
435+
$ export RUNNER_CONFIG=~/.configs/runnerconfig.json
436+
```
437+
438+
### Run Benchmarks
439+
440+
All benchmarks must be compiled and run in **Release** configuration.
441+
442+
PowerShell:
443+
444+
```pwsh
445+
> dotnet run -c Release -f net9.0
446+
```
447+
448+
Bash:
449+
450+
```bash
451+
# Omit RUNNER_CONFIG if you exported it earlier, or if you're using the
452+
# copy prepared by the build.
453+
$ dotnet run -c Release -f net9.0
454+
455+
$ RUNNER_CONFIG=~/.configs/runnerconfig.json dotnet run -c Release -f net9.0
456+
```

‎azurepipelines-coverage.yml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Azure DevOps code coverage settings:
2+
#
3+
# https://learn.microsoft.com/en-us/azure/devops/pipelines/test/codecoverage-for-pullrequests?view=azure-devops#configuring-coverage-settings
4+
#
5+
coverage:
6+
# Code coverage status will be posted to pull requests based on targets
7+
# defined below.
8+
status:
9+
# Off by default. When on, details about coverage for each file changed will
10+
# be posted as a pull request comment.
11+
comments: on
12+
# Diff coverage is code coverage only for the lines changed in a pull
13+
# request.
14+
diff:
15+
# Set this to a desired %. Default is 70%.
16+
target: 70%

‎build.proj

Lines changed: 131 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -178,21 +178,109 @@
178178
</Target>
179179

180180
<!-- Tests -->
181+
182+
<!-- Run all unit tests applicable to the host OS. -->
181183
<Target Name="RunTests" DependsOnTargets="RunFunctionalTests;RunManualTests"/>
182-
<Target Name="RunFunctionalTests">
183-
<!-- Windows -->
184-
<Exec ConsoleToMsBuild="true" Command="$(DotnetPath)dotnet test &quot;@(FunctionalTestsProj)&quot; -p:Configuration=$(Configuration) -p:Target$(TFGroup)Version=$(TF) -p:ReferenceType=$(ReferenceType) --no-build -v n --collect &quot;Code coverage&quot; -p:TestSet=$(TestSet) --results-directory $(ResultsDirectory) -p:TestTargetOS=Windows$(TargetGroup) --filter &quot;category!=non$(TargetGroup)tests&amp;category!=failing&amp;category!=nonwindowstests&quot; &quot;--logger:trx;LogFilePrefix=Functional-Windows$(TargetGroup)-$(TestSet)&quot;" Condition="'$(IsEnabledWindows)' == 'true'"/>
185-
<!-- Unix -->
186-
<Exec ConsoleToMsBuild="true" Command="$(DotnetPath)dotnet test &quot;@(FunctionalTestsProj)&quot; -p:Configuration=$(Configuration) -p:TargetNetCoreVersion=$(TF) -p:ReferenceType=$(ReferenceType) --no-build -v n -p:TestSet=$(TestSet) --results-directory $(ResultsDirectory) -p:TestTargetOS=Unixnetcoreapp --collect &quot;Code coverage&quot; --filter &quot;category!=nonnetcoreapptests&amp;category!=failing&amp;category!=nonlinuxtests&amp;category!=nonuaptests&quot; &quot;--logger:trx;LogFilePrefix=Functional-Unixnetcoreapp-$(TestSet)&quot;" Condition="'$(IsEnabledWindows)' != 'true'"/>
184+
185+
<!-- Run all Functional tests applicable to the host OS. -->
186+
<Target Name="RunFunctionalTests" DependsOnTargets="RunFunctionalTestsWindows;RunFunctionalTestsUnix"/>
187+
188+
<!-- Run all Functional tests applicable to Windows. -->
189+
<Target Name="RunFunctionalTestsWindows" Condition="'$(IsEnabledWindows)' == 'true'">
190+
<PropertyGroup>
191+
<TestCommand>
192+
$(DotnetPath)dotnet test "@(FunctionalTestsProj)"
193+
--no-build
194+
-v n
195+
-p:Configuration=$(Configuration)
196+
-p:Target$(TFGroup)Version=$(TF)
197+
-p:ReferenceType=$(ReferenceType)
198+
-p:TestSet=$(TestSet)
199+
-p:TestTargetOS=Windows$(TargetGroup)
200+
--collect "Code coverage"
201+
--results-directory $(ResultsDirectory)
202+
--filter "category!=non$(TargetGroup)tests&amp;category!=failing&amp;category!=nonwindowstests"
203+
--logger:"trx;LogFilePrefix=Functional-Windows$(TargetGroup)-$(TestSet)"
204+
</TestCommand>
205+
<TestCommand>$(TestCommand.Replace($([System.Environment]::NewLine), " "))</TestCommand>
206+
</PropertyGroup>
207+
<Message Text=">>> Running Functional test for Windows via command: $(TestCommand)"/>
208+
<Exec ConsoleToMsBuild="true" Command="$(TestCommand)"/>
209+
</Target>
210+
211+
<!-- Run all Functional tests applicable to Unix. -->
212+
<Target Name="RunFunctionalTestsUnix" Condition="'$(IsEnabledWindows)' != 'true'">
213+
<PropertyGroup>
214+
<TestCommand>
215+
$(DotnetPath)dotnet test "@(FunctionalTestsProj)"
216+
--no-build
217+
-v n
218+
-p:Configuration=$(Configuration)
219+
-p:TargetNetCoreVersion=$(TF)
220+
-p:ReferenceType=$(ReferenceType)
221+
-p:TestSet=$(TestSet)
222+
-p:TestTargetOS=Unixnetcoreapp
223+
--collect "Code coverage"
224+
--results-directory $(ResultsDirectory)
225+
--filter "category!=nonnetcoreapptests&amp;category!=failing&amp;category!=nonlinuxtests&amp;category!=nonuaptests"
226+
--logger:"trx;LogFilePrefix=Functional-Unixnetcoreapp-$(TestSet)"
227+
</TestCommand>
228+
<TestCommand>$(TestCommand.Replace($([System.Environment]::NewLine), " "))</TestCommand>
229+
</PropertyGroup>
230+
<Message Text=">>> Running Functional test for Unix via command: $(TestCommand)"/>
231+
<Exec ConsoleToMsBuild="true" Command="$(TestCommand)"/>
232+
</Target>
233+
234+
<!-- Run all Manual tests applicable to the host OS. -->
235+
<Target Name="RunManualTests" DependsOnTargets="RunManualTestsWindows;RunManualTestsUnix"/>
236+
237+
<!-- Run all Manual tests applicable to Windows. -->
238+
<Target Name="RunManualTestsWindows" Condition="'$(IsEnabledWindows)' == 'true'">
239+
<PropertyGroup>
240+
<TestCommand>
241+
$(DotnetPath)dotnet test "@(ManualTestsProj)"
242+
--no-build
243+
-v n
244+
-p:Configuration=$(Configuration)
245+
-p:Target$(TFGroup)Version=$(TF)
246+
-p:ReferenceType=$(ReferenceType)
247+
-p:TestSet=$(TestSet)
248+
-p:TestTargetOS=Windows$(TargetGroup)
249+
--collect "Code coverage"
250+
--results-directory $(ResultsDirectory)
251+
--filter "category!=non$(TargetGroup)tests&amp;category!=failing&amp;category!=nonwindowstests"
252+
--logger:"trx;LogFilePrefix=Manual-Windows$(TargetGroup)-$(TestSet)"
253+
</TestCommand>
254+
<TestCommand>$(TestCommand.Replace($([System.Environment]::NewLine), " "))</TestCommand>
255+
</PropertyGroup>
256+
<Message Text=">>> Running Manual test for Windows via command: $(TestCommand)"/>
257+
<Exec ConsoleToMsBuild="true" Command="$(TestCommand)"/>
187258
</Target>
188259

189-
<Target Name="RunManualTests">
190-
<!-- Windows -->
191-
<Exec ConsoleToMsBuild="true" Command="$(DotnetPath)dotnet test &quot;@(ManualTestsProj)&quot; -p:Configuration=$(Configuration) -p:Target$(TFGroup)Version=$(TF) -p:ReferenceType=$(ReferenceType) --no-build -l &quot;console;verbosity=normal&quot; --collect &quot;Code coverage&quot; -p:TestSet=$(TestSet) --results-directory $(ResultsDirectory) -p:TestTargetOS=Windows$(TargetGroup) --filter &quot;category!=non$(TargetGroup)tests&amp;category!=failing&amp;category!=nonwindowstests&quot; &quot;--logger:trx;LogFilePrefix=Manual-Windows$(TargetGroup)-$(TestSet)&quot;" Condition="'$(IsEnabledWindows)' == 'true'"/>
192-
<!-- Unix -->
193-
<Exec ConsoleToMsBuild="true" Command="$(DotnetPath)dotnet test &quot;@(ManualTestsProj)&quot; -p:Configuration=$(Configuration) -p:TargetNetCoreVersion=$(TF) -p:ReferenceType=$(ReferenceType) --no-build -l &quot;console;verbosity=normal&quot; --collect &quot;Code coverage&quot; -p:TestSet=$(TestSet) --results-directory $(ResultsDirectory) -p:TestTargetOS=Unixnetcoreapp --filter &quot;category!=nonnetcoreapptests&amp;category!=failing&amp;category!=nonlinuxtests&amp;category!=nonuaptests&quot; &quot;--logger:trx;LogFilePrefix=Manual-Unixnetcoreapp-$(TestSet)&quot;" Condition="'$(IsEnabledWindows)' != 'true'"/>
260+
<!-- Run all Manual tests applicable to Unix. -->
261+
<Target Name="RunManualTestsUnix" Condition="'$(IsEnabledWindows)' != 'true'">
262+
<PropertyGroup>
263+
<TestCommand>
264+
$(DotnetPath)dotnet test "@(ManualTestsProj)"
265+
--no-build
266+
-v n
267+
-p:Configuration=$(Configuration)
268+
-p:TargetNetCoreVersion=$(TF)
269+
-p:ReferenceType=$(ReferenceType)
270+
-p:TestSet=$(TestSet)
271+
-p:TestTargetOS=Unixnetcoreapp
272+
--collect "Code coverage"
273+
--results-directory $(ResultsDirectory)
274+
--filter "category!=nonnetcoreapptests&amp;category!=failing&amp;category!=nonlinuxtests&amp;category!=nonuaptests"
275+
--logger:"trx;LogFilePrefix=Manual-Unixnetcoreapp-$(TestSet)"
276+
</TestCommand>
277+
<TestCommand>$(TestCommand.Replace($([System.Environment]::NewLine), " "))</TestCommand>
278+
</PropertyGroup>
279+
<Message Text=">>> Running Manual test for Unix via command: $(TestCommand)"/>
280+
<Exec ConsoleToMsBuild="true" Command="$(TestCommand)"/>
194281
</Target>
195282

283+
<!-- Clean -->
196284
<Target Name="Clean">
197285
<RemoveDir Directories='$([System.IO.Directory]::GetDirectories(".","artifacts", SearchOption.AllDirectories))' />
198286
<RemoveDir Directories='$([System.IO.Directory]::GetDirectories(".","bin", SearchOption.AllDirectories))' />
@@ -201,6 +289,39 @@
201289
<RemoveDir Directories='$([System.IO.Directory]::GetDirectories(".",".nuget", SearchOption.AllDirectories))' />
202290
</Target>
203291

292+
<!-- AKV Targets ========================================================= -->
293+
<Target Name="BuildAkv">
294+
<!-- @TODO: TestTargetOS for restore poisons the project.assets.json file... We should remove it. -->
295+
<!-- @TODO: TestTargetOS makes this far more complicated than it needs to be. We should remove it. -->
296+
<!-- @TODO: RemoveProperties shouldn't be necessary -->
297+
<Message Text=">>> Restoring AKV project" />
298+
<MSBuild Projects="@(AKVProvider)" Targets="Restore"/>
299+
300+
<PropertyGroup>
301+
<BuildAkvProperties>$(CI);TestTargetOS=$(TestOS)netfx;Platform=AnyCPU;$(ProjectProperties);$(NugetPackProperties)</BuildAkvProperties>
302+
</PropertyGroup>
303+
<Message Text=">>> Building AKV project for netfx [$(BuildAkvProperties)]" />
304+
<MSBuild Projects="@(AKVProvider)" Properties="$(BuildAkvProperties);" />
305+
306+
<PropertyGroup>
307+
<BuildAkvProperties>$(CI);TestTargetOS=$(TestOS)netcoreapp;$(ProjectProperties);Platform=AnyCPU;OSGroup=Unix;</BuildAkvProperties>
308+
</PropertyGroup>
309+
<Message Text=">>> Building AKV project for netcore/unix [$(BuildAkvProperties)]" />
310+
<MSBuild Projects="@(AKVProvider)" Properties="$(BuildAkvProperties)" RemoveProperties="TargetsWindows;TargetsUnix;" />
311+
312+
<PropertyGroup>
313+
<BuildAkvProperties>$(CI);TestTargetOS=$(TestOS)netcoreapp;$(ProjectProperties);Platform=AnyCPU;OSGroup=Windows_NT</BuildAkvProperties>
314+
</PropertyGroup>
315+
<Message Text=">>> Building AKV project for netcore/windows [$(BuildAkvProperties)]" />
316+
<MSBuild Projects="@(AKVProvider)" Properties="$(BuildAkvProperties);" RemoveProperties="TargetsWindows;TargetsUnix;" />
317+
318+
<PropertyGroup>
319+
<BuildAkvProperties>$(CI);TestTargetOS=$(TestOS)netcoreapp;$(ProjectProperties);Platform=AnyCPU;OSGroup=AnyOS;</BuildAkvProperties>
320+
</PropertyGroup>
321+
<Message Text=">>> Building AKV project for netcore/anyos [$(BuildAkvProperties)]" />
322+
<MSBuild Projects="@(AKVProvider)" Properties="$(BuildAkvProperties)" RemoveProperties="TargetsWindows;TargetsUnix;" />
323+
</Target>
324+
204325
<Target Name="BuildAKVNetFx" Condition="'$(IsEnabledWindows)' == 'true'">
205326
<MSBuild Projects="@(AKVProvider)" Targets="restore" Properties="TestTargetOS=$(TestOS)netfx" />
206327
<Message Text=">>> Building AKVNetFx [$(CI);TestTargetOS=$(TestOS)netfx;Platform=AnyCPU;$(TestProjectProperties)] ..." Condition="!$(ReferenceType.Contains('Package'))"/>

‎doc/snippets/Microsoft.Data.Sql/SqlDataSourceEnumerator.xml

Lines changed: 19 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -18,47 +18,25 @@
1818
<returns>
1919
A <see cref="T:System.Data.DataTable" /> containing information about the visible SQL Server instances.
2020
</returns>
21-
<remarks>
22-
<para>
23-
The table returned by this method contains the following columns, all of which contain strings:
24-
</para>
25-
<para>
26-
<list type="table">
27-
<listheader>
28-
<term>Column</term>
29-
<description>Description</description>
30-
</listheader>
31-
<item>
32-
<term><b>ServerName</b></term>
33-
<description>Name of the server.</description>
34-
</item>
35-
<item>
36-
<term><b>InstanceName</b></term>
37-
<description>Name of the server instance. Blank if the server is running as the default instance.</description>
38-
</item>
39-
<item>
40-
<term><b>IsClustered</b></term>
41-
<description>Indicates whether the server is part of a cluster.</description>
42-
</item>
43-
<item>
44-
<term><b>Version</b></term>
45-
<description>
46-
Version of the server:
47-
<list type="bullet">
48-
<item>10.0.xx for SQL Server 2008</item>
49-
<item>10.50.x for SQL Server 2008 R2</item>
50-
<item>11.0.xx for SQL Server 2012 </item>
51-
<item>12.0.xx for SQL Server 2014</item>
52-
<item>13.0.xx for SQL Server 2016</item>
53-
<item>14.0.xx for SQL Server 2017</item>
54-
</list>
55-
</description>
56-
</item>
57-
</list>
58-
<note type="note">
59-
Due to the nature of the mechanism used by <see cref="T:Microsoft.Data.Sql.SqlDataSourceEnumerator" /> to locate data sources on a network, the method will not always return a complete list of the available servers, and the list might not be the same on every call. If you plan to use this function to let users select a server from a list, make sure that you always also supply an option to type in a name that is not in the list, in case the server enumeration does not return all the available servers. In addition, this method may take a significant amount of time to execute, so be careful about calling it when performance is critical.
60-
</note>
61-
</para>
21+
<remarks>
22+
<format type="text/markdown">
23+
<![CDATA[
24+
25+
## Remarks
26+
The table returned by this method contains the following columns, all of which contain strings:
27+
28+
|Column|Description|
29+
|------------|-----------------|
30+
|**ServerName**|Name of the server.|
31+
|**InstanceName**|Name of the server instance. Blank if the server is running as the default instance.|
32+
|**IsClustered**|Indicates whether the server is part of a cluster.|
33+
|**Version**|Version of the server:<ul><li>10.0.xx for SQL Server 2008</li><li>10.50.x for SQL Server 2008 R2</li><li>11.0.xx for SQL Server 2012</li><li>12.0.xx for SQL Server 2014</li><li>13.0.xx for SQL Server 2016</li><li>14.0.xx for SQL Server 2017</li></ul>|
34+
35+
> [!NOTE]
36+
> Due to the nature of the mechanism used by <xref:Microsoft.Data.Sql.SqlDataSourceEnumerator> to locate data sources on a network, the method will not always return a complete list of the available servers, and the list might not be the same on every call. If you plan to use this function to let users select a server from a list, make sure that you always also supply an option to type in a name that is not in the list, in case the server enumeration does not return all the available servers. In addition, this method may take a significant amount of time to execute, so be careful about calling it when performance is critical.
37+
38+
]]>
39+
</format>
6240
</remarks>
6341
<example>
6442
<para>

0 commit comments

Comments
 (0)