Microsoft.Data.SqlClient 名前空間の概要

[アーティクル]
05/31/2024

Microsoft.Data.SqlClient 名前空間は、実質的には System.Data.SqlClient 名前空間の新しいバージョンです。 Microsoft.Data.SqlClient は通常、System.Data.SqlClient と同じ API と下位互換性を維持します。 System.Data.SqlClient から Microsoft.Data.SqlClient への移行は、ほとんどのアプリケーションにおいては簡単です。 Microsoft.Data.SqlClient に NuGet 依存関係を追加し、参照と using ステートメントをMicrosoft.Data.SqlClient に更新します。

一部のアプリケーションに影響を与える可能性がある、System.Data.SqlClient と比較して使用頻度の低い API にはいくつかの違いがあります。これらの違いについては、便利な移植チートシートを参照してください。

API リファレンス

Microsoft.Data.SqlClient API の詳細は、.NET API ブラウザーに関する記事に記載されています。

Microsoft.Data.SqlClient 5.2 のリリースノート

5.2 の新機能

.NET Standard でのサポートがSqlDiagnosticListener追加されました。 #1931
新しい RowsCopied64 プロパティが SqlBulkCopy に追加されました。 #2004 詳細情報
AccessTokenCallBack に新しい SqlConnection API を追加しました。 #1260 詳細情報
Windows 上の .NET 上の暗号化の SuperSocketNetLib レジストリオプションのサポートを追加しました。 #2047
.NET 6 以降に SqlBatch サポートを追加 #1825、#2223 詳細情報
Workload Identity 認証サポート#2159、#2264 を追加しました
.NET #2210 でのローカライズサポートを追加しました
グルジア語照合#2194のサポートを追加しました
ビッグエンディアンシステム#2170のサポートを追加しました
.NET 8 サポート#2230を追加しました
System.Runtime.Caching 8.0.0、System.Configuration.ConfigurationManager 8.0.0、System.Diagnostics.DiagnosticSource 8.0.0 #2303 に、メジャー .NET バージョンの依存関係の明示的なバージョンを追加しました
別のパッケージファイル #2137 でデバッグシンボルを生成する機能を追加しました

SqlBulkCopy に新しいプロパティ `RowsCopied64` を追加しました

SqlBulkCopy には、RowsCopied64 値の型をサポートする新しいプロパティ long があります。

既存 SqlBulkCopy.RowsCopied の動作は変更されていないことに注意してください。値が int.MaxValue を超えると、RowsCopied は負の数を返すことがあります。

使用例:

    using (SqlConnection srcConn = new SqlConnection(srcConstr))
    using (SqlCommand srcCmd = new SqlCommand("select top 5 * from employees", srcConn))
    {
        srcConn.Open();
        using (DbDataReader reader = srcCmd.ExecuteReader())
        {
            using (SqlBulkCopy bulkcopy = new SqlBulkCopy(dstConn))
            {
                bulkcopy.DestinationTableName = dstTable;
                SqlBulkCopyColumnMappingCollection ColumnMappings = bulkcopy.ColumnMappings;

                ColumnMappings.Add("EmployeeID", "col1");
                ColumnMappings.Add("LastName", "col2");
                ColumnMappings.Add("FirstName", "col3");

                bulkcopy.WriteToServer(reader);
                long rowsCopied = bulkcopy.RowsCopied64;
            }
        }
    }

SqlConnection に新しいプロパティ `AccessTokenCallBack` を追加しました

SqlConnection は、フェデレーション認証アクセストークンを返す TokenCredential デリゲートとして新しい AccessTokenCallBack プロパティを導入することにより、Func<SqlAuthenticationParameters, CancellationToken,Task<SqlAuthenticationToken>> 認証をサポートします。

使用例:

using Microsoft.Data.SqlClient;
using Azure.Identity;

const string defaultScopeSuffix = "/.default";
string connectionString = GetConnectionString();
DefaultAzureCredential credential = new();
using SqlConnection connection = new(connectionString);

connection.AccessTokenCallback = async (authParams, cancellationToken) =>
{
    string scope = authParams.Resource.EndsWith(defaultScopeSuffix)
        ? authParams.Resource
        : $"{authParams.Resource}{defaultScopeSuffix}";
    AccessToken token = await cred.GetTokenAsync(
        new TokenRequestContext([scope]),
        cancellationToken);

    return new SqlAuthenticationToken(token.Token, token.ExpiresOn);
}

connection.Open();
Console.WriteLine("ServerVersion: {0}", connection.ServerVersion);
Console.WriteLine("State: {0}", connection.State);

SqlBatch API

使用例:

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        string str = "Data Source=(local);Initial Catalog=Northwind;"
        + "Integrated Security=SSPI;Encrypt=False";
        RunBatch(str);
    }

    static void RunBatch(string connString)
    {
        using var connection = new SqlConnection(connString);
        connection.Open();

        var batch = new SqlBatch(connection);

        const int count = 10;
        const string parameterName = "parameter";
        for (int i = 0; i < count; i++)
        {
            var batchCommand = new SqlBatchCommand($"SELECT @{parameterName} as value");
            batchCommand.Parameters.Add(new SqlParameter(parameterName, i));
            batch.BatchCommands.Add(batchCommand);
        }

        // Optionally Prepare
        batch.Prepare();

        var results = new List<int>(count);
        using (SqlDataReader reader = batch.ExecuteReader())
        {
            do
            {
                while (reader.Read())
                {
                    results.Add(reader.GetFieldValue<int>(0));
                }
            } while (reader.NextResult());
        }
        Console.WriteLine(string.Join(", ", results));
    }
}

5.2 の対象プラットフォームサポート

.NET Framework 4.6.2 以降 (Windows x86、Windows x64)
.NET 6.0+ (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 5.2 リリースノートで入手できます。

5.1 での破壊的変更

.NET Core 3.1 のサポートが終了しました。 #1704 #1823

5.1 の新機能

SqlParameter 値と GetFieldValue の DateOnly と TimeOnly のサポートが追加されました。 #1813
.NET Core と SNI Native の TLS 1.3 のサポートが追加されました。 #1821
Encrypt=Mandatory または Encrypt=Strict の ServerCertificate 設定が追加されました。 #1822 詳細情報
.NET Framework をターゲットとする場合の Windows ARM64 のサポートが追加されました。 #1828

サーバー証明書

ServerCertificate 接続設定の既定値は空の文字列です。 Encrypt が Mandatory または Strict に設定されている場合は、ServerCertificate を使用して、サーバーの TLS/SSL 証明書と照合する証明書ファイルへのファイルシステムのパスを指定できます。指定された証明書は、有効なものになるように完全に一致する必要があります。受け入れられる証明書の形式は PEM、DER、CER です。使用例を次に示します。

"Data Source=...;Encrypt=Strict;ServerCertificate=C:\\certificates\\server.cer"

5.1 の対象プラットフォームサポート

.NET Framework 4.6.2 以降 (Windows x86、Windows x64)
.NET 6.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows Azure Resource Manager、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 5.1 リリースノートで入手できます。

Microsoft.Data.SqlClient 5.0 のリリースノート

5.0 における破壊的変更

.NET Framework 4.6.1 のサポートを終了しました #1574
Microsoft.SqlServer.Server パッケージへの依存関係が追加されました。この新しい依存関係は、アプリケーションがその名前空間を参照し、.NET Core. から System.Data.SqlClient へのパッケージ参照 (直接または間接) が残っている場合、名前空間の競合を引き起こす可能性があります。
Microsoft.Data.SqlClient.Server 名前空間からクラスが削除され、Microsoft.SqlServer.Server パッケージからサポートされている型に置き換えられました。#1585。影響を受けるクラスと列挙型は次のとおりです。
- Microsoft.Data.SqlClient.Server.IBinarySerialize -> Microsoft.SqlServer.Server.IBinarySerialize
- Microsoft.Data.SqlClient.Server.InvalidUdtException -> Microsoft.SqlServer.Server.InvalidUdtException
- Microsoft.Data.SqlClient.Server.SqlFacetAttribute -> Microsoft.SqlServer.Server.SqlFacetAttribute
- Microsoft.Data.SqlClient.Server.SqlFunctionAttribute -> Microsoft.SqlServer.Server.SqlFunctionAttribute
- Microsoft.Data.SqlClient.Server.SqlMethodAttribute -> Microsoft.SqlServer.Server.SqlMethodAttribute
- Microsoft.Data.SqlClient.Server.SqlUserDefinedAggregateAttribute -> Microsoft.SqlServer.Server.SqlUserDefinedAggregateAttribute
- Microsoft.Data.SqlClient.Server.SqlUserDefinedTypeAttribute -> Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute
- (列挙型) Microsoft.Data.SqlClient.Server.DataAccessKind -> Microsoft.SqlServer.Server.DataAccessKind
- (列挙型) Microsoft.Data.SqlClient.Server.Format -> Microsoft.SqlServer.Server.Format
- (列挙型) Microsoft.Data.SqlClient.Server.SystemDataAccessKind -> Microsoft.SqlServer.Server.SystemDataAccessKind

5.0 の新機能

TDS8 のサポートが追加されました。 TDS 8 を使う場合、ユーザーは接続文字列で Encrypt=Strict を指定する必要があります。 #1608 詳細情報
接続時にサーバー SPN とフェールオーバーサーバー SPN を指定するためのサポートが追加されました。 #1607 詳細情報
Windows で .NET Core をターゲットにするときに別名のサポートが追加されました。 #1588 詳細情報
SqlDataSourceEnumerator が追加されました。 #1430、詳細情報
安全でない TLS の警告を抑制する、新しい AppContext スイッチが追加されました。 #1457、詳細情報

TDS 8 の強化されたセキュリティ

TDS 8 を使うには、接続文字列で Encrypt=Strict を指定します。厳格モードでは、TrustServerCertificate が無効になります (厳格モードでは常に False として扱われます)。 HostNameInCertificate が追加され、一部の厳格モードのシナリオに役立ちます。 TDS 8 は、すべてのサーバー通信をセキュリティで保護された暗号化 TLS 接続内で開始して継続します。

接続の暗号化の動作を明確にするために、新しい Encrypt 値が追加されました。 Encrypt=Mandatory は Encrypt=True と同等であり、TDS 接続ネゴシエート中に接続を暗号化します。 Encrypt=Optional は Encrypt=False と同等で、サーバーが TDS 接続ネゴシエーション中に暗号化が必要であることをクライアントに伝えた場合のみ、接続を暗号化します。

サーバーへの接続の暗号化について詳しくは、暗号化と証明書の検証に関する記事をご覧ください。

HostNameInCertificate は、クライアントがサーバーを識別するために使う名前 (DNS エイリアスなど) とは異なる名前または代替のサブジェクト名のサーバー証明書を持つサーバーに、エイリアスを使って暗号化して接続する場合に接続文字列で指定できます。使用例: HostNameInCertificate=MyDnsAliasName

サーバー SPN

独特なドメイン/フォレスト構成の環境で接続する場合、サーバー SPN に特定の要件がある場合があります。 ServerSPN (サーバー SPN) と FailoverServerSPN (フェールオーバーサーバー SPN) の接続文字列設定を使うと、ドメイン環境で統合認証の間に使われる自動生成されたサーバー SPN をオーバーライドできます

SQL エイリアスのサポート

ユーザーは、SQL Server 構成マネージャーを使用してエイリアスを構成できます。これらのエイリアスは、Windows レジストリに格納され、.NET Framework をターゲットとする場合は既にサポートされています。このリリースでは、Windows 上の .NET か .NET Core をターゲットとする場合にエイリアスがサポートされます。

SQL データソース列挙子のサポート

ローカルネットワーク内で利用できる SQL Server のすべてのインスタンスを列挙する機構を提供します。

using Microsoft.Data.Sql;
static void Main()  
  {  
    // Retrieve the enumerator instance and then the data.  
    SqlDataSourceEnumerator instance =  
      SqlDataSourceEnumerator.Instance;  
    System.Data.DataTable table = instance.GetDataSources();  
  
    // Display the contents of the table.  
    DisplayData(table);  
  
    Console.WriteLine("Press any key to continue.");  
    Console.ReadKey();  
  }  
  
  private static void DisplayData(System.Data.DataTable table)  
  {  
    foreach (System.Data.DataRow row in table.Rows)  
    {  
      foreach (System.Data.DataColumn col in table.Columns)  
      {  
        Console.WriteLine("{0} = {1}", col.ColumnName, row[col]);  
      }  
      Console.WriteLine("============================");  
    }  
  }

安全でない TLS 警告の抑制

サーバーとのネゴシエートに TLS バージョン 1.2 未満が使われた場合、コンソールにセキュリティ警告が出力されます。アプリケーション起動時に以下の AppContext スイッチを有効にすることで、Encrypt = false の場合 SQL 接続時にこの警告を抑制することができます。

Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning

5.0 の対象プラットフォームサポート

.NET Framework 4.6.2 以降 (Windows x86、Windows x64)
.NET Core 3.1 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 5.0 リリースノートで入手できます。

Microsoft.Data.SqlClient 4.1 のリリースノート

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 4.1 リリースノートで入手できます。

4.1 の新機能

構成証明プロトコル None の導入

None という新しい構成証明プロトコルが接続文字列で許可されます。このプロトコルにより、ユーザーは VBS エンクレーブのエンクレーブ構成証明を使用しないようにできます。このプロトコルが設定されている場合、エンクレーブ構成証明 URL プロパティは省略可能です。

接続文字列の例:

//Attestation protocol NONE with no URL
"Data Source = {server}; Initial Catalog = {db}; Column Encryption Setting = Enabled; Attestation Protocol = None;"

4.1 の対象プラットフォームサポート

.NET Framework 4.6.1 以降 (Windows x86、Windows x64)
.NET Core 3.1 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

Microsoft.Data.SqlClient 4.0 のリリースノート

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 4.0 リリースノートで入手できます。

4.0 における破壊的変更

Encrypt 接続文字列プロパティが既定で true になるように変更しました。 #1210 詳細情報
ドライバーにより、Active Directory 認証モード用に AggregateException を置き換える SqlException がスローされるようになりました。 #1213
古い Asynchronous Processing 接続プロパティを .NET Framework から削除しました。 #1148
Configurable Retry Logic 安全スイッチを削除しました。 #1254 詳細情報
.NET Core 2.1 のサポートを終了しました #1272
[.NET Framework] Active Directory Integrated 認証の使用時に接続文字列でユーザー ID が指定された場合、例外はスローされません #1359

4.0 の新機能

暗号化の既定値を true に設定

Encrypt 接続設定の既定値が false から true に変更されました。クラウドデータベース使用の拡大と、これらの接続が安全であることを確認する必要性のため、この下位互換性の重大な変更が必要になりました。

暗号化が必要なときに接続が失敗するようになりました

クライアント暗号化ライブラリが無効になっているか使用できないシナリオでは、暗号化が true に設定されているか、サーバーに暗号化が必要な場合に、暗号化されていない接続を行うことが可能でした。

システムの既定のプロトコルを使用するためのアプリコンテキストスイッチ

TLS 1.3 はドライバーでサポートされていないため、既定でサポートされているプロトコル一覧から削除されました。ユーザーは、次のアプリコンテキストスイッチを有効にすることで、オペレーティングシステムのクライアントプロトコルの使用の強制に戻すことができます。

Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols

最適化されたパラメーターのバインドを有効にする

Microsoft.Data.SqlClient には、パラメーターの数が多いクエリのパフォーマンスを向上させる新しい SqlCommand API、EnableOptimizedParameterBinding が導入されています。このプロパティは、既定では無効になっています。 true に設定すると、コマンドの実行時に、パラメーター名が SQL Server インスタンスに送信されません。

public class SqlCommand
{
    public bool EnableOptimizedParameterBinding { get; set; }
}

構成可能な再試行ロジックの安全スイッチの削除

構成可能な再試行ロジック機能を使用するのに、アプリコンテキストスイッチ "Switch.Microsoft.Data.SqlClient.EnableRetryLogic" は不要になりました。この機能は、実稼働環境でサポートされるようになりました。この機能の既定の動作は、引き続き再試行なしポリシーであり、再試行を有効にするには、クライアントアプリケーションでオーバーライドする必要があります。

SqlLocalDb 共有インスタンスのサポート

マネージド SNI の使用時に、SqlLocalDb 共有インスタンスがサポートされるようになりました。

考えられるシナリオ:
- (localdb)\. (SqlLocalDb の既定のインスタンスに接続します)
- (localdb)\<named instance>
- (localdb)\.\<shared instance name> (*新しく追加されたサポート)

`XmlReader`、`TextReader`、`Stream` 型の `GetFieldValueAsync<T>` および `GetFieldValue<T>` サポート

XmlReader、TextReader、Stream 型が、GetFieldValueAsync<T> および GetFieldValue<T> の使用時にサポートされるようになりました。

使用例:

using (SqlConnection connection = new SqlConnection(connectionString))
{
    using (SqlCommand command = new SqlCommand(query, connection))
    {
        connection.Open();
        using (SqlDataReader reader = await command.ExecuteReaderAsync())
        {
            if (await reader.ReadAsync())
            {
                using (Stream stream = await reader.GetFieldValueAsync<Stream>(1))
                {
                    // Continue to read from stream
                }
            }
        }
    }
}

4.0 の対象プラットフォームサポート

.NET Framework 4.6.1 以降 (Windows x86、Windows x64)
.NET Core 3.1 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

Microsoft.Data.SqlClient 3.0 のリリースノート

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 3.0 リリースノートで入手できます。

3.0 における破壊的変更

.NET Framework のサポートされる最小バージョンが v4.6.1 に上げられました。 .NET Framework v4.6.0 はサポートされなくなりました。 #899
User Id 接続プロパティで、ユーザー割り当てマネージド ID の Object Id ではなく Client Id が必要になるようになりました #1010 詳細を読む
SqlDataReader では、空の byte[] ではなく DBNull 値が返されるようになりました。従来の動作を有効にするには、AppContext スイッチ Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior を有効にします #998 詳細を読む

3.0 の新機能

構成可能な再試行ロジック

この新機能により、クライアントアプリケーションが "一時的" または "再試行可能" なエラーで再試行するための構成可能なサポートが導入されます。構成は、コードまたはアプリの構成ファイルを使用して行うことができ、再試行操作を適用して接続を開くか、コマンドを実行することができます。この機能は、既定では無効になっており、現在はプレビュー段階です。このサポートを有効にするには、クライアントアプリケーションで次の安全スイッチをオンにする必要があります。

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true);

.NET AppContext スイッチを有効にすると、さまざまなカスタマイズオプションを使用して、SqlConnection および SqlCommand に対し、個別に、またはまとめて、再試行ロジックポリシーを定義できます。

SqlConnection および SqlCommand には、カスタムの SqlRetryLogicBaseProvider 実装を登録するための新しいパブリック API が導入されています。

public SqlConnection
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

public SqlCommand
{
    public SqlRetryLogicBaseProvider RetryLogicProvider;
}

API の使用例を次に示します。

using Microsoft.Data.SqlClient;

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.
class RetryLogicSample
{
    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1)
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report the execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not a good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open the general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is being created and other services are going to connect to it.
            RetryConnection(provider);
        }
        catch
        {
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void RetryConnection(SqlRetryLogicBaseProvider provider)
    {
        // Change this if you already have a database with the same name in your database.
        string dbName = "Invalid_DB_Open";

        // Create a connection to an invalid database.
        using var cnn = new SqlConnection(string.Format(CnnStringFormat, dbName));
        // 3. Assign the `provider` to the connection
        cnn.RetryLogicProvider = provider;
        Console.WriteLine($"Connecting to the [{dbName}] ...");
        // Manually execute the following command in SSMS to create the invalid database while the SqlConnection is attempting to connect to it.
        // >> CREATE DATABASE Invalid_DB_Open;
        Console.WriteLine($"Manually, run the 'CREATE DATABASE {dbName};' in the SQL Server before exceeding the {provider.RetryLogic.NumberOfTries} attempts.");
        // the connection tries to connect to the database 5 times
        Console.WriteLine("The first attempt, before getting into the retry logic.");
        cnn.Open();
        Console.WriteLine($"Connected to the [{dbName}] successfully.");

        cnn.Close();

        // Drop it after test
        ExecuteCommand(s_generalConnection, string.Format(DropDatabaseFormat, dbName));
        Console.WriteLine($"The [{dbName}] is removed.");
    }
}

/// Detecting retriable exceptions is a vital part of the retry pattern.
/// Before applying retry logic it is important to investigate exceptions and choose a retry provider that best fits your scenario.
/// First, log your exceptions and find transient faults.
/// The purpose of this sample is to illustrate how to use this feature and the condition might not be realistic.

    private const string DefaultDB = "Northwind";
    private const string CnnStringFormat = "Server=localhost; Initial Catalog={0}; Integrated Security=true; pooling=false;";
    private const string DropDatabaseFormat = "DROP DATABASE {0}";
    private const string CreateDatabaseFormat = "CREATE DATABASE {0}";

    // For general use
    private static SqlConnection s_generalConnection = new SqlConnection(string.Format(CnnStringFormat, DefaultDB));

    static void Main(string[] args)
    {
        // 1. Define the retry logic parameters
        var options = new SqlRetryLogicOption()
        {
            NumberOfTries = 5,
            MaxTimeInterval = TimeSpan.FromSeconds(20),
            DeltaTime = TimeSpan.FromSeconds(1),
            AuthorizedSqlCondition = null,
            // error number 3702 : Cannot drop database "xxx" because it is currently in use.
            TransientErrors = new int[] {3702}
        };

        // 2. Create a retry provider
        var provider = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(options);

        // define the retrying event to report execution attempts
        provider.Retrying += (object s, SqlRetryingEventArgs e) =>
            {
                int attempts = e.RetryCount + 1;
                Console.ForegroundColor = ConsoleColor.Yellow;
                Console.WriteLine($"attempt {attempts} - current delay time:{e.Delay} \n");
                Console.ForegroundColor = ConsoleColor.DarkGray;
                if (e.Exceptions[e.Exceptions.Count - 1] is SqlException ex)
                {
                    Console.WriteLine($"{ex.Number}-{ex.Message}\n");
                }
                else
                {
                    Console.WriteLine($"{e.Exceptions[e.Exceptions.Count - 1].Message}\n");
                }

                // It is not good practice to do time-consuming tasks inside the retrying event which blocks the running task.
                // Use parallel programming patterns to mitigate it.
                if (e.RetryCount == provider.RetryLogic.NumberOfTries - 1)
                {
                    Console.WriteLine("This is the last chance to execute the command before throwing the exception.");
                    Console.WriteLine("Press Enter when you're ready:");
                    Console.ReadLine();
                    Console.WriteLine("continue ...");
                }
            };

        // Open a general connection.
        s_generalConnection.Open();

        try
        {
            // Assume the database is creating and other services are going to connect to it.
            RetryCommand(provider);
        }
        catch
        {
            s_generalConnection.Close();
            // exception is thrown if connecting to the database isn't successful.
            throw;
        }
        s_generalConnection.Close();
    }

    private static void ExecuteCommand(SqlConnection cn, string command)
    {
        using var cmd = cn.CreateCommand();
        cmd.CommandText = command;
        cmd.ExecuteNonQuery();
    }

    private static void FindActiveSessions(SqlConnection cnn, string dbName)
    {
        using var cmd = cnn.CreateCommand();
        cmd.CommandText = "DECLARE @query NVARCHAR(max) = '';" + Environment.NewLine +
            $"SELECT @query = @query + 'KILL ' + CAST(spid as varchar(50)) + ';' FROM sys.sysprocesses WHERE dbid = DB_ID('{dbName}')" + Environment.NewLine +
            "SELECT @query AS Active_sessions;";
        var reader = cmd.ExecuteReader();
        if (reader.Read())
        {
            Console.ForegroundColor = ConsoleColor.Green;
            Console.Write($">> Execute the '{reader.GetString(0)}' command in SQL Server to unblock the running task.");
            Console.ResetColor();
        }
        reader.Close();
    }

var RetryLogicOption = new SqlRetryLogicOption()
{
    NumberOfTries = 5,
    // Declare the error number 102 as a transient error to apply the retry logic when it occurs.
    TransientErrors = new int[] { 102 },
    // When a SqlCommand executes out of a transaction, 
    // the retry logic will apply if it contains a 'select' keyword.
    AuthorizedSqlCondition = x => string.IsNullOrEmpty(x)
            || Regex.IsMatch(x, @"\b(SELECT)\b", RegexOptions.IgnoreCase),
    DeltaTime = TimeSpan.FromSeconds(1),
    MaxTimeInterval = TimeSpan.FromSeconds(60),
    MinTimeInterval = TimeSpan.FromSeconds(3)
};

構成ファイルから同じ登録を行うための新しい構成セクションも導入されました。既存のコードを変更する必要はありません。

<section name="SqlConfigurableRetryLogicConnection"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>

<section name="SqlConfigurableRetryLogicCommand"
            type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

構成ファイル内の新しい構成セクションの簡単な使用例を次に示します。

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="SqlConfigurableRetryLogicConnection"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryConnectionSection, Microsoft.Data.SqlClient"/>
    <section name="SqlConfigurableRetryLogicCommand"
             type="Microsoft.Data.SqlClient.SqlConfigurableRetryCommandSection, Microsoft.Data.SqlClient"/>

    <section name="AppContextSwitchOverrides"
             type="Microsoft.Data.SqlClient.AppContextSwitchOverridesSection, Microsoft.Data.SqlClient"/>
  </configSections>

  <!--Enable safety switch in .NET Core-->
  <AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableRetryLogic=true"/>

  <!--Retry method for SqlConnection-->
  <SqlConfigurableRetryLogicConnection retryMethod ="CreateFixedRetryProvider" numberOfTries ="3" deltaTime ="00:00:10" maxTime ="00:00:30"
                                    transientErrors="40615" />

  <!--Retry method for SqlCommand containing SELECT queries-->
  <SqlConfigurableRetryLogicCommand retryMethod ="CreateIncrementalRetryProvider" numberOfTries ="5" deltaTime ="00:00:10" maxTime ="00:01:10"
                                    authorizedSqlCondition="\b(SELECT)\b" transientErrors="102, 4060, 0"/>
</configuration>

または、アプリケーションで SqlRetryLogicBaseProvider 基底クラスの独自のプロバイダーを実装し、それを SqlConnection/SqlCommand に登録します。

イベントカウンター

.NET Core 3.1 以上および .NET Standard 2.1 以上を対象とするアプリケーションでは、次のカウンターを使用できるようになりました。

名前	Display name	説明
active-hard-connections	サーバーに対する現在の実際のアクティブな接続	データベースサーバーに対して現在開かれている接続の数。
hard-connects	サーバーに対する実際の接続速度	データベースサーバーに対して開かれている 1 秒あたりの接続の数。
hard-disconnects	サーバーからの実際の切断速度	データベースサーバーに対して行われる 1 秒あたりの切断の数。
active-soft-connects	接続プールから取得されたアクティブな接続	接続プールから消費される既に開かれている接続の数。
soft-connects	接続プールから取得された接続の速度	接続プールから消費される 1 秒あたりの接続の数。
soft-disconnects	接続プールに返される接続の速度	接続プールに返される 1 秒あたりの接続の数。
number-of-non-pooled-connections	接続プーリングを使用しない接続の数	プールされていないアクティブな接続の数。
number-of-pooled-connections	接続プールによって管理されている接続の数	接続プールインフラストラクチャによって管理されているアクティブな接続の数。
number-of-active-connection-pool-groups	アクティブな一意の接続文字列の数	アクティブな一意の接続プールグループの数。このカウンターは、AppDomain で見つかった一意の接続文字列の数に基づいています。
number-of-inactive-connection-pool-groups	切断待ちの一意な接続文字列の数	排除対象としてマークされた一意の接続プールグループの数。このカウンターは、AppDomain で見つかった一意の接続文字列の数に基づいています。
number-of-active-connection-pools	アクティブな接続プールの数	接続プールの合計数。
number-of-inactive-connection-pools	非アクティブな接続プールの数	アクティビティが最近なく、破棄されるのを待っている、非アクティブな接続プールの数。
number-of-active-connections	アクティブな接続の数	現在使用中のアクティブな接続の数。
number-of-free-connections	接続プール内の準備完了接続の数	接続プール内の開いている利用可能な接続の数。
number-of-stasis-connections	現在準備完了待ち状態の接続の数	現在アクションの完了待ち状態で、アプリケーションで使用できない接続の数。
number-of-reclaimed-connections	GC から回収された接続の数	アプリケーションによって `Close` または `Dispose` が呼び出されず、ガベージコレクションによって回収された接続の数。注明示的に終了または破棄しないと、パフォーマンスに悪影響を及ぼします。

これらのカウンターは、プロバイダー名として Microsoft.Data.SqlClient.EventSource を使用して、.NET Core グローバル CLI ツール (Windows または Linux の dotnet-counters および dotnet-trace) と Windows の PerfView で使用できます。詳細については、「イベントカウンター値を取得する」を参照してください。

dotnet-counters monitor Microsoft.Data.SqlClient.EventSource -p
PerfView /onlyProviders=*Microsoft.Data.SqlClient.EventSource:EventCounterIntervalSec=1 collect

Azure Identity の依存関係の導入

Microsoft.Data.SqlClient は、Azure.Identity ライブラリに依存して、"Active Directory マネージド ID/MSI" および "Active Directory サービスプリンシパル" 認証モードのトークンを取得するようになりました。この変更により、パブリック公開領域に対して次の変更が加えられます。

破壊的変更
"User Id" 接続プロパティで、"ユーザー割り当てマネージド ID" の "Object Id" ではなく "Client Id" が必要になるようになりました。
パブリック API
新しい読み取り専用パブリックプロパティ: SqlAuthenticationParameters.ConnectionTimeout
依存関係
Azure.Identity v1.3.0

SNI.dll 内のイベントトレースの実装

Microsoft.Data.SqlClient.SNI (.NET Framework 依存関係) および Microsoft.Data.SqlClient.SNI.runtime (.NET Core/Standard 依存関係) のバージョンは、v3.0.0-preview1.21104.2 に更新されました。 SNI.dll でのイベントトレースは、クライアントアプリケーションからは有効にされなくなりました。 xperf や perfview などのツールを使って Microsoft.Data.SqlClient.EventSource プロバイダーへのセッションをサブスクライブするだけで十分です。詳細については、「ネイティブ SNI でのイベントトレースのサポート」を参照してください。

行バージョンの null 動作の有効化

SqlDataReader では、空の byte[] ではなく DBNull 値を返します。従来の動作を有効にするには、アプリケーションの起動時に、AppContext スイッチ "Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior" を有効にする必要があります。

Microsoft Entra のデフォルトの認証では次のことをサポートしています。

Note

Microsoft Entra ID はAzure Active Directory (Azure AD) の新しい名前ですが、既存の環境の中断を防ぐために、UI フィールド、接続プロバイダー、エラーコード、コマンドレットなど、ハードコーディングされた一部の要素でAzure AD が残ります。この記事では、2 つの名前は交換可能です。

今回の PR では、新しい SQL 認証方法である Active Directory Default が導入されています。この認証モードにより、Microsoft Entra ID によるユーザー認証の可能性が広がり、ログインソリューションがクライアント環境、Visual Studio Code、Visual Studio、Azure CLI などに拡張されます。

この認証モードを使用すると、ドライバーでは、Azure Identity ライブラリから "DefaultAzureCredential" を渡してアクセストークンを取得することによってトークンを取得します。このモードでは、次の種類の資格情報を使用して、以下の順序でアクセストークンの取得を試みます。

EnvironmentCredential
- クライアントとシークレット、またはユーザー名とパスワード、環境変数 AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET、AZURE_CLIENT_CERTIFICATE_PATH、AZURE_USERNAME、AZURE_PASSWORD で構成された詳細を使用して、Microsoft Entra ID への認証を有効にします (詳細)
ManagedIdentityCredential
- デプロイ環境に割り当てられているマネージド ID を使用して、Microsoft Entra ID への認証を試みます。 "ユーザー割り当てマネージド ID" の "クライアント ID" は、 "ユーザー ID" 接続プロパティから読み取られます。
SharedTokenCacheCredential
- Microsoft アプリケーション間で共有されるローカルキャッシュ内のトークンを使用して認証を行います。
VisualStudioCredential
- Visual Studio からのデータを使用して Microsoft Entra ID による認証を有効化する
VisualStudioCodeCredential
- Visual Studio Code からのデータを使用して Microsoft Entra ID による認証を有効化します。
AzureCliCredential
- Azure CLI を使用して Microsoft Entra ID による認証を有効にして、アクセストークンを取得します。

"Active Directory Default" のドライバー実装では、InteractiveBrowserCredential は無効になっています。また、"Active Directory Interactive" は、MFA/Interactive 認証を使用してトークンを取得するために使用できる唯一のオプションです。

現在、その他のカスタマイズオプションは使用できません。

カスタムマスターキーストアプロバイダー登録の機能強化

Microsoft.Data.SqlClient では、マルチテナントアプリケーションと、これによる列暗号化および暗号化解除の使用をより適切にサポートするために、アプリケーション内でマスターキーストアプロバイダーにアクセスできる場所をより細かく制御できるようになりました。 SqlConnection および SqlCommand のインスタンスでカスタムマスターキーストアプロバイダーを登録できるようにするために、次の API が導入されました。

public class SqlConnection
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnConnection(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}
public class SqlCommand 
{
    public void RegisterColumnEncryptionKeyStoreProvidersOnCommand(IDictionary<string, SqlColumnEncryptionKeyStoreProvider> customProviders)
}

カスタムマスターキーストアプロバイダーをグローバルに登録するために使われる SqlConnection の静的 API SqlConnection.RegisterColumnEncryptionKeyStoreProviders は引き続きサポートされます。グローバルに保持される列暗号化キーキャッシュは、グローバルに登録されたプロバイダーにのみ適用されます。

列マスターキーストアプロバイダー登録の優先順位

Windows Certificate Store、CNG Store、CSP に使用できる組み込みの列マスターキーストアプロバイダーは、事前登録されています。組み込みの列マスターキーストアプロバイダーのいずれかが必要な場合、接続またはコマンドインスタンスでプロバイダーを登録する必要はありません。

カスタムマスターキーストアプロバイダーは、3 つの異なるレイヤーでドライバーに登録できます。グローバルレベルは現在のままです。接続ごとおよびコマンドごとのレベルの新しい登録は、最初は空であり、複数回設定できます。

3 つの登録の優先順位は次のとおりです。

コマンドごとの登録が空でないかどうか確認されます。
コマンドごとの登録が空の場合、接続ごとの登録が空でないかどうか確認されます。
接続ごとの登録が空の場合、グローバル登録が確認されます。

登録レベルでキーストアプロバイダーが見つかると、ドライバーはプロバイダーを検索するために他の登録にフォールバックしません。プロバイダーが登録されていても、適切なプロバイダーがあるレベルで見つからない場合、確認された登録内に登録されているプロバイダーのみを含む例外がスローされます。

列暗号化キーキャッシュの優先順位

新しいインスタンスレベルの API を使って登録されたカスタムキーストアプロバイダーの列暗号化キー (CEK) は、ドライバーによってキャッシュされません。キーストアプロバイダーは、パフォーマンスを向上させるために独自のキャッシュを実装する必要があります。キーストアプロバイダーインスタンスがグローバルレベルでドライバーに登録されている場合、カスタムキーストアプロバイダーによって実装される列暗号化キーのローカルキャッシュは、ドライバーによって無効にされます。

さらに、SqlColumnEncryptionKeyStoreProvider 基底クラスには、キャッシュの有効期間を設定するための新しい API が導入されました。

public abstract class SqlColumnEncryptionKeyStoreProvider
{
    // The default value of Column Encryption Key Cache Time to Live is 0.
    // Provider's local cache is disabled for globally registered providers.
    // Custom key store provider implementation must include column encryption key cache to provide caching support to locally registered providers.
    public virtual TimeSpan? ColumnEncryptionKeyCacheTtl { get; set; } = new TimeSpan(0);
}

IP アドレスの優先順位

TCP 接続を確立するときにドライバーに対して IP アドレスファミリの優先順位を指定するために、新しい接続プロパティ IPAddressPreference が導入されました。 Transparent Network IP Resolution (.NET Framework 内) または Multi Subnet Failover が trueに設定されている場合、この設定は機能しません。このプロパティでは次の 3 つの値が許容されます。

IPv4First
- これが既定値です。ドライバーでは、解決された IPv4 アドレスが最初に使われます。それらのいずれも正常に接続できない場合、解決された IPv6 アドレスが試されます。
IPv6First
- ドライバーは、解決された IPv6 アドレスを最初に使います。それらのいずれでも接続できない場合は、解決された IPv4 アドレスを試します。
UsePlatformDefault
- ドライバーは、DNS 解決応答から受信した順序で IP アドレスを試します。

3.0 の対象プラットフォームサポート

.NET Framework 4.6.1 以降 (Windows x86、Windows x64)
.NET Core 2.1 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

Microsoft.Data.SqlClient 2.1 のリリースノート

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 2.1 リリースノートで入手できます。

2.1 の新機能

Always Encrypted でのクロスプラットフォームのサポート

Microsoft.Data.SqlClient v2.1 での拡張により、次のプラットフォームで Always Encrypted がサポートされるようになります。

Always Encrypted のサポート	セキュリティで保護されたエンクレーブを使用する Always Encrypted のサポート	[対象とする Framework]	Microsoft.Data.SqlClient のバージョン	オペレーティングシステム
はい	はい	.NET Framework 4.6+	1.1.0 以降	Windows
はい	はい	.NET Core 2.1 以降	2.1.0 以降¹	Windows、Linux、macOS
はい	いいえ²	.NET Standard 2.0	2.1.0 以降	Windows、Linux、macOS
はい	はい	.NET Standard 2.1 以降	2.1.0 以降	Windows、Linux、macOS

Note

¹ v2.1 より前のバージョンの Microsoft.Data.SqlClient では、Always Encrypted は Windows でのみサポートされています。 ² セキュリティで保護されたエンクレーブを使用する Always Encrypted は、.NET Standard 2.0 ではサポートされていません。

Microsoft Entra デバイスコードフロー認証

Microsoft.Data.SqlClient v2.1 では、MSAL.NET での "デバイスコードフロー" 認証がサポートされています。リファレンスドキュメント:OAuth 2.0 デバイス許可付与フローに関するページ

接続文字列の例:

Server=<server>.database.windows.net; Authentication=Active Directory Device Code Flow; Database=Northwind;Encrypt=True

次の API を使用すると、デバイスコードフローのコールバックメカニズムをカスタマイズできます。

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetDeviceCodeFlowCallback(Func<DeviceCodeResult, Task> deviceCodeFlowCallbackMethod)
}

Microsoft Entra マネージド ID 認証

マネージド ID を使用する Microsoft Entra 認証のサポートが、Microsoft.Data.SqlClient v2.1 で導入されています。

次の認証モードキーワードがサポートされています。

Active Directory Managed Identity
Active Directory MSI (クロス MS SQL ドライバーの互換性の場合)

接続文字列の例:

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; Initial Catalog={db};"

// For System Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory MSI; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

// For User Assigned Managed Identity
"Server={serverURL}; Authentication=Active Directory Managed Identity; Encrypt=True; User Id={ObjectIdOfManagedIdentity}; Initial Catalog={db};"

Microsoft Entra 対話型認証の機能強化

Microsoft.Data.SqlClient v2.1 で追加された次の API を使用すると、Microsoft Entra 対話型 認証のエクスペリエンスをカスタマイズできます。

public class ActiveDirectoryAuthenticationProvider
{
    // For .NET Framework targeted applications only
    public void SetIWin32WindowFunc(Func<IWin32Window> iWin32WindowFunc);

    // For .NET Standard targeted applications only
    public void SetParentActivityOrWindowFunc(Func<object> parentActivityOrWindowFunc);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void SetAcquireAuthorizationCodeAsyncCallback(Func<Uri, Uri, CancellationToken, Task<Uri>> acquireAuthorizationCodeAsyncCallback);

    // For .NET Framework, .NET Core and .NET Standard targeted applications
    public void ClearUserTokenCache();
}

`SqlClientAuthenticationProviders` 構成セクション

Microsoft.Data.SqlClient v2.1 には、新しい構成セクション SqlClientAuthenticationProviders が導入されています (既存の SqlAuthenticationProviders の複製)。既存の構成セクション SqlAuthenticationProviders は、適切な型が定義されているときの下位互換性のために引き続きサポートされます。

新しいセクションを使用すると、アプリケーション構成ファイルに、System.Data.SqlClient 用の SqlAuthenticationProviders セクションと、Microsoft.Data.SqlClient 用の SqlClientAuthenticationProviders セクションの両方を含めることができます。

アプリケーションクライアント ID を使用した Microsoft Entra 認証

Microsoft.Data.SqlClient v2.1 には、ユーザー定義のアプリケーションクライアント ID を Microsoft 認証ライブラリに渡すためのサポートが導入されています。アプリケーションクライアント ID は、Microsoft Entra ID で認証するときに使用されます。

次の新しい API が導入されています。

新しいコンストラクターが ActiveDirectoryAuthenticationProvider に導入されました。
[すべての .NET プラットフォーム (.NET Framework、.NET Core、.NET Standard) に適用されます]

public ActiveDirectoryAuthenticationProvider(string applicationClientId)

用途:

string APP_CLIENT_ID = "<GUID>";
SqlAuthenticationProvider customAuthProvider = new ActiveDirectoryAuthenticationProvider(APP_CLIENT_ID);
SqlAuthenticationProvider.SetProvider(SqlAuthenticationMethod.ActiveDirectoryInteractive, customAuthProvider);

using (SqlConnection sqlConnection = new SqlConnection("<connection_string>")
{
    sqlConnection.Open();
}

SqlAuthenticationProviderConfigurationSection と SqlClientAuthenticationProviderConfigurationSection に新しい構成プロパティが導入されました。
[.NET Framework と .NET Core に適用されます]

internal class SqlAuthenticationProviderConfigurationSection : ConfigurationSection
{
    ...
    [ConfigurationProperty("applicationClientId", IsRequired = false)]
    public string ApplicationClientId => this["applicationClientId"] as string;
}

// Inheritance
internal class SqlClientAuthenticationProviderConfigurationSection : SqlAuthenticationProviderConfigurationSection
{ ... }

用途:

<configuration>
    <configSections>
        <section name="SqlClientAuthenticationProviders"
                         type="Microsoft.Data.SqlClient.SqlClientAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
    </configSections>
    <SqlClientAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

<!--or-->

<configuration>
    <configSections>
        <section name="SqlAuthenticationProviders"
                         type="Microsoft.Data.SqlClient.SqlAuthenticationProviderConfigurationSection, Microsoft.Data.SqlClient" />
    </configSections>
    <SqlAuthenticationProviders applicationClientId ="<GUID>" />
</configuration>

データ分類 v2 のサポート

Microsoft.Data.SqlClient v2.1 には、データ分類の "秘密度ランク" 情報のサポートが導入されています。次の新しい API を使用できるようになりました。

public class SensitivityClassification
{
    public SensitivityRank SensitivityRank;
}

public class SensitivityProperty
{
    public SensitivityRank SensitivityRank;
}

public enum SensitivityRank
{
    NOT_DEFINED = -1,
    NONE = 0,
    LOW = 10,
    MEDIUM = 20,
    HIGH = 30,
    CRITICAL = 40
}

アクティブな `SqlConnection` のサーバープロセス ID

Microsoft.Data.SqlClient v2.1 には、アクティブな接続での新しい SqlConnection プロパティ ServerProcessId が導入されています。

public class SqlConnection
{
    // Returns the server process Id (SPID) of the active connection.
    public int ServerProcessId;
}

ネイティブ SNI でのトレースログのサポート

Microsoft.Data.SqlClient v2.1 では、SNI.dll でイベントのトレースを使用できるように、既存の SqlClientEventSource の実装が拡張されています。イベントは、Xperf などのツールを使用してキャプチャする必要があります。

次に示すように SqlClientEventSource にコマンドを送信することでトレースを有効にできます。

// Enables trace events:
EventSource.SendCommand(eventSource, (EventCommand)8192, null);

// Enables flow events:
EventSource.SendCommand(eventSource, (EventCommand)16384, null);

// Enables both trace and flow events:
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);

"Command Timeout" 接続文字列プロパティ

Microsoft.Data.SqlClient v2.1 で導入された "Command Timeout" 接続文字列プロパティを使用すると、既定の 30 秒をオーバーライドできます。個々のコマンドのタイムアウトは、SqlCommand の CommandTimeout プロパティを使用してオーバーライドできます。

接続文字列の例:

"Server={serverURL}; Initial Catalog={db}; Encrypt=True; Integrated Security=true; Command Timeout=60"

ネイティブ SNI からのシンボルの削除

Microsoft.Data.SqlClient v2.1 では、v2.0.0 で導入されたシンボルが、Microsoft.Data.SqlClient.SNI.runtime NuGet の v2.1.1 以降から削除されます。パブリックシンボルにアクセスする必要がある BinSkim などのツールのために、パブリックシンボルが Microsoft シンボルサーバーに発行されるようになります。

Microsoft.Data.SqlClient のシンボルのソースリンク

Microsoft.Data.SqlClient v2.1 以降、ソースコードをダウンロードする必要のない、強化されたデバッグエクスペリエンスのため、Microsoft.Data.SqlClient のシンボルが Microsoft シンボルサーバーにソースリンクされて発行されます。

2.1 の対象プラットフォームサポート

.NET Framework 4.6 以降 (Windows x86、Windows x64)
.NET Core 2.1 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

Microsoft.Data.SqlClient 2.0 のリリースノート

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 2.0 リリースノートで入手できます。

2.0 における重大な変更

エンクレーブプロバイダーインターフェイス SqlColumnEncryptionEnclaveProvider のアクセス修飾子が public から internal に変更されました。
SqlClientMetaDataCollectionNames クラスの定数は、SQL Server の変更を反映するように更新されました。
ターゲット SQL Server で TLS 暗号化が適用されている場合、ドライバーによってサーバー証明書の検証が実行されるようになりました。これは、Azure の接続では既定です。
SqlDataReader.GetSchemaTable() から、null ではなく空の DataTable が返されるようになりました。
ドライバーによる小数点以下桁数の丸めの実行が、SQL Server の動作に一致するようになりました。下位互換性を維持するために、AppContext スイッチを使用して以前の切り捨ての動作を有効にすることができます。
Microsoft.Data.SqlClient を使用する .NET Framework アプリケーションの場合、以前は bin\x64 と bin\x86 フォルダーにダウンロードされた SNI.dll ファイルは、Microsoft.Data.SqlClient.SNI.x64.dll と Microsoft.Data.SqlClient.SNI.x86.dll という名前になり、bin ディレクトリにダウンロードされます。
SqlConnectionStringBuilder から接続文字列をフェッチするとき、一貫性を保つために、古いプロパティは新しい接続文字列プロパティのシノニムによって置き換えられます。詳細

2.0 の新機能

次の新機能は、Microsoft.Data.SqlClient 2.0 で導入されました。

DNS エラーの回復性

この機能をサポートする SQL Server エンドポイントへの接続が成功するたびに、ドライバーは IP アドレスをキャッシュします。接続を試みている間に DNS 解決のエラーが発生した場合、ドライバーは、そのサーバーに対してキャッシュされた IP アドレス (存在する場合) を使って、接続の確立を試みます。

EventSource の追跡

このリリースでは、アプリケーションをデバッグするためのイベントトレースログのキャプチャに対するサポートが導入されています。これらのイベントをキャプチャするには、クライアントアプリケーションで SqlClient の EventSource 実装からのイベントをリッスンする必要があります。

Microsoft.Data.SqlClient.EventSource

詳細については、SqlClient でイベントのトレースを有効にする方法を参照してください。

Windows でのマネージドネットワークの有効化

新しい AppContext スイッチ "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows" によって、Windows 上でテストおよびデバッグの目的のためにマネージド SNI 実装を使用できるようになります。このスイッチを使うと、Windows 上の .NET Core 2.1 以降および .NET Standard 2.0 以降のプロジェクトではマネージド SNI を使うようにドライバーの動作が切り替わり、ネイティブライブラリでの Microsoft.Data.SqlClient ライブラリに対するすべての依存関係がなくなります。

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

ドライバーで使用できるスイッチの完全な一覧については、「SqlClient の AppContext スイッチ」を参照してください。

小数点の切り捨て動作の有効化

ドライバーは、SQL Server と同じように、データの小数点以下を既定で丸めます。下位互換性を維持するために、AppContext スイッチ "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" を true に設定できます。

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

新しい接続文字列プロパティのシノニム

次の既存の接続文字列プロパティに対して新しいシノニムが追加されました。これにより、複数の単語を使用しているプロパティのスペースあけの混乱を回避できます。以前のプロパティ名は、下位互換性のために引き続きサポートされます。ただし、SqlConnectionStringBuilder から接続文字列をフェッチするときは、新しい接続文字列プロパティが含まれるようになりました。

既存の接続文字列プロパティ	新しいシノニム
ApplicationIntent	アプリケーションの目的
ConnectRetryCount	Connect Retry Count
ConnectRetryInterval	Connect Retry Interval
PoolBlockingPeriod	Pool Blocking Period
MultipleActiveResultSets	Multiple Active Result Sets
MultiSubnetFailover	Multiple Subnet Failover
TransparentNetworkIPResolution	Transparent Network IP Resolution
TrustServerCertificate	[Trust Server Certificate]

SqlBulkCopy RowsCopied プロパティ

RowsCopied プロパティを使用すると、実行中の一括コピー操作で処理された行の数に読み取り専用でアクセスできます。この値は、必ずしもターゲットテーブルに追加された行の最終的な数と同じになるとは限りません。

接続オープンのオーバーライド

SqlConnection.Open() の既定の動作をオーバーライドして、一時的なエラーによってトリガーされる 10 秒の遅延と自動接続の再試行を無効にすることができます。

using SqlConnection sqlConnection = new SqlConnection("Data Source=(local);Integrated Security=true;Initial Catalog=AdventureWorks;");
sqlConnection.Open(SqlConnectionOverrides.OpenWithoutRetry);

注意

このオーバーライドは、SqlConnection.Open() にのみ適用でき、SqlConnection.OpenAsync() には適用できないことにご注意ください。

Active Directory 対話モードでのユーザー名のサポート

.NET Framework と .NET Core の両方に対して Microsoft Entra 対話型認証モードを使用する場合は、接続文字列にユーザー名を指定できます。

ユーザー ID または UID 接続文字列プロパティを使用してユーザー名を設定します。

"Server=<server name>; Database=<db name>; Authentication=Active Directory Interactive; User Id=<username>;Encrypt=True;"

SqlBulkCopy の順序のヒント

クラスター化インデックスを持つテーブルに対する一括コピー操作のパフォーマンスを向上させるために、順序のヒントを指定できます。詳細については、「の一括コピー操作」セクションを参照してください。

SNI 依存関係の変更

Windows 上の Microsoft.Data.SqlClient (.NET Core および .NET Standard) は、Microsoft.Data.SqlClient.SNI.runtime に依存するようになりました。これにより、runtime.native.System.Data.SqlClient.SNI に対する以前の依存関係が置き換えられます。新しい依存関係によって、Windows で既にサポートされているプラットフォームである ARM64、x64、x86 に加えて、ARM プラットフォームのサポートが追加されます。

2.0 の対象プラットフォームサポート

.NET Framework 4.6 以降 (Windows x86、Windows x64)
.NET Core 2.1 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Windows ARM64、Windows ARM、Linux、macOS)

Microsoft.Data.SqlClient 1.1.0 のリリースノート

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 1.1 リリースノートで入手できます。

1.1 の新機能

セキュアエンクレーブを使用する Always Encrypted

Always Encrypted は、Microsoft SQL Server 2016 から使用できます。セキュリティで保護されたエンクレーブは、Microsoft SQL Server 2019 から使用できます。エンクレーブ機能を使用するには、必要な構成証明プロトコルと構成証明 URL が接続文字列に含まれている必要があります。次に例を示します。

"Attestation Protocol=HGS;Enclave Attestation Url=<attestation_url_for_HGS>"

詳細については、次を参照してください。

1.1 の対象プラットフォームサポート

.NET Framework 4.6 以降 (Windows x86、Windows x64)
.NET Core 2.1 以降 (Windows x86、Windows x64、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Linux、macOS)

Microsoft.Data.SqlClient 1.0 のリリースノート

Microsoft.Data.SqlClient 名前空間の最初のリリースでは、既存の System.Data.SqlClient 名前空間よりも多くの機能が提供されています。

依存関係を含む完全なリリースノートは、GitHub リポジトリ: 1.0 リリースノートで入手できます。

1.0 の新機能

.NET Framework 4.7.2 System.Data.SqlClient に対する新機能

データ分類 - Azure SQL Database および Microsoft SQL Server 2019 で使用できます。
UTF-8 のサポート - Microsoft SQL Server 2019 で使用できます。

.NET Core 2.2 System.Data.SqlClient に対する新機能

データ分類 - Azure SQL Database および Microsoft SQL Server 2019 で使用できます。
UTF-8 のサポート - Microsoft SQL Server 2019 で使用できます。
認証 - Active Directory パスワード認証モード。

データ分類

データ分類では、基になるソースでこの機能がサポートされ、データの機密性と分類に関するメタデータが含まれている場合に、SqlDataReader 経由で取得したオブジェクトに関するデータの機密性と分類に関する読み取り専用の情報を公開する新しい一連の API が提供されます。「SqlClient でのデータ検出と分類」にあるサンプルアプリケーションを参照してください。

public class SqlDataReader
{
    public Microsoft.Data.SqlClient.DataClassification.SensitivityClassification SensitivityClassification
}

namespace Microsoft.Data.SqlClient.DataClassification
{
    public class ColumnSensitivity
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.SensitivityProperty> SensitivityProperties
    }
    public class InformationType
    {
        public string Id
        public string Name
    }
    public class Label
    {
        public string Id
        public string Name
    }
    public class SensitivityClassification
    {
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.ColumnSensitivity> ColumnSensitivities
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.InformationType> InformationTypes
        public System.Collections.ObjectModel.ReadOnlyCollection<Microsoft.Data.SqlClient.DataClassification.Label> Labels
    }
    public class SensitivityProperty
    {
        public Microsoft.Data.SqlClient.DataClassification.InformationType InformationType
        public Microsoft.Data.SqlClient.DataClassification.Label Label
    }
}

UTF-8 のサポート

UTF-8 のサポートで、アプリケーションコードを変更する必要はありません。これらの SqlClient の変更によって、サーバーで UTF-8 がサポートされ、基になる列の照合順序が UTF-8 である場合に、クライアントとサーバーの間の通信が最適化されます。 SQL Server 2019 の新機能の UTF-8 のセクションを参照してください。

セキュリティで保護されたエンクレーブが設定された Always Encrypted:

一般に、.NET Framework で System.Data.SqlClient および組み込み列マスターキーストアプロバイダーを使用する既存のドキュメントも .NET Core で動作するようになりました。

Always Encrypted と .NET Framework Data Provider を使用して開発する

Always Encrypted:Windows 証明書ストアで機密データを保護し、暗号化キーを格納する

認証

[認証] 接続文字列オプションを使用して、さまざまな認証モードを指定できます。詳細については、SqlAuthenticationMethod のドキュメントを参照してください。

注意

Azure Key Vault プロバイダーなどのカスタムキーストアプロバイダーは、Microsoft.Data.SqlClient をサポートするように更新する必要があります。同様に、エンクレーブプロバイダーも Microsoft.Data.SqlClient をサポートするように更新する必要があります。 Always Encrypted は、.NET Framework および .NET Core ターゲットに対してのみサポートされます。 .NET Standard には特定の暗号化依存関係がないため、.NET Standard に対してはサポートされません。

1.0 の対象プラットフォームサポート

.NET Framework 4.6 以降 (Windows x86、Windows x64)
.NET Core 2.1 以降 (Windows x86、Windows x64、Linux、macOS)
.NET Standard 2.0 以降 (Windows x86、Windows x64、Linux、macOS)

次の方法で共有

Microsoft.Data.SqlClient 名前空間の概要

API リファレンス

Microsoft.Data.SqlClient 5.2 のリリース ノート

5.2 の新機能

SqlBulkCopy に新しいプロパティ RowsCopied64 を追加しました

SqlConnection に新しいプロパティ AccessTokenCallBack を追加しました

SqlBatch API

5.2 の対象プラットフォーム サポート

5.1 での破壊的変更

5.1 の新機能

サーバー証明書

5.1 の対象プラットフォーム サポート

Microsoft.Data.SqlClient 5.0 のリリース ノート

5.0 における破壊的変更

5.0 の新機能

TDS 8 の強化されたセキュリティ

サーバー SPN

SQL エイリアスのサポート

SQL データ ソース列挙子のサポート

安全でない TLS 警告の抑制

5.0 の対象プラットフォーム サポート

Microsoft.Data.SqlClient 4.1 のリリース ノート

4.1 の新機能

構成証明プロトコル None の導入

4.1 の対象プラットフォーム サポート

Microsoft.Data.SqlClient 4.0 のリリース ノート

4.0 における破壊的変更

4.0 の新機能

暗号化の既定値を true に設定

暗号化が必要なときに接続が失敗するようになりました

システムの既定のプロトコルを使用するためのアプリ コンテキスト スイッチ

最適化されたパラメーターのバインドを有効にする

構成可能な再試行ロジックの安全スイッチの削除

SqlLocalDb 共有インスタンスのサポート

XmlReader、TextReader、Stream 型の GetFieldValueAsync<T> および GetFieldValue<T> サポート

4.0 の対象プラットフォーム サポート

Microsoft.Data.SqlClient 3.0 のリリース ノート

3.0 における破壊的変更

3.0 の新機能

構成可能な再試行ロジック

イベント カウンター

Azure Identity の依存関係の導入

SNI.dll 内のイベント トレースの実装

行バージョンの null 動作の有効化

Microsoft Entra のデフォルトの認証では次のことをサポートしています。

カスタム マスター キー ストア プロバイダー登録の機能強化

列マスター キー ストア プロバイダー登録の優先順位

列暗号化キー キャッシュの優先順位

IP アドレスの優先順位

3.0 の対象プラットフォーム サポート

Microsoft.Data.SqlClient 2.1 のリリース ノート

2.1 の新機能

Always Encrypted でのクロスプラットフォームのサポート

Microsoft Entra デバイス コード フロー 認証

Microsoft Entra マネージド ID 認証

Microsoft Entra 対話型認証の機能強化

SqlClientAuthenticationProviders 構成セクション

アプリケーション クライアント ID を使用した Microsoft Entra 認証

データ分類 v2 のサポート

アクティブな SqlConnection のサーバー プロセス ID

ネイティブ SNI でのトレース ログのサポート

"Command Timeout" 接続文字列プロパティ

ネイティブ SNI からのシンボルの削除

Microsoft.Data.SqlClient のシンボルのソース リンク

2.1 の対象プラットフォーム サポート

Microsoft.Data.SqlClient 2.0 のリリース ノート

2.0 における重大な変更

2.0 の新機能

DNS エラーの回復性

EventSource の追跡

Windows でのマネージド ネットワークの有効化

小数点の切り捨て動作の有効化

新しい接続文字列プロパティのシノニム

SqlBulkCopy RowsCopied プロパティ

接続オープンのオーバーライド

Active Directory 対話モードでのユーザー名のサポート

SqlBulkCopy の順序のヒント

SNI 依存関係の変更

2.0 の対象プラットフォーム サポート

Microsoft.Data.SqlClient 5.2 のリリースノート

SqlBulkCopy に新しいプロパティ `RowsCopied64` を追加しました

SqlConnection に新しいプロパティ `AccessTokenCallBack` を追加しました

5.2 の対象プラットフォームサポート

5.1 の対象プラットフォームサポート

Microsoft.Data.SqlClient 5.0 のリリースノート

SQL データソース列挙子のサポート

5.0 の対象プラットフォームサポート

Microsoft.Data.SqlClient 4.1 のリリースノート

4.1 の対象プラットフォームサポート

Microsoft.Data.SqlClient 4.0 のリリースノート

システムの既定のプロトコルを使用するためのアプリコンテキストスイッチ

`XmlReader`、`TextReader`、`Stream` 型の `GetFieldValueAsync<T>` および `GetFieldValue<T>` サポート

4.0 の対象プラットフォームサポート

Microsoft.Data.SqlClient 3.0 のリリースノート

イベントカウンター

SNI.dll 内のイベントトレースの実装

カスタムマスターキーストアプロバイダー登録の機能強化

列マスターキーストアプロバイダー登録の優先順位

列暗号化キーキャッシュの優先順位

3.0 の対象プラットフォームサポート

Microsoft.Data.SqlClient 2.1 のリリースノート

Microsoft Entra デバイスコードフロー認証

`SqlClientAuthenticationProviders` 構成セクション

アプリケーションクライアント ID を使用した Microsoft Entra 認証

アクティブな `SqlConnection` のサーバープロセス ID

ネイティブ SNI でのトレースログのサポート

Microsoft.Data.SqlClient のシンボルのソースリンク

2.1 の対象プラットフォームサポート

Microsoft.Data.SqlClient 2.0 のリリースノート

Windows でのマネージドネットワークの有効化

2.0 の対象プラットフォームサポート

Microsoft.Data.SqlClient 1.1.0 のリリースノート

セキュアエンクレーブを使用する Always Encrypted

1.1 の対象プラットフォームサポート

Microsoft.Data.SqlClient 1.0 のリリースノート

1.0 の対象プラットフォームサポート