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データベース、Microsoft FabricのWarehouse対応の.NETデータプロバイダーです。 NuGetパッケージとして配布され、.NETランタイムとは独立して進化し、新しい開発のためにSystem.Data.SqlClientを置き換えます。 .NETアプリケーションに対して、接続、コマンド、結果処理、トランザクション、一括コピー、SQL Server固有の機能を提供します。

出発点を選択する

• プロジェクトを設定し、最初のクエリを実行するには、 まず「Get started」からSqlClientドライバーから始めてください。
• 接続するデータベースを作成するには、SqlClient ドライバーの使用開始にある 前提条件 を参照してください。
• .NETプロジェクトでドライバーを追加または更新するには、「Microsoftのインストール、更新、デプロイ」へ行ってください。Data.SqlClient。
• パスワードレス認証でAzure SQLに接続するには、まずMicrosoft Entra認証とConnection文字列から始めてください。
• 既存のアプリケーションを一時的な障害に対して強靭にするには、 Configurable retry logic と High availability and disaster recoveryにアクセスしてください。
• 大規模なデータセットを効率的に移動するには、 バルクコピー操作に切り替えてください。
• System.Data.SqlClientからの移行は、まずSystem.Data.SqlClientからMicrosoftへ移行します。Data.SqlClient。
• 接続やクエリの問題を診断するには、 SqlClientトラブルシューティングガイド の「 イベントソーストレーシングを有効にする」をご覧ください。

Azure SQLの運用ベースライン

このスニペットを本番向けのAzure SQLデータアクセスパスの出発点として活用してください。 IConfigurationからサーバー名やデータベース名を読み取るため、値はホストによって設定された構成プロバイダー(appsettings.json、環境変数、Azure App Configuration、Key Vault によって裏付けられた設定など)から得られます。 この構成は以下の特徴を組み合わせています:

• トランスポート層セキュリティ(TLS)。
• マネージド ID。
• アイドル接続のレジリエンス(回復力)
• 構成可能な再試行ロジック(CRL)による初期接続再試行と構造化ログ付き。
• クエリ中に発生する一時的なエラーに対してコマンドレベルの再試行。
• 迅速なフェイルオーバーグループ復旧。
• キャンセル トークンを受け取る非同期呼び出し。

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

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

このスニペットは、.NET 8以降のバージョンを対象としたプロジェクトを前提としており、Microsoft.Data.SqlClientおよびMicrosoft.Data.SqlClient.Extensions.Azure 7.1.1パッケージを参照しています。 .NETジェネリックホストやASP.NET CoreなどのホストはILoggerとIConfigurationを提供し、設定はSql:Serverでサーバー名、Sql:Databaseでデータベース名を提供します。

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    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 (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // 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);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

このメソッドは接続されたデータベース名を返し、Connected to database <database>をログに記録します。 再試行が起きると、それを引き起こした例外とともに、再試行のたびに警告が1件記録されます。

スニペットの各部分の仕組み:

• 対象: Microsoft Entra 認証用に構成された任意の SQL データベース エンジン エンドポイント: Azure SQL Database、Azure SQL Managed Instance、Microsoft Fabric の SQL Database、Azure 仮想マシン 上の、または Azure Arc で有効化された SQL Server 2022 以降。
• Encrypt = SqlConnectionEncryptOption.StrictTDS 8.0暗号化を選択します。 SQL Server 2022以降のバージョン、Azure SQL Database、Azure SQL Managed Instance、またはMicrosoft FabricのSQL Databaseが必要です。 古いサーバーには SqlConnectionEncryptOption.Mandatory を使いましょう。
• ActiveDirectoryManagedIdentity: 管理されたアイデンティティが利用可能な場合にのみ機能します。例えば、Azure App Service、Azure Functions、またはAzure仮想マシンなどです。 ローカル開発では、SqlAuthenticationMethod.ActiveDirectoryDefault を使いましょう。これは Azure CLI、Visual Studioサインイン、その他の認証情報ソースを試します。 各ソースを探ると接続が遅くなるので、本番環境では使わないでおけ。 詳細は「 デフォルト認証を使用」をご覧ください。
• MultiSubnetFailover = true: すべての解決済みIPアドレスに対して並列にTCP接続を試み、最初に成功した接続を使用します。これにより、遅いIPごとの順次試行を回避します。 Azure SQL Database、Azure SQL Managed Instance、Microsoft FabricのSQLデータベース、可用性グループリスナー、フェイルオーバークラスタインスタンスに設定してください。 単一IPの対象でも安全です。 名前付きインスタンス、TCP 以外のプロトコル、64 個を超える IP アドレスを持つインスタンス、または非推奨であるデータベース ミラーリングではサポートされていません。 代わりに Always On 可用性グループ を使用してください 詳細については、 高可用性と災害復旧 および透明 ネットワークIP解決の無効化を参照してください。
• ConnectRetryCount = 3 と ConnectRetryInterval = 10: ドライバーは Open()中に一時的な障害発生時に再試行し、次のコマンド時に切断されたアイドル接続を再接続します。 デフォルトのカウントは1です。 10秒間隔で3回行う試行は、より長い再構成やフェイルオーバーよりも長く持ちこたえます。 ドライバーはサーバー名が既知のAzure SQLドメイン(例えば.database.windows.net)で終わる場合にのみ1を2に上げるため、カスタムDNSエイリアスは1になります。
• openRetry SqlConnection.RetryLogicProviderに割り当てられ、Open()に対して指数関数的なバックオフを追加します。 ドライバーは ConnectTimeout が切れると内部リトライを停止するため、OpenAsync が例外をスローするまでの最悪のケースは、最大 30 秒の試行 5 回に、バックオフを加えた程度です。 アイドル再接続のたびに完全な openRetry ポリシーを実行し、そのポリシーが再試行回数を使い果たすとアイドルリカバリーは終了します。
• サーバーレス自動一時停止: Azure SQL Database サーバーレス では、ConnectTimeout を少なくとも 60 秒に引き上げてください。 最初の Open() はエラー 40613 で失敗することがありますが、データベースの再開中に openRetry がそれを再試行します。 クライアント側のタイムアウトはエラー -2として現れますが、再試行はされないため、各接続試行は再開よりも長く続けなければなりません。 詳細は「 自動一時停止」と「自動再開」をご覧ください。
• commandRetryコマンドの再実行が安全である場合にのみ SqlCommand.RetryLogicProvider に付けてください: 読み取り、自然キーで保護された MERGE、保存プロシージャを通じたアップサート、その他の冪等操作。 トランザクション内でリトライをスキップするため、アプリケーションコードは複数ステートメントのトランザクションをリトライしなければなりません。 ExecuteReader および ExecuteScalar は、最初の結果セットが始まる前に返されたエラーのみを再試行します。 ExecuteNonQuery 通話全体を再試行します。
• 一時的なエラーリスト: TransientErrors 設定は組み込みリストを置き換えます。 代わりに拡張するには、SqlConfigurableRetryFactory.BaselineTransientErrors(Microsoft.Data.SqlClient 7.0以降)を使いましょう。
• Retrying イベント: Retrying は各リトライの前に、リトライ回数、次の遅延、これまでの例外とともに発生します。 ILoggerかテレメトリパイプラインにルーティングしてください。
• 例外:このメソッドは例外をキャッチしません。 使い果たされたプロバイダーは、各試行の例外とともに AggregateException を投げます。 非一時的なエラーは元の例外として伝播します。 呼び出し元はリクエストの残りのコンテキストとともに一度だけログを残します。
• キャンセル: CancellationToken は、再試行間のプロバイダーの待機を停止します。 1回のConnectRetryInterval試行でドライバーのOpen待ちを妨げることはありません。 詳細は「 非同期プログラミング」を参照してください。
• プロバイダーのライフタイム: スニペットは、自己完結に保つために、呼び出しのたびにリトライ プロバイダーを作成します。 アプリケーションでは一度作成して再利用します。

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

• 接続文字列
• Microsoft Entra 認証
• 暗号化と証明書の検証
• 構成可能な再試行ロジック
• 高可用性とディザスター リカバリー

データアクセスのコアタスクを学びましょう

接続後は、以下の記事を順番に参照してください：

1. 結果形状を選択してTransact-SQL (T-SQL) を実行するコマンドを実行します。
2. パラメータを設定して データベース仕様に合うようにします。
3. SqlDataReaderでデータを取得 し、行や複数の結果を処理できます。
4. ストアドプロシージャを修正して、出力パラメータや返り値を使用します。
5. 非同期プログラミングとキャンセルを使って、呼び出し元によるキャンセルや制限付きタイムアウトを追加しましょう。
6. 再試行や本番の診断を追加する前に、エラーやメッセージを処理してください。

主要な機能

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

概要

構成と接続

認証とセキュリティ

データの取得と更新

データの種類

信頼性と診断

SQL Server 機能

参照とリソース

機能をリクエストする

機能の追加を要望するには、Microsoft.Data.SqlClient GitHub リポジトリで Issue を作成してください。

関連するコンテンツ

• Microsoft。GitHubのData.SqlClient
• NuGet 上の Microsoft.Data.SqlClient
• リリースノート
• ADO.NET概要
• Microsoft SQLドライバとフレームワーク