Microsoftの接続オプション。Data.SqlClient

この記事は、Microsoft.が受け入れているすべての接続文字列キーワードを一覧にしています。Data.SqlClientが受け入れています。 各キーワードには対応する SqlConnectionStringBuilder プロパティも持っています。 導入、一般的なパターン、解析ルールについては 「接続文字列」を参照してください。

キーワードやエイリアスは大文字を区別しません。 ビルダープロパティで値を設定すると、ビルダーは キーワード欄に 標準的なキーワードを書き込みます。

SqlConnectionStringBuilderでオプションを設定する

サーバー、データベース、認証設定を保持する基本接続文字列から始めます。 その後、ビルダープロパティでワークロード固有のオプションを設定します。 .NETフレームワークのタブはC# 7.3を使用しています。 サンプルを実行するプロジェクトを作成するには、「 プロジェクトを作成」をご覧ください。

using Microsoft.Data.SqlClient;

string connectionString =
    Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
    ?? throw new InvalidOperationException(
        "Set the SQL_CONNECTION_STRING environment variable.");

var builder = new SqlConnectionStringBuilder(connectionString)
{
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    CommandTimeout = 60,
    MaxPoolSize = 50,
};

await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();

await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");

出力は次のとおりです。

APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60

新しい SqlCommand は接続の Command Timeout キーワードからデフォルトのタイムアウトを取ります。

デフォルト値を確認してください

新しい SqlConnectionStringBuilder がすべてのオプションのデフォルトを報告します。 このプログラムは、ほとんどのアプリケーションが確認するデフォルト情報を印刷します:

using Microsoft.Data.SqlClient;

var defaults = new SqlConnectionStringBuilder();

Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");

.NET 上の出力は次の通りです:

Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind

Encrypt: True Mandatoryの選択肢です。 .NET Frameworkでは、デフォルトのアプリケーション名はFramework Microsoft SqlClient Data Providerです。

サーバーおよびデータベースのオプション

キーワード Aliases 建設業者の所有物 Default 説明
Data Source Server、Address、Addr、Network Address DataSource 空 接続するサーバー。 ホスト名、 host,port、 host\instance、 (localdb)\instance、 tcp: または np: プロトコルプレフィックスを受け入れます。 受け入れられたフォームについては、「 サーバーとデータベースを指定する」を参照してください。
Initial Catalog Database InitialCatalog 空 ログイン後に使うデータベース。 空のデータベースはサーバーがログインのデフォルトデータベースを使用します。
AttachDbFilename Extended Properties、Initial File Name AttachDBFilename 空 SQL Server ExpressおよびLocalDB用のプライマリデータベースファイルの全パスを接続します。
User Instance None UserInstance false 接続をSQL Server Expressのユーザーインスタンスにリダイレクトします。 詳細については、SQL Server Expressのユーザーインスタンスをご覧ください。
Failover Partner FailoverPartner FailoverPartner 空 プライマリサーバーが利用できない場合に試すデータベースミラーリングパートナー。 データベースミラーリングは廃止されています。 新規展開には可用性グループを活用しましょう。
Current Language Language CurrentLanguage 空 セッションの言語名SQL Server、例えばus_english。 日付フォーマットとシステムメッセージ言語を制御します。

アプリケーション識別オプション

キーワード Aliases 建設業者の所有物 Default 説明
Application Name App ApplicationName Core Microsoft SqlClient Data Provider サーバーが APP_NAME() やセッションビューで報告する名前です。 デプロイされた各ワークロードに対して1つの安定名を使いましょう。 異なる値は異なる接続プールを生み出します。
Workstation ID WorkstationID、WSID WorkstationID ローカル コンピューター名 サーバーが HOST_NAME()を通じて報告するクライアントコンピュータ名です。
Application Intent ApplicationIntent ApplicationIntent ReadWrite ReadOnly ターゲットがサポートする場合に読み取り意図ルーティングを要求します。 文は読み取り専用にはなりません。 詳細は「 高可用性および災害復旧」を参照してください。

どのフレームワークやツールが接続を開いたかを報告するには、 RegisteredApplication プロパティを使いましょう。 接続文字列キーワードは存在しません。 詳細については、「 アプリケーション識別を報告」をご覧ください。

認証オプション

