Microsoft.Data.SqlClient 名前空間の概要
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に新しいSqlConnectionAPI を追加しました。 #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();
using SqlConnection connection = new SqlConnection(connectionString);
connection.AccessTokenCallback = async (authParams, cancellationToken) =>
{
var cred = new DefaultAzureCredential();
string scope = authParams.Resource.EndsWith(defaultScopeSuffix) ? authParams.Resource : authParams.Resource + defaultScopeSuffix;
AccessToken token = await cred.GetTokenAsync(new TokenRequestContext(new[] { 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 での破壊的変更
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 以降1 | Windows、Linux、macOS |
| はい | いいえ2 | .NET Standard 2.0 | 2.1.0 以降 | Windows、Linux、macOS |
| はい | はい | .NET Standard 2.1 以降 | 2.1.0 以降 | Windows、Linux、macOS |
Note
1 v2.1 より前のバージョンの Microsoft.Data.SqlClient では、Always Encrypted は Windows でのみサポートされています。 2 セキュリティで保護されたエンクレーブを使用する 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>"
詳細については、次を参照してください。
- SqlClient による Always Encrypted のサポート
- チュートリアル:セキュリティで保護されたエンクレーブが設定された Always Encrypted を使用する .NET アプリケーションの開発」をご覧ください。
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)
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示