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 Generic Host や 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 データベース、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ドライバとフレームワーク