キーワード Aliases 建設業者の所有物 Default 説明
Authentication None Authentication 指定なし 認証方法。 受け入れられた値は以下の表を参照してください。
Integrated Security Trusted_Connection IntegratedSecurity false true、 yes、または sspi は現在のプロセスの単位元を利用します。
User ID UID、User UserID 空 SQLのログイン名、またはMicrosoft Entra IDユーザーまたはクライアント識別子(Authenticationによって異なります)。
Password PWD Password 空 パスワードやクライアントの秘密を受け入れるメソッドの場合は。
Persist Security Info PersistSecurityInfo PersistSecurityInfo false falseした場合、接続が開いた後、ドライバーはSqlConnection.ConnectionStringからパスワードを削除します。 そのままにして false。
Server SPN ServerSPN ServerSPN サーバー名に由来します プライマリサーバーへの統合認証に使用されるサービスプリンシパル名(SPN)を上書きします。
Failover Partner SPN FailoverPartnerSPN FailoverPartnerSPN パートナー名に由来します フェイルオーバーパートナーへの統合認証に使われるSPNを上書きします。

Authentication これらの価値観を受け入れます。 ビルダーは ActiveDirectoryDefaultのようにスペースを使わずに書き、パーサは両方の形を受け入れます。

価値 Identity
Sql Password User IDとPasswordを使ったSQLログインです。
Active Directory Default 環境変数、管理型アイデンティティ、開発者ツールのサインインなどの認証情報ソースの連鎖です。
Active Directory Managed Identity 管理されたアイデンティティです。 User IDをユーザー割り当てのIDのクライアントIDに設定します。 Active Directory MSI はエイリアスです。
Active Directory Workload Identity Kubernetesワークロードのアイデンティティです。
Active Directory Service Principal User IDがクライアントIDに設定され、Passwordがクライアントシークレットに設定されたアプリケーションです。
Active Directory Interactive ブラウザのプロンプトでサインインするユーザー。
Active Directory Device Code Flow コードで別のデバイスにサインインするユーザー。
Active Directory Integrated サインインしたWindowsユーザーは、フェデレーテッドまたはシームレスなシングルサインオン構成を通じて利用できます。
Active Directory Password ユーザー名とパスワード。 メソッドは廃止されています。 別の方法を使う。

Microsoft Entra IDメソッドにはMicrosoft.Data.SqlClient.Extensions.Azureパッケージが必要です。 セットアップや例については、Microsoft Entra ID認証およびSQL Server認証を参照してください。

暗号化オプション

キーワード Aliases 建設業者の所有物 Default 説明
Encrypt None Encrypt Mandatory Strict TDS 8.0を使用し、常にサーバー証明書の検証を行います。 Mandatory、 true、または yes が接続を暗号化します。 Optional、 false、または no は、サーバーが要求するときだけ接続全体を暗号化します。 サーバーが暗号化をサポートしているが必須でない場合、暗号化されるのはログインパケットのみです。
Trust Server Certificate TrustServerCertificate TrustServerCertificate false true サーバー証明書の検証を省略します。 Encrypt=Strict場合は無視されます。 運用環境では使用しないでください。
Host Name In Certificate HostNameInCertificate HostNameInCertificate 空 証明書検証のための代替名称です。 SqlClientはまず Data Sourceのサーバー名に対して証明書を検証します。 名前が一致しない場合だけ Host Name In Certificate チェックするため、サーバー名がすでに一致している場合に間違った値があっても失敗にはなりません。 証明書をピン留めするわけではありません。 特定の証明書を要求するには Server Certificateをご利用ください。 ネットワークの宛先を変更したり、信頼チェーンや有効期限チェックを回避したりはしません。 サーバー名がすでに証明書と一致している場合は、設定を解除したままにしてください。
Server Certificate ServerCertificate ServerCertificate 空 PEM、DER、またはCERファイルのパスで、サーバー証明書と正確に一致しなければならない。 ドライバーは証明書の検証時にのみ照合を確認するので、 Encrypt=Mandatory や Encrypt=Strict 、 Trust Server Certificate=falseと組み合わせて使うのが良いです。 マッチングファイルはチェーン名やホスト名の検証に代わるもので、クライアントが信頼していない自己署名証明書で動作します。

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

常に暗号化されたオプション

キーワード Aliases 建設業者の所有物 Default 説明
Column Encryption Setting ColumnEncryption ColumnEncryptionSetting Disabled Enabled 接続時にAlways Encryptedをオンにします。
Attestation Protocol None AttestationProtocol 指定なし エンクレイブ認証プロトコル: AAS、 HGS、または None。
Enclave Attestation Url None EnclaveAttestationUrl 空 Always Encryptedの認証サービスエンドポイントで、セキュアエンクレーブを使ったものです。

ネットワークオプション

キーワード Aliases 建設業者の所有物 Default 説明
Multi Subnet Failover MultiSubnetFailover MultiSubnetFailover false サーバー名が並列で解決されるすべてのIPアドレスを試します。 可用性グループのリスナーや、TCP経由でアクセス可能なフェイルオーバークラスタインスタンスに利用してください。 データベースミラーリングには対応していません。 ネームドインスタンスはネットワークの実装によって異なります。 管理された実装は、.NETがLinuxやmacOSで使用し、マネージドネットワーキングが有効なWindows上で使用されており、名前付きインスタンスをサポートし、解決されたすべてのアドレスにSQL Serverブラウザのリクエストを並列で送信します。 Windowsのネイティブ実装では、SNIエラー48で名前付きインスタンスを拒否することができます。
IP Address Preference IPAddressPreference IPAddressPreference IPv4First 解決アドレスを試す順は IPv4First、 IPv6First、または UsePlatformDefaultです。
Packet Size PacketSize PacketSize 8000 タブラーデータストリーム(TDS)パケットサイズはバイト単位で、512から32,768までです。

プロセス全体のAppContextスイッチは、 Multi Subnet Failover デフォルトを trueに変更できます。 詳細については、 SqlClientのAppContextスイッチを参照してください。

タイムアウトの選択肢

キーワード Aliases 建設業者の所有物 Default 説明
Connect Timeout Connection Timeout、ConnectTimeout、Timeout ConnectTimeout 15 接続を待つまでの数秒、プールが満杯の接続を待つ時間も含めて。 0 無限に待つ。
Command Timeout None CommandTimeout 30 接続上で作成されたコマンドのデフォルト CommandTimeout 数秒です。 0 無限に待つ。

Connect Timeout クエリの実行を制限しません。 Command Timeout ログインやプール接続の待ち時間を制限しません。 非同期通話に CancellationToken を渡し、発信者がどちらかのタイムアウトが切れる前に待つのをやめられます。

接続復旧オプション

キーワード Aliases 建設業者の所有物 Default 説明
Connect Retry Count ConnectRetryCount ConnectRetryCount 1 最初のオープン中の予選の一時的な故障後、そして故障したアイドル接続の復旧時に再挑戦。 0 再試行をオフにする。 有効な値は 0 から 255 です。
Connect Retry Interval ConnectRetryInterval ConnectRetryInterval 10 再試しの間隔が数秒。 有効な値は1から60までです。

Connect Retry Countが1されている場合(これがデフォルト)、ドライバーはAzure SQLエンドポイントに2を使い、サーバーレスのSQLプールエンドポイントには5Azure Synapse Analytics、壊れたアイドル接続を復元します。 最初の開きは値をセットとして使うため、デフォルトでは各エンドポイントで1回の再試行が許可されています。 ドライバーは両方の場合に設定された他の値を使います。

これらのキーワードは、実行中に失敗したコマンドをリトライしません。 オープンの内蔵リトライをスキップするには、OpenWithoutRetryでOpenオーバーロードを呼び出してください。 カスタムポリシーについては 「設定可能な再試行ロジック」を参照してください。 コマンドは安全に繰り返した場合のみ再試行してください。

プーリングオプション

キーワード Aliases 建設業者の所有物 Default 説明
Pooling None Pooling true 物理接続を再利用して接続文字列をマッチングします。
Min Pool Size None MinPoolSize 0 プールが作られた後も開いたままにする物理的な接続。
Max Pool Size None MaxPoolSize 100 最も物理的な接続を一つのプールに集めます。 1 以上を指定してください。
Connection Idle Timeout None IdleTimeout 300 プールが閉じる前に接続がアイドル状態に保たれる数秒間。 0 アイドル・エクスパレーションをオフにします。 Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehavior AppContext スイッチがfalseされた場合にのみ強制されます。 既定では、これは true です。
Load Balance Timeout Connection Lifetime LoadBalanceTimeout 0 接続後の数秒単位でプールに最大年齢が戻ってきました。 古い接続は閉じられています。 0 制限をオフにする。
Pool Blocking Period PoolBlockingPeriod PoolBlockingPeriod Auto プールがキャッシュされたログイン失敗を短時間再送信するかどうか: Auto、 AlwaysBlock、または NeverBlock。 AutoAzure SQL endpoints 嘅 blocking offs を開けます。

それぞれ異なる接続文字列は独自のプールを持ちます。 プールキー、クリアリング、アイドル時間については、SQL Server接続プーリングを参照してください。

トランザクションおよびセッションオプション

キーワード Aliases 建設業者の所有物 Default 説明
Enlist None Enlist true トランザクションが開かれた際に、接続をアンビエント System.Transactions に登録します。
Transaction Binding None TransactionBinding Implicit Unbind Implicit Unbind 入会したトランザクションが終了すると接続が切り離されます。 Explicit Unbind 接続が切断されるかコードが切り離すまで、接続を保ち続けます。
Multiple Active Result Sets MultipleActiveResultSets MultipleActiveResultSets false 1つの接続で複数のアクティブなバッチを許可します。
Type System Version None TypeSystemVersion Latest ドライバーが公開するサーバータイプのシステムです。 Latest、SQL Server 2012、SQL Server 2008、SQL Server 2005を受け入れています。 Latestはそのままにしておけ。
Replication None Replication false 接続をレプリケーション接続として識別します。

.NETフレームワークのみのオプション

これらのキーワードは.NETフレームワークでのみ受け入れられています。 .NETでは、ビルダーがNotSupportedExceptionを投げ、SqlConnectionArgumentException投げます。

キーワード Aliases 建設業者の所有物 Default 説明
Network Library Net、Network NetworkLibrary 空 ネットワーク図書館。 Data Sourceでtcp:やnp:プレフィックスと組み合わせて使わないでください。接続が失敗します。 .NETでは、Data Sourceの接頭辞にtcp:またはnp:を付けてください。
Connection Reset None ConnectionReset true Obsolete.
Transparent Network IP Resolution TransparentNetworkIPResolution TransparentNetworkIPResolution true Obsolete.

サポートされていないキーワード

キーワード Result
Context Connection Context Connection=true は InvalidOperationExceptionをスローします。 Microsoft。Data.SqlClientはSQL CLRコンテキスト接続をサポートしていません。
Asynchronous Processing ArgumentException: Keyword not supported をスローします。 非同期メソッドはこの方法なしでも動作します。
Driver、Provider ArgumentException: Keyword not supported をスローします。 これらのキーワードはODBCおよびOLE DBに属しています。

検証規則

SqlConnectionStringBuilder 未知のキーワードや多くの無効な値を設定した際に却下します。 SqlConnection接続文字列を設定すると、ビルダーが受け入れる単一の値やキーワードの組み合わせなど、より多くのチェックを行います。 建築業者が受け入れた文字列でも、接続を作成した際に失敗する可能性があります。

ビルダーと接続はこれらの値を拒否します ArgumentException:

  • Connect Timeout、 Command Timeout、 Load Balance Timeout、 Connection Idle Timeout、または Min Pool Size 0未満です。
  • Max Pool Size 1点未満。
  • Packet Size 512番から32,768番まで。
  • Connect Retry Count 0から255までの外側。
  • Connect Retry Interval 1番から60番まで外側。
  • この記事には載っていないキーワードです。

SqlConnection また、ビルダーがこれらの値を受け入れていても、 ArgumentExceptionでこれらの値を拒否します。

  • Type System Version Latest、SQL Server 2012、SQL Server 2008、SQL Server 2005を除いて。
  • Transaction Binding Implicit UnbindやExplicit Unbind以外は。
  • Application Name、Current Language、Data Source、Failover Partner、Initial Catalog、Password、User ID、Workstation ID、AttachDBFilenameのTDS限界より長い値です。

SqlConnection また、これらの組み合わせを ArgumentExceptionで拒否します:

  • Min Pool Size が Max Pool Size より大きい。
  • Failover Partner Initial Catalogなし。
  • Failover PartnerでMulti Subnet Failover=true、User Instance=true、またはApplication Intent=ReadOnly。
  • Authentication と Integrated Security=true。
  • Password Active Directory Integrated、Active Directory Interactive、Active Directory Managed Identity、Active Directory MSI、Active Directory Default、またはActive Directory Workload Identityといった。
  • User IDあるいはActive Directory Device Code FlowとPassword。

オプションの変更点をレビュー

本番環境でオプションを変更する前に:

  1. 現在の接続文字列、ドライバーのバージョン、エンドポイントの種類、解決している問題を記録します。
  2. 一度に一つの選択肢を変えましょう。
  3. 接続確立、認証、証明書検証、プーリング、フェイルオーバー、キャンセル、クエリ実行のテストを行います。
  4. 接続遅延、プール待ち時間、エラー数を測定してください。
  5. すべてのデプロイ済みインスタンスで設定を確認してください。

接続文字列を変更すると新しいプールが作成されます。 段階的な展開中は、古いプールと新しいプールが同時に存在するため、サーバーへの物理接続の総数が増加する可能性があります。

関連するコンテンツ

  • 最終更新: