Skip to content

Latest commit

 

History

History
321 lines (231 loc) · 15.4 KB

BUILDGUIDE.md

File metadata and controls

321 lines (231 loc) · 15.4 KB

Guidelines for Building Microsoft.Data.SqlClient

This document provides all the necessary details to build the driver and run tests present in the repository.

Visual Studio Pre-Requisites

This project should be built with Visual Studio 2019+ for the best compatibility. The required set of components are provided in the below file:

Once the environment is setup properly, execute the desired set of commands below from the root folder to perform the respective operations:

Building the driver

# Default Build Configuration:

msbuild
# Builds the driver for the Client OS in 'Debug' Configuration for 'AnyCPU' platform.
# Both .NET Framework  (NetFx) and .NET Core drivers are built by default (as supported by Client OS).
msbuild -p:Configuration=Release
# Builds the driver in 'Release' Configuration for `AnyCPU` platform.
msbuild -p:Platform=Win32
# Builds the .NET Framework (NetFx) driver for Win32 (x86) platform on Windows in 'Debug' Configuration.
msbuild -t:clean
# Cleans all build directories.
msbuild -t:restore
# Restores Nuget Packages.
msbuild -t:BuildAllConfigurations
# Builds the driver for all target OSes and supported platforms.
msbuild -p:BuildNetFx=false
# Skips building the .NET Framework (NetFx) Driver on Windows.
# On Unix the netfx driver build is automatically skipped.
msbuild -p:OSGroup=Unix
# Builds the driver for the Unix platform.
msbuild -t:BuildNetCoreAllOS
# Builds the .NET Core driver for all Operating Systems.

Building Tests

msbuild -t:BuildTestsNetCore
# Build the tests for the .NET Core driver in 'Debug' Configuration. Default .NET Core version is 2.1.
msbuild -t:BuildTestsNetFx
# Build the tests for the .NET Framework (NetFx) driver in 'Debug' Configuration. Default .NET Framework version is 4.6.1.

Run Functional Tests

  • Windows (netfx x86):
dotnet test "src\Microsoft.Data.SqlClient\tests\FunctionalTests\Microsoft.Data.SqlClient.Tests.csproj" -p:Platform="Win32" -p:Configuration="Release" -p:TestTargetOS="Windowsnetfx" --no-build -v n --filter "category!=nonnetfxtests&category!=failing&category!=nonwindowstests"
  • Windows (netfx x64):
dotnet test "src\Microsoft.Data.SqlClient\tests\FunctionalTests\Microsoft.Data.SqlClient.Tests.csproj" -p:Platform="x64" -p:Configuration="Release" -p:TestTargetOS="Windowsnetfx" --no-build -v n --filter "category!=nonnetfxtests&category!=failing&category!=nonwindowstests"

  • AnyCPU:

    Windows (netcoreapp):

dotnet test "src\Microsoft.Data.SqlClient\tests\FunctionalTests\Microsoft.Data.SqlClient.Tests.csproj" -p:Platform="AnyCPU" -p:Configuration="Release" -p:TestTargetOS="Windowsnetcoreapp" --no-build -v n --filter "category!=nonnetcoreapptests&category!=failing&category!=nonwindowstests"

Unix (netcoreapp):

dotnet test "src/Microsoft.Data.SqlClient/tests/FunctionalTests/Microsoft.Data.SqlClient.Tests.csproj" -p:Platform="AnyCPU" -p:Configuration="Release" -p:TestTargetOS="Unixnetcoreapp" --no-build -v n --filter "category!=nonnetcoreapptests&category!=failing&category!=nonlinuxtests&category!=nonuaptests"

Run Manual Tests

Pre-Requisites for running Manual tests:

Manual Tests require the below setup to run:

  • SQL Server with enabled Shared Memory, TCP and Named Pipes Protocols and access to the Client OS.

  • Databases "NORTHWIND" and "UdtTestDb" present in SQL Server, created using SQL scripts createNorthwindDb.sql and createUdtTestDb.sql. To setup an Azure Database with "NORTHWIND" tables, use SQL Script: createNorthwindAzureDb.sql.

  • Make a copy of the configuration file config.default.json and rename it to config.json. Update the values in config.json:

    Property Description Value
    TCPConnectionString Connection String for a TCP enabled SQL Server instance. Server={servername};Database={Database_Name};Trusted_Connection=True;
    OR Data Source={servername};Initial Catalog={Database_Name};Integrated Security=True;
    NPConnectionString Connection String for a Named Pipes enabled SQL Server instance. Server=\\{servername}\pipe\sql\query;Database={Database_Name};Trusted_Connection=True;
    OR
    Data Source=np:{servername};Initial Catalog={Database_Name};Integrated Security=True;
    TCPConnectionStringHGSVBS (Optional) Connection String for a TCP enabled SQL Server with Host Guardian Service (HGS) attestation protocol configuration. Server=tcp:{servername}; Database={Database_Name}; UID={UID}; PWD={PWD}; Attestation Protocol = HGS; Enclave Attestation Url = {AttestationURL};
    AADAuthorityURL (Optional) Identifies the OAuth2 authority resource for Server specified in AADPasswordConnectionString https://login.windows.net/<tenant>, where <tenant> is the tenant ID of the Azure Active Directory (Azure AD) tenant
    AADPasswordConnectionString (Optional) Connection String for testing Azure Active Directory Password Authentication. Data Source={server.database.windows.net}; Initial Catalog={Azure_DB_Name};Authentication=Active Directory Password; User ID={AAD_User}; Password={AAD_User_Password};
    AADSecurePrincipalId (Optional) The Application Id of a registered application which has been granted permission to the database defined in the AADPasswordConnectionString. {Application ID}
    AADSecurePrincipalSecret (Optional) A Secret defined for a registered application which has been granted permission to the database defined in the AADPasswordConnectionString. {Secret}
    AzureKeyVaultURL (Optional) Azure Key Vault Identifier URL https://{keyvaultname}.vault.azure.net/
    AzureKeyVaultTenantId (Optional) The Azure Active Directory tenant (directory) Id of the service principal. {Tenant ID of Active Directory}
    AzureKeyVaultClientId (Optional) "Application (client) ID" of an Active Directory registered application, granted access to the Azure Key Vault specified in AZURE_KEY_VAULT_URL. Requires the key permissions Get, List, Import, Decrypt, Encrypt, Unwrap, Wrap, Verify, and Sign. {Client Application ID}
    AzureKeyVaultClientSecret (Optional) "Client Secret" of the Active Directory registered application, granted access to the Azure Key Vault specified in AZURE_KEY_VAULT_URL {Client Application Secret}
    LocalDbAppName (Optional) If Local Db Testing is supported, this property configures the name of Local DB App instance available in client environment. Empty string value disables Local Db testing. Name of Local Db App to connect to.
    SupportsIntegratedSecurity (Optional) Whether or not the USER running tests has integrated security access to the target SQL Server. true OR false
    SupportsFileStream (Optional) Whether or not FileStream is enabled on SQL Server true OR false
    UseManagedSNIOnWindows (Optional) Enables testing with Managed SNI on Windows true OR false
    IsAzureSynpase (Optional) When set to 'true', test suite runs compatible tests for Azure Synapse/Parallel Data Warehouse. true OR false

Commands to run Manual Tests:

  • Windows (netfx x86):
dotnet test "src\Microsoft.Data.SqlClient\tests\ManualTests\Microsoft.Data.SqlClient.ManualTesting.Tests.csproj" -p:Platform="Win32" -p:Configuration="Release" -p:TestTargetOS="Windowsnetfx" --no-build -v n --filter "category!=nonnetfxtests&category!=failing&category!=nonwindowstests"
  • Windows (netfx x64):
dotnet test "src\Microsoft.Data.SqlClient\tests\ManualTests\Microsoft.Data.SqlClient.ManualTesting.Tests.csproj" -p:Platform="x64" -p:Configuration="Release" -p:TestTargetOS="Windowsnetfx" --no-build -v n --filter "category!=nonnetfxtests&category!=failing&category!=nonwindowstests"

  • AnyCPU:

    Windows (netfx):

dotnet test "src\Microsoft.Data.SqlClient\tests\ManualTests\Microsoft.Data.SqlClient.ManualTesting.Tests.csproj" -p:Platform="AnyCPU" -p:Configuration="Release" -p:TestTargetOS="Windowsnetfx" --no-build -v n --filter "category!=nonnetfxtests&category!=failing&category!=nonwindowstests"
Windows (`netcoreapp`):

dotnet test "src\Microsoft.Data.SqlClient\tests\ManualTests\Microsoft.Data.SqlClient.ManualTesting.Tests.csproj" -p:Platform="AnyCPU" -p:Configuration="Release" -p:TestTargetOS="Windowsnetcoreapp" --no-build -v n --filter "category!=nonnetcoreapptests&category!=failing&category!=nonwindowstests"
Unix (`netcoreapp`):

dotnet test "src/Microsoft.Data.SqlClient/tests/ManualTests/Microsoft.Data.SqlClient.ManualTesting.Tests.csproj" -p:Platform="AnyCPU" -p:Configuration="Release" -p:TestTargetOS="Unixnetcoreapp" --no-build -v n --filter "category!=nonnetcoreapptests&category!=failing&category!=nonlinuxtests&category!=nonuaptests"

Run A Single Test

dotnet test "src\Microsoft.Data.SqlClient\tests\ManualTests\Microsoft.Data.SqlClient.ManualTesting.Tests.csproj" -p:Platform="AnyCPU" -p:Configuration="Release" -p:TestTargetOS="Windowsnetcoreapp" --no-build -v n --filter "FullyQualifiedName=Microsoft.Data.SqlClient.ManualTesting.Tests.AlwaysEncrypted.CspProviderExt.TestKeysFromCertificatesCreatedWithMultipleCryptoProviders"

Testing with Custom ReferenceType

Tests can be built and run with custom "Reference Type" property that enables different styles of testing:

  • "Project" => Build and run tests with Microsoft.Data.SqlClient as Project Reference
  • "Package" => Build and run tests with Microsoft.Data.SqlClient as Package Reference with configured "TestMicrosoftDataSqlClientVersion" in "Versions.props" file.
  • "NetStandard" => Build and run tests with Microsoft.Data.SqlClient as Project Reference via .NET Standard Library
  • "NetStandardPackage" => Build and run tests with Microsoft.Data.SqlClient as Package Reference via .NET Standard Library

************** IMPORTANT NOTE BEFORE PROCEEDING WITH "PACKAGE" AND "NETSTANDARDPACKAGE" REFERENCE TYPES *************** CREATE A NUGET PACKAGE WITH BELOW COMMAND AND ADD TO LOCAL FOLDER + UPDATE NUGET CONFIG FILE TO READ FROM THAT LOCATION

 msbuild -p:configuration=Release

Building Tests:

For .NET Core, all 4 reference types are supported:

msbuild -t:BuildTestsNetCore -p:ReferenceType=Project
# Default setting uses Project Reference.

msbuild -t:BuildTestsNetCore -p:ReferenceType=Package

msbuild -t:BuildTestsNetCore -p:ReferenceType=NetStandard

msbuild -t:BuildTestsNetCore -p:ReferenceType=NetStandardPackage

For .NET Framework, below reference types are supported:

msbuild -t:BuildTestsNetFx -p:ReferenceType=Project
# Default setting uses Project Reference.

msbuild -t:BuildTestsNetFx -p:ReferenceType=Package

Running Tests:

Provide property to dotnet test commands for testing desired reference type.

dotnet test -p:ReferenceType=Project ...

Testing with Custom TargetFramework

Tests can be built and run with custom Target Frameworks. See the below examples.

Building Tests:

msbuild -t:BuildTestsNetFx -p:TargetNetFxVersion=net462
# Build the tests for custom TargetFramework (.NET Framework)
# Applicable values: net461 (Default) | net462 | net47 | net471  net472 | net48
msbuild -t:BuildTestsNetCore -p:TargetNetCoreVersion=netcoreapp3.1
# Build the tests for custom TargetFramework (.NET Core)
# Applicable values: netcoreapp2.1 | netcoreapp2.2 | netcoreapp3.1 | net5.0

Running Tests:

dotnet test -p:TargetNetFxVersion=net462 ...
# Use above property to run Functional Tests with custom TargetFramework (.NET Framework)
# Applicable values: net461 (Default) | net462 | net47 | net471  net472 | net48

dotnet test -p:TargetNetCoreVersion=netcoreapp3.1 ...
# Use above property to run Functional Tests with custom TargetFramework (.NET Core)
# Applicable values: netcoreapp2.1 | netcoreapp2.2 | netcoreapp3.1 | net5.0

Using Managed SNI on Windows

Managed SNI can be enabled on Windows by enabling the below AppContext switch:

"Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows"

Set truncation on for scaled decimal parameters

Scaled decimal parameter truncation can be enabled by enabling the below AppContext switch:

"Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal"

Enabling configurable retry logic

To use this feature, you must enable the following AppContext switch at application startup:

"Switch.Microsoft.Data.SqlClient.EnableRetryLogic"

Enabling row version null behavior

SqlDataReader returns a DBNull value instead of an empty byte[]. To enable the legacy behavior, you must enable the following AppContext switch on application startup:

"Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior"

Enabling OS secure protocols preference

TLS 1.3 has been excluded due to the fact that the driver lacks full support. To enable OS preferences as before, enable the following AppContext switch on application startup:

"Switch.Microsoft.Data.SqlClient.EnableSecureProtocolsByOS"

Debugging SqlClient on Linux from Windows

For enhanced developer experience, we support debugging SqlClient on Linux from Windows, using the project "Microsoft.Data.SqlClient.DockerLinuxTest" that requires "Container Tools" to be enabled in Visual Studio. You may import configuration: VS19Components.vsconfig if not enabled already.

This project is also included in docker-compose.yml to demonstrate connectivity with SQL Server docker image.

To run the same:

  1. Build the Solution in Visual Studio
  2. Set docker-compose as Startup Project
  3. Run "Docker-Compose" launch configuration.
  4. You will see similar message in Debug window: 
    Connected to SQL Server v15.00.4023 from Unix 4.19.76.0
The program 'dotnet' has exited with code 0 (0x0).
  5. Now you can write code in Program.cs to debug SqlClient on Linux!

Troubleshooting Docker issues

There may be times where connection cannot be made to SQL Server, we found below ideas helpful:

  • Clear Docker images to create clean image from time-to-time, and clear docker cache if needed by running docker system prune in Command Prompt.

  • If you face Microsoft.Data.SqlClient.SNI.dll not found errors when debugging, try updating the below properties in the netcore\Microsoft.Data.SqlClient.csproj file and try again:

      <OSGroup>Unix</OSGroup>
  <TargetsWindows>false</TargetsWindows>
  <TargetsUnix>true</TargetsUnix>

Collecting Code Coverage

Using VSTest

dotnet test <test_properties...> --collect:"Code Coverage"

Using Coverlet Collector

dotnet test <test_properties...> --collect:"XPlat Code Coverage"

Run Performance Tests

Running Performance test project directly:

Project location from Root: src\Microsoft.Data.SqlClient\tests\PerformanceTests\Microsoft.Data.SqlClient.PerformanceTests.csproj Configure runnerconfig.json file with connection string and preferred settings to run Benchmark Jobs.

cd src\Microsoft.Data.SqlClient\tests\PerformanceTests
dotnet run -c Release -f netcoreapp3.1|net5.0

Only "Release Configuration" applies to Performance Tests