Microsoft.Data.SqlClient for SQL Server

ADO.NET のダウンロード

Microsoft.Data.SqlClient は、SQL Server、Azure SQL Database、Azure SQL Managed Instance、Azure Synapse Analytics、および Microsoft Fabric の SQL データベース向けにサポートされている .NET データ プロバイダーです。 NuGetパッケージとして配布され、.NETランタイムとは独立して進化し、新しい開発のためにSystem.Data.SqlClientを置き換えます。 接続の開放、コマンドの実行、結果の処理、トランザクション管理、データの一括読み込み、.NETアプリケーションのSQL Server固有の機能を活用するために使えます。

出発点を選択する

Azure SQLの運用ベースライン

このスニペットを本番向けのAzure SQLデータアクセスパスの出発点として活用してください。 サーバー名とデータベース名をIConfigurationから読み取るため、値はホストが配線した設定プロバイダー(appsettings.json、環境変数、Azure App Configuration、Key Vault支援設定など)から得られます。 この構成は、トランスポート層セキュリティ(TLS)、マネージドアイデンティティ、アイドル接続の回復力、構成可能な再試行ロジック(CRL)による初期接続再試行(構造化ログ付き)、クエリ中に発生する一時的なエラーに対するコマンドレベルの再試行、そして迅速なフェイルオーバーグループ復旧を組み合わせています。

セキュリティ向上と環境間の設定をサポートするために、接続情報はコード外に保持してください。 本番環境では、接続情報をアプリケーションの設定システムに保存し、機密値をAzure Key Vaultで管理してください。 詳細については、「 接続情報の保護」を参照してください。

この記事のC#スニペットは簡潔にするために using 指示やクラスラッパーを省略しています。

public static void QuerySalesWithResilience(IConfiguration config, ILogger logger)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (SqlClient 5.0 and later versions; server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Idle connection resiliency: reconnect a dropped idle connection after Open() succeeded.
        // This is separate from the initial-connect retry provider defined next.
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Retry the initial Open() on transient failures with exponential backoff and jitter.
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    try
    {
        using var connection = new SqlConnection(builder.ConnectionString)
        {
            RetryLogicProvider = openRetry,
        };
        connection.Open();

        using var command = new SqlCommand(
            "SELECT TOP (100) SalesOrderId, OrderDate, TotalDue FROM Sales.SalesOrderHeader ORDER BY OrderDate DESC",
            connection)
        {
            RetryLogicProvider = commandRetry,
            CommandTimeout = 30,
        };

        using var reader = command.ExecuteReader();
        while (reader.Read())
        {
            logger.LogInformation(
                "Order {SalesOrderId} placed {OrderDate:d} total ${TotalDue:N2}",
                reader.GetInt32(0), reader.GetDateTime(1), reader.GetDecimal(2));
        }
    }
    catch (SqlException ex)
    {
        logger.LogError(
            ex,
            "Query against {Server}/{Database} failed after retries (SQL error {ErrorNumber})",
            server, database, ex.Number);
        throw;
    }
}

このスニペットは、Microsoft Entra認証に設定されたすべてのSQL データベース エンジンエンドポイントを対象としています:Azure SQL Database、Azure SQL Managed Instance、Microsoft FabricのSQL Database、SQL Server 2022以降のバージョンはAzure 仮想マシンまたはAzure Arcで有効化されています。

Encrypt = SqlConnectionEncryptOption.Strict TDS 8.0暗号化を選択します。 Microsoftが必要です。Data.SqlClient 5.0以降のバージョンと、TDS 8.0(SQL Server 2022以降バージョン、Azure SQL Database、Azure SQL Managed Instance、Microsoft FabricのSQLデータベース)をサポートするサーバーが必要です。 古いサーバーに接続する際には SqlConnectionEncryptOption.Mandatory にフォールバックしましょう。

ConnectRetryCountそしてConnectRetryIntervalアイドル接続のレジリエンシーを有効にします:Open()成功後、ドライバーは次のコマンドで切断されたアイドル接続を透過的に再接続します。 最初の試行 Open()はやり直しません。 初期接続の再試行は、openRetryに割り当てられたSqlConnection.RetryLogicProviderプロバイダーから行われます。 この二つの特徴は補完的です。

各プロバイダーの Retrying イベントは各リトライの前に発生し、リトライカウント、次の試みまでの遅延、これまでに観察された例外を伝えます。 リトライループを本番環境で見せるように、 ILogger かテレメトリパイプラインにルーティングしてください。

ターゲットがAzure SQL Database、Azure SQL Managed Instance、Microsoft FabricのSQLデータベース、可用性グループのリスナー、またはフェイルオーバークラスターインスタンスの場合にMultiSubnetFailover = true設定してください。 名前解決されたすべてのIPアドレスに対してTCP接続を並列に試行し、最初に成功した接続を使用する並列接続用のコードパスを選択します。これにより、そうしない場合に接続が停滞するおそれのある、IPアドレスごとに順番に試す低速な処理を回避します。 単一IPターゲットでは、設定は安全です。 MultiSubnetFailover 名前付きインスタンスに接続する場合、TCP以外のプロトコルで接続する場合、または64以上のIPアドレスで設定されたインスタンスに接続する場合にはサポートされません。 また、データベースミラーリングでは使えず、サポートされているすべてのSQL Serverバージョンで推奨されていません。 代わりに Always On 可用性グループ を使用してください 詳細については、 高可用性と災害復旧 および透明 ネットワークIP解決の無効化を参照してください。

ターゲットがAzure SQL Databaseサーバーレスで自動一時停止が有効な場合は、ConnectTimeoutを少なくとも60秒に引き上げてください。 自動一時停止されたデータベースは最初の Open()で再開され、その最初の Open() はエラー 40613 で失敗することがありますが、データベースは再開されます。 エラー 40613 は内蔵の過渡性エラーリストにあるため、 openRetry 再試行します。 クライアント側のタイムアウトはエラー -2 として表示されますが、その一覧には含まれていないため、再開処理の途中でタイムアウトした openRetry は Open() では救済できません。 個々の接続試行は、再開をカバーするのに十分な長さでなければなりません。 詳細は「 自動一時停止」と「自動再開」をご覧ください。

コマンドレベルの再試行は、コマンドごとに発信者の判断です。 次のようなコマンドを再実行しても安全な場合にのみ、commandRetry を SqlCommand.RetryLogicProvider にアタッチします。読み取り、自然キーで保護された MERGE、ストアド プロシージャを介したアップサート、その他のべき等操作。 組み込みのコマンドプロバイダーはトランザクションがアクティブなときにリトライをスキップするため、複数文のトランザクションはトランザクションを再開できるアプリケーションコードで再試行する必要があります。 TransientErrors を設定すると、ドライバーの組み込みエラー リストは置き換えられます。代わりに組み込みベースラインを拡張するには、SqlConfigurableRetryFactory.BaselineTransientErrors を使用します（Microsoft.Data.SqlClient 7.0 以降）。

この構成の各部分の詳細については、以下を参照してください。

主要な機能

  • 最新の.NETサポート:現在の.NETおよび.NETフレームワークのバージョンで動作します。 バージョンごとの内訳については、 サポートライフサイクルをご覧ください。
  • デフォルトで暗号化:TLSで暗号化され、 Encrypt=true がデフォルトです。 Microsoft.Data.SqlClient 5.0 以降では、TDS 8.0 暗号化のために Encrypt=Strict を設定してください。
  • Microsoft Entra ID認証: マネージド ID、サービス プリンシパル、対話型、統合、既定の資格情報チェーン、アクセス トークン フローを使用したパスワードレス接続。
  • Kerberos と NTLM: オンプレミスの Active Directory およびレガシー シナリオ向けの統合 Windows 認証。
  • Always Encrypted: 機密列のクライアント側暗号化。インプレース操作のための省略可能なセキュア エンクレーブに対応。
  • 一括コピー: SqlBulkCopyを活用した高スループット挿入。
  • 接続のレジリエンシー:組み込みの接続再試行(ConnectRetryCount および ConnectRetryInterval)と、接続やコマンドのためのオプトイン可能な設定可能な再試行ロジック。
  • 豊富なSQL Serverデータ型:datetimeoffset、sql_variant、JSON、ベクター、空間、XML、テーブル値パラメータ。
  • 診断:イベントソーストレーシング、診断カウンター、提供者統計、専用のトラブルシューティングガイド。

概要

[アーティクル] Description
SqlClient ドライバーの概要 プロジェクトを設定し、データベースを作成し、接続し、クエリし、接続のレジリエンシーを追加しましょう。
SqlClient ドライバーの概要 Microsoftの方法を学びましょう。Data.SqlClientはADO.NETに適合します。
Microsoftをダウンロードしてください。Data.SqlClient NuGetパッケージをインストールし、ソースリリースを探してください。
サポート ライフサイクル サポートされているドライバーのバージョンとサポート日を確認しましょう。
Microsoft。Data.SqlClient 名前空間 System.Data.SqlClientから移行し、名前空間の違いを確認してください。

構成と接続

[アーティクル] Description
データ ソースへの接続 SQL Server と Azure SQL への接続を開いて管理します。
接続文字列 サーバー、データベース、認証、暗号化、接続動作の設定を行います。
暗号化と証明書の検証 暗号化された接続とサーバー証明書の検証を設定しましょう。
SQL Server 接続プーリング 物理的な接続を効率的に再利用しましょう。
接続イベント 接続状態や情報メッセージに応答します。

認証とセキュリティ

[アーティクル] Description
SQL Server のセキュリティ 認証、承認、アプリケーションのセキュリティガイダンスを確認してください。
Microsoft Entra 認証 マネージドID、サービスプリンシパル、パスワード、インタラクティブフローと接続できます。
接続情報の保護 認証情報や接続設定はアプリケーションコードから除外してください。
常に暗号化 データベースシステムから機密の列値を保護しましょう。
セキュリティで保護されたエンクレーブが設定された Always Encrypted 暗号化されたデータに対してリッチな操作を行い、安全なエンクレイブを設けましょう。

データの取得と更新

[アーティクル] Description
コマンドとパラメーター パラメータ化されたSQL文やストアドプロシージャを実行します。
DataAdapters と DataReaders 結果セットをストリーミングしたり、切り離されたデータ構造を埋めたりします。
トランザクションとコンカレンシー ローカルおよび分散トランザクションと並行制御を活用しましょう。
データベーススキーマ情報の取得 スキーマコレクションと制限を発見しましょう。
一括コピー作業 SqlBulkCopyで大規模なデータセットを効率的に読み込みましょう。
テーブル値パラメーター パラメータ化された文やストアドプロシージャに複数の行を送ります。
非同期プログラミング 非同期接続、コマンド、データ操作を活用してください。
複数のアクティブな結果セット (MARS) 1つの接続で複数のバッチをインターリーブします。

データの種類

[アーティクル] Description
ADO.NETデータ型マッピング 共通言語のランタイムタイプをプロバイダーおよびSQL Serverタイプにマッピングします。
SQL Server データ型 SQL Server特有の価値観やSystem.Data.SqlTypesタイプを扱いましょう。
JSONデータ SQL Server jsonデータ型を送信・取得します。
ベクトルデータ ベクトル値の送信と取得。
XMLデータ XMLの値を読み書き、パラメータ化します。
バイナリおよび大型データ バイナリ、FILESTREAM、および大容量値データをストリーミングして更新します。

信頼性と診断

[アーティクル] Description
構成可能な再試行ロジック 一時的な接続やコマンドの失敗を制限ポリシーで再試行してください。
高可用性とディザスター リカバリー 可用性グループリスナーやフェイルオーバーパートナーと接続しましょう。
診断カウンター アクティブな接続、プールされた接続、その他のドライバー指標を監視してください。
イベントソーストレーシングを有効にする 詳細な運転者イベントを記録し、診断を行ってください。
データトレース ADO.NET操作およびデータアクセスを追跡します。
SqlClient トラブルシューティング ガイド 共通接続やドライバーの問題を診断しましょう。
クエリ通知 クエリ結果が変更された際に通知を受け取ります。

SQL Server 機能

[アーティクル] Description
SQL Server の機能と ADO.NET SqlClientで利用可能なSQL Server固有の機能を閲覧できます。
ローカルDB SQL Server Express LocalDBインスタンスに接続します。
データの検出と分類 結果セットから感度分類メタデータを読み取る。

参照とリソース

[アーティクル] Description
Microsoft.Data.SqlClient API リファレンス ドライバーの.NET API参照を参照してください。
AppContextの切り替え 互換性とセキュリティ動作の設定を行います。
追加のSqlClient情報もご覧ください ソースコード、サポート、コミュニティリソースを見つけましょう。

関連するコンテンツ

  • Last updated on