Microsoft.Data.SqlClient の接続文字列

Microsoft。Data.SqlClient 接続文字列は、セミコロンで区切られたkeyword=valueペアのリストです。 SqlConnectionかSqlConnectionStringBuilderにパスしてください:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

接続文字列では、次の 4 つの点がわかります。

1. アプリケーションはどのサーバーとデータベースを使っていますか?
2. アプリケーションはどのアイデンティティで動作しますか?
3. クライアントはどのようにしてサーバー証明書を検証するのでしょうか?
4. ワークロードに必要な接続動作は何でしょうか?

この記事では、その選択とドライバーがテキストを読む際に使うルールについて説明します。 各キーワード、その同義語、および既定値については 接続オプション を参照してください。 コード内で接続文字列を作成・変更するには 、接続文字列ビルダーを参照してください。

認証パターンを選択する

配属に合ったパターンを使いましょう。 <server>などの各プレースホルダーを自分の値に置き換えます。

Windowsの統合認証はプロセスの ID として接続します。 デスクトップやコンソールアプリケーションの場合、通常はサインインしているユーザーです。 ウェブアプリケーションやWindowsサービスの場合は、アプリケーションプールやサービスアカウントです。 なりすましは身元を変えることがあります。 アプリケーションが実際に使っているアイデンティティにログインとデータベース権限を付与します。

これら3つのWindows統合認証形式は同等です:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

文字列がIntegrated Security=trueを設定し、User IDとPasswordも設定した場合、ドライバーはWindows 認証を使い、ユーザー名とパスワードを無視します。

Microsoft.Data.SqlClient 7.0以降のバージョンでは、ドライバーが提供するMicrosoft Entra ID認証方法に対してバージョンマッチドMicrosoft.Data.SqlClient.Extensions.Azureパッケージが必要です。 アプリケーションコードがアクセストークンやアクセストークンコールバックを提供する場合は、そのパッケージは必要ありません。

受け入れられた Authentication 値については 、認証オプションをご覧ください。 認証にはデータベースユーザー、権限、サーバー上のアイデンティティ設定も必要です。 設定手順については、Microsoft Entra ID認証およびSQL Server認証を参照してください。

サーバーとデータベースを指定する

Server そして Database は最も読みやすいキーワード名です。 ビルダーはそれらを標準的な対価物、 Data Source と Initial Catalogとして記述します。 4つの名前はすべて接続文字列(接続文字列)で動作します。

Serverを以下のいずれかの形式に設定してください:

本番環境では、接続文字列、完全修飾ホスト名、および明示的なポートを使用してください。 IPアドレスではなく、サーバー証明書と一致するDNS名を使用してください。なぜなら、証明書検証は接続文字列内のサーバー名と証明書の名前を比較するからです。

SQL認証とuser@servernameフォームのユーザー名でAzure SQL Databaseに接続する場合、servername部分はServerのサーバーと一致しなければなりません。

可用性グループ リスナーまたはフェールオーバー クラスター インスタンスについても、Multi Subnet Failoverのを確認してください。

暗号化と証明書検証の設定

Encryptキーワードは、いずれの場合も以下の値を受け入れます。

サーバーが TDS 8.0 をサポートしており、かつ、クライアントが検証できる証明書を備えている場合は、Strict を使用します。 Azure SQL DatabaseおよびMicrosoft FabricのSQLデータベースはこれをサポートしています。 LocalDBの接続は暗号化されておらず、Mandatoryを使っていてもStrictも失敗します。

Encrypt値とTrust Server Certificate値は以下のように組み合わさります。

本番環境での接続エラーを修正するために Trust Server Certificate=true を設定しないでください。 チャネルを暗号化しますが、サーバーの身元は確認しません。 信頼できる証明書が存在しない開発環境に限定してください。

Data Source内のサーバー名が証明書と一致しない場合は、Host Name In Certificateを証明書の名前に設定してください。 SqlClientはサーバー名と一致しない時だけチェックし、証明書のピン留めもしません。 特定の証明書を1つだけ受け入れるには、「Server Certificate」にPEM、DER、またはCERファイルのパスを設定します。

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

検証ルールの詳細については、「暗号化および証明書の検証」を参照してください。

接続プーリングを使用する

プーリングはデフォルトでオンになっています。 SqlConnectionを開くと、ドライバーはその接続設定に一致するプールから物理的な接続を取得します。 接続を閉じたり破棄したりすると、物理的な接続は閉じるのではなくプールに戻ってきます。 プールされたオープンはネットワーク接続、TLSハンドシェイク、ログインをスキップします。

次の規則に従います。

• 必要な直前に接続を開け、終わったらすぐに破棄し、using または await using を使用してください。 廃棄されていない接続はチェックアウトのままで、プールが尽きることもあります。

• 起動時に一度接続文字列を作成し、それを再利用してください。 プールキーには接続文字列の正確なテキストが含まれているため、異なるキーワードの順序、同義語、またはリクエストIDやユーザー名などのリクエストごとの値が別個のプールを形成します。 ビルダーは一つの正準形を出力します。 詳細については、「Keep one canonical 接続文字列」を参照してください。

• 統合認証のもとで各Windowsアイデンティティ、各SqlCredentialインスタンス、各AccessToken値ごとに別々のプールが用意されることを期待してください。 各接続にAccessTokenCallbackを設定するのではなく、ドライバーが提供するAccessTokenメソッドや再利用されたAuthenticationを使うのが良いでしょう。

• Max Pool Size の値を増やす前に、まだ破棄されていない接続を探してください。Max Pool Size はデフォルトで 100 に設定されています。 プール内のすべての接続が使用中の場合、 Open は最大 Connect Timeout まで待ち、その後 InvalidOperationExceptionを投げます:

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• すべてのプールのサーバー容量を計画しましょう。 .NETフレームワーク上の各プロセス、または各アプリケーションドメインは独自のプールを持っています。 サーバーへの接続は、各プロセスのプール数とアプリケーションインスタンス数を Max Pool Size に掛け合わせた数に達する可能性があります。

• Pooling=false を、プールの問題の回避策として設定しないでください。 開くたびに、完全なログインが実行されます。

長くアイドル状態のプール接続を閉じるには、「 接続アイドル時間の制限」を参照してください。 プールキー、サイズ設定、クリアリング、トランザクションについては、SQL Server接続プーリングを参照してください。

接続設定とコマンド設定を別々に

接続文字列は接続の確立とセッションの動作を制御します。 コマンドは1つのSQL操作を制御します。

タイムアウトが長くなるのはリトライ ロジックではありません。 タイムアウトは待機時間の制限です。 再試行すると次の試みが始まり、その再挑戦は上限が定められており、安全に繰り返せなければなりません。

アプリケーション ID を報告する

Application Name サーバーが APP_NAME()を通じて報告する名前を設定します。 デプロイされた各ワークロードに対して1つの安定名を使いましょう。 アプリケーション用に接続を開くフレームワークやツールも、接続文字列キーワードを持たないこのRegisteredApplicationプロパティを通じて自己報告できます。 詳細については、「アプリケーション ID を報告する」をご覧ください。

接続ストリングを安全に作る

コードが値を追加・変更するときには SqlConnectionStringBuilder を使いましょう。 信頼できないテキストを接続文字列に結合しないでください。なぜなら、そのテキストのセミコロンがキーワードを追加または置き換えることがあるからです。 ビルダーは値を検証し、同義語を標準キーワードにマッピングし、各値を引用符で囲み、その値がキーワードを追加できないようにします。 例については「接続文字列ビルダー」を参照してください。

コード外での接続情報の保存

アプリケーションの設定システムから接続文字列を読み込みます。 .NETアプリケーションは一般的に環境変数、ローカル開発のためのユーザーシークレット、Azure App Configuration、Azure Key Vaultを使用します。

次の規則に従います。

• パスワード、クライアントシークレット、アクセストークン、本番接続文字列はコミットしないでください。
• 接続文字列にパスワードを含める必要がない認証方法を使用してください。
• 設定ソースへのアクセスを制限してください。
• 保存されたシークレットをローテーションし、それらをキャッシュしているアプリケーションを再起動または再読み込みします。
• ログ、例外、トレース、テレメトリに接続文字列を書かないでください。
• デフォルトの Persist Security Info=false のままにしておくと、開かれた接続の ConnectionString プロパティを介してパスワードが公開されないようにできます。

.NET 設定プロバイダーについては、「.NET 内の構成」を参照してください。 その他のコントロールについては、接続情報の保護をご覧ください。

構文解析ルール

ドライバーは以下のルールを適用します：

• キーワードでは大文字と小文字は区別されません。 DATABASE、 Database、 database は同じキーワードです。
• 多くのキーワードには同義語があります。 Server と Data Source は同じ値を設定します。 Connectionオプションの記事には、各キーワードの同義語が記載されています。
• キーワードが複数回現れた場合、最後の値が優先されます。 同義語は同じキーワードとしてカウントされます。
• ドライバーはキーワードや引用符なしの値の周りのスペースを無視します。
• 末尾のセミコロンは任意です。
• ドライバーが認識できないキーワードは、メッセージArgumentExceptionを含むKeyword not supportedをスローします。

値はキーワードによって大文字と小文字を区別することがあります。 パスワードは大文字と小文字が区別されます。 Encrypt=STRICT と Encrypt=strict は同じです。

このプログラムは、ビルダーがどのようにキーワードを正規化し、重複を解決し、特殊文字を引用するかを示します。 .NET Framework タブでは C# 7.3 を使用しています。 サンプルを実行するプロジェクトを作成するには、「 プロジェクトを作成」をご覧ください。

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

出力は次のとおりです。

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

最初の行は各同義語を標準的なキーワードに置き換えたものを示しています: server → Data Source、 DATABASE → Initial Catalog、 uid → User ID、 timeout → Connect Timeout。

値を引用符で囲む

セミコロン、スペースで始まるか終わる値、または引用符で始まるか終わる値がある場合、二重引用符(")または単一引用符(')で囲みます。 引用符で囲まれた値の中では、囲む引用符を2回書きます。

ルールを引用するのは間違えやすいものです。 プロパティ を通じて値を設定し、ビルダーにそれらを引用符で囲ませます。 詳細については、「 安全に接続文字列を構築する」をご覧ください。

ブール値を指定してください

ブール値を取るキーワードは、大文字小文字を問わず、true、false、yes、および no を受け入れます。 Integrated Security また、 sspiも受け入れ、つまり trueを意味します。 ビルダーは True または False と書きます。

他のドライバーのキーワードを使う

Microsoft.Data.SqlClientはDriverやProviderなどのODBCやOLE DBキーワードを受け入れていません。 他のドライバーから接続文字列を移動する際には、これらのキーワードを削除してください。 System.Data.SqlClient接続文字列は Microsoft.Data.SqlClient で動作します。以下の違いがあります:

• Encrypt の既定値は Microsoft.Data.SqlClient では Mandatory です。 信頼できる証明書を持たないサーバーは証明書検証に失敗します。 サーバーに信頼できる証明書をインストールしてください。
• .NETでは、Network Library、Connection Reset、Transparent Network IP Resolutionはサポートされていません。 削除してください。
• Context Connection=trueはサポートされていません。
• Asynchronous Processing はサポートされているキーワードではなく、ArgumentException をスローします。 削除します。 非同期メソッドはそれなしでも動作します。
• Type System Version=SQL Server 2000はサポートされていません。 接続を作成すると ArgumentException がスローされます。 Latest、SQL Server 2012、SQL Server 2008、またはSQL Server 2005を使ってください。

関連するコンテンツ

• .NET アプリで Microsoft.Data.SqlClient を使用する
• 接続オプション
• 接続文字列ビルダー
• データ ソースへの接続
• SQL Server 接続プーリング
• Microsoft Entra ID 認証
• 暗号化と証明書の検証
• SQL Server Express のユーザー インスタンス
• SqlClient ドライバーのサポート ライフサイクル