SqlConnectionStringBuilder クラス

定義

名前空間:

Microsoft.Data.SqlClient

アセンブリ:

Microsoft.Data.SqlClient.dll

パッケージ:

Microsoft.Data.SqlClient v5.2.0

SqlConnection クラスで使用される接続文字列の内容を簡単に作成および管理するための手段を提供します。

public ref class SqlConnectionStringBuilder sealed : System::Data::Common::DbConnectionStringBuilder

public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

継承

DbConnectionStringBuilder

SqlConnectionStringBuilder

例

次のコンソール アプリケーションは、SQL Server データベースの接続文字列をビルドします。 このコードでは、SqlConnectionStringBuilder クラスを使用して接続文字列を作成し、ConnectionString インスタンスの SqlConnectionStringBuilder プロパティを接続クラスのコンストラクターに渡します。 この例では、既存の接続文字列の解析も行い、接続文字列の内容を操作するさまざまな方法を示しています。

注意

この例には、SqlConnectionStringBuilder による接続文字列の操作方法を示すために、パスワードが含まれています。 実際のアプリケーションでは、Windows 認証を使用することをお勧めします。 パスワードを使用する必要がある場合も、ハードコードされたパスワードをアプリケーションに含めないでください。

using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Create a new SqlConnectionStringBuilder and
        // initialize it with a few name/value pairs.
        SqlConnectionStringBuilder builder =
            new SqlConnectionStringBuilder(GetConnectionString());

        // The input connection string used the 
        // Server key, but the new connection string uses
        // the well-known Data Source key instead.
        Console.WriteLine(builder.ConnectionString);

        // Pass the SqlConnectionStringBuilder an existing 
        // connection string, and you can retrieve and
        // modify any of the elements.
        builder.ConnectionString = "server=(local);user id=ab;" +
            "password= a!Pass113;initial catalog=AdventureWorks";

        // Now that the connection string has been parsed,
        // you can work with individual items.
        Console.WriteLine(builder.Password);
        builder.Password = "new@1Password";

        // You can refer to connection keys using strings, 
        // as well. When you use this technique (the default
        // Item property in Visual Basic, or the indexer in C#),
        // you can specify any synonym for the connection string key
        // name.
        builder["Server"] = ".";
        builder["Connect Timeout"] = 1000;
        builder["Trusted_Connection"] = true;
        Console.WriteLine(builder.ConnectionString);

        Console.WriteLine("Press Enter to finish.");
        Console.ReadLine();
    }

    private static string GetConnectionString()
    {
        // To avoid storing the connection string in your code,
        // you can retrieve it from a configuration file. 
        return "Server=(local);Integrated Security=SSPI;" +
            "Initial Catalog=AdventureWorks";
    }
}

注釈

接続文字列ビルダーを使用すると、開発者はこのクラスのプロパティおよびメソッドを使用することによって、正しい構文の接続文字列をプログラムで作成し、既存の接続文字列の解析や再作成を行うことができます。 接続文字列ビルダーは、SQL Server で許可される既知のキー/値ペアに対応する厳密に型指定されたプロパティを提供します。 アプリケーションの一部として接続文字列を作成する必要がある開発者は、SqlConnectionStringBuilder クラスを使用して接続文字列を作成および変更できます。 また、このクラスを使用すると、アプリケーションの構成ファイルに保存された接続文字列を容易に管理することができます。

SqlConnectionStringBuilder では、有効なキー/値ペアのチェックが行われます。 このため、このクラスを使用して無効な接続文字列を作成することはできません。無効なペアを追加しようとすると、例外がスローされます。 このクラスでは、あらかじめ決められた一連のシノニムを管理しており、特定のシノニムを対応する既知のキー名に変換することができます。

たとえば、 Item プロパティを使用して値を取得する場合、必要なキーのシノニムを含む文字列を指定できます。 たとえば、Item プロパティや メソッドなどのキー名を含む文字列を必要とするメンバーを使用する場合は、接続文字列内でこのキーに対して "ネットワーク アドレス"、"addr"、またはそのRemove他の許容されるシノニムを指定できます。 使用可能なシノニムの一覧については、ConnectionString プロパティのトピックを参照してください。

Item プロパティハンドルは、悪意のあるエントリの挿入を試みます。 たとえば、次のコードでは、既定の Item プロパティ (C# の場合はインデクサー) を使用して、入れ子になったキー/値ペアのエスケープを正しく行っています。

Dim builder As New Microsoft.Data.SqlClient.SqlConnectionStringBuilder  
builder("Data Source") = "(local)"  
builder("Integrated Security") = True  
builder("Initial Catalog") = "AdventureWorks;NewValue=Bad"  
Console.WriteLine(builder.ConnectionString)  

Microsoft.Data.SqlClient.SqlConnectionStringBuilder builder =  
  new Microsoft.Data.SqlClient.SqlConnectionStringBuilder();  
builder["Data Source"] = "(local)";  
builder["Integrated Security"] = true;  
builder["Initial Catalog"] = "AdventureWorks;NewValue=Bad";  
Console.WriteLine(builder.ConnectionString);  

結果は、無効な値が安全に処理される、次の接続文字列になります。

Source=(local);Initial Catalog="AdventureWorks;NewValue=Bad";  
Integrated Security=True  

コンストラクター

SqlConnectionStringBuilder()	SqlConnectionStringBuilder クラスの新しいインスタンスを初期化します。
SqlConnectionStringBuilder(String)	SqlConnectionStringBuilder クラスの新しいインスタンスを初期化します。 指定された接続文字列によって、インスタンスの内部的な接続情報のデータが提供されます。

プロパティ

ApplicationIntent	SQL Server 可用性グループ内のデータベースに接続する際の、アプリケーション ワークロードの種類を宣言します。 このプロパティの値は、ApplicationIntent を使用して設定できます。 Always On 可用性グループの SqlClient サポートの詳細については、「高可用性障害復旧のための SqlClient サポート」をご覧ください。
ApplicationName	接続文字列に関連付けられたアプリケーションの名前を取得または設定します。
AttachDBFilename	プライマリ データ ファイルの名前を表す文字列を取得または設定します。 この文字列には、アタッチ可能なデータベースの完全パス名が含まれています。
AttestationProtocol	構成証明プロトコルの値を取得または設定します。
Authentication	Azure Active Directory 認証を使用してSQL Databaseに接続するために使用する認証方法を取得または設定します。
ColumnEncryptionSetting	接続文字列ビルダーの列暗号化設定を取得および設定します。
CommandTimeout	コマンドの実行試行を終了してエラーを生成するまでの既定の待機時間 (秒単位)。 既定値は 30 秒です。
ConnectRetryCount	アイドル状態の接続エラーが発生したことが特定された後で試みられた再接続の回数。 この値は 0 から 255 までの整数でなくてはなりません。 Azure 以外のエンドポイントの既定値は 1 です。 Azure SQL エンドポイントの場合、既定値は 2 です。 バージョン 5.x 以降では、Azure SQLサーバーレス エンドポイントまたはオンデマンド エンドポイントの場合、アイドル状態または一時停止中のインスタンスへの接続の成功を向上させるために、既定値は 5 です。 0 に設定すると、アイドル状態の接続エラーが発生した場合、再接続は行われません。 許容範囲外の値が設定された場合は ArgumentException がスローされます。
ConnectRetryInterval	アイドル状態の接続エラーが発生したことが特定された後で、再接続を試行する時間間隔 (秒単位)。 この値は 1 から 60 までの整数でなくてはなりません。 既定は 10 秒です。
ConnectTimeout	サーバーへの接続を待機する時間の長さ (秒単位) を取得または設定します。この時間が経過すると、接続の試行が終了し、エラーが生成されます。
CurrentLanguage	データベース サーバーの警告またはエラー メッセージに使用される言語を取得または設定します。
DataSource	接続する先の SQL Server インスタンスの名前またはネットワーク アドレスを取得または設定します。
EnclaveAttestationUrl	エンクレーブ ベースのAlways Encryptedで使用するエンクレーブ構成証明 URL を取得または設定します。
Encrypt	バージョン 5.0 以降の値、またはBooleanクライアントとサーバーの間で送信されるすべてのデータに TLS 暗号化が必要かどうかを示す以前のバージョンの値を取得または設定SqlConnectionEncryptOptionします。
Enlist	SQL Server の接続プーラーが、作成スレッドの現在のトランザクション コンテキストに、接続を自動的に登録するかどうかを示すブール値を取得または設定します。
FailoverPartner	プライマリ サーバーがダウンした場合に接続先となるパートナー サーバーの名前またはアドレスを取得または設定します。
FailoverPartnerSPN	接続のフェールオーバー パートナーのサービス プリンシパル名 (SPN) を取得または設定します。
HostNameInCertificate	接続のサーバー証明書を検証するときに使用するホスト名を取得または設定します。 指定しない場合は、 のサーバー名 Data Source が証明書の検証に使用されます。 (v5.0 以降でのみ使用可能)
InitialCatalog	接続に関連付けられたデータベースの名前を取得または設定します。
IntegratedSecurity	User ID および Password を接続文字列中に指定するか (false の場合)、現在の Windows アカウントの資格情報を認証に使用するか (true の場合) を示すブール値を取得または設定します。
IPAddressPreference	TCP 接続を確立するときの IP アドレス ファミリの基本設定を取得または設定します。
IsFixedSize	SqlConnectionStringBuilder が固定サイズかどうかを示す値を取得します。
Item[String]	指定されたキーに関連付けられている値を取得または設定します。 C# の場合、このプロパティはインデクサーです。
Keys	ICollection 内のキーが格納されている SqlConnectionStringBuilder を取得します。
LoadBalanceTimeout	接続プールに維持されている接続が破棄されるまでの最短時間 (秒単位) を取得または設定します。
MaxPoolSize	特定の接続文字列について、接続プール内で許可される最大接続数を取得または設定します。
MinPoolSize	特定の接続文字列について、接続プール内で許可される最小接続数を取得または設定します。
MultipleActiveResultSets	true の場合、アプリケーションは複数のアクティブな結果セット (MARS) を保持できます。 false の場合、その接続で他のバッチを実行するには、その前にアプリケーションは 1 つのバッチからのすべての結果セットを処理するか、取り消す必要があります。 詳細については、「 複数のアクティブな結果セット (MARS)」を参照してください。
MultiSubnetFailover	アプリケーションが異なるサブネット上の AlwaysOn 可用性グループ (AG) に接続している場合、MultiSubnetFailover=true に設定すると、(現在) アクティブなサーバーの検出と接続が速くなります。 Always On 可用性グループの SqlClient サポートの詳細については、「高可用性障害復旧のための SqlClient サポート」をご覧ください。
PacketSize	SQL Server のインスタンスと通信するために使用されるネットワーク パケットのサイズ (バイト単位) を取得または設定します。
Password	SQL Server アカウントのパスワードを取得または設定します。
PersistSecurityInfo	パスワードやアクセス トークンなどのセキュリティに依存する情報を、このSqlConnectionStringBuilder接続が開いている状態になった後に作成された接続の接続文字列の一部として返す必要があるかどうかを示すブール値を取得または設定します。 このプロパティは、アプリケーションが既に開いているデータベース接続からパスワードを読み取る必要がある場合にのみ に true 設定する必要があります。 の既定値 false は、より安全な設定です。このプロパティに を使用すると true 、誤ってデータベース パスワードをログに記録したりトレースしたりするなどのセキュリティ 上のリスクがアプリケーションに表示されます。
PoolBlockingPeriod	接続プールのブロック期間の動作。
Pooling	接続をプールするか、接続要求ごとに明示的に接続を開くかを示すブール値を取得または設定します。
Replication	この接続を使用したレプリケーションをサポートするかどうかを示すブール値を取得または設定します。
ServerCertificate	接続のSQL Server TLS/SSL 証明書と照合する証明書ファイルへのパスを取得または設定します。 受け付けられる証明書の形式は PEM、DER、CER です。 指定した場合、SQL Server証明書は、指定された が完全に一致しているかどうかをServerCertificate確認することによって確認されます。 (v5.1 以降でのみ使用可能)
ServerSPN	データ ソースのサービス プリンシパル名 (SPN) を取得または設定します。
TransactionBinding	登録された System.Transactions トランザクションとの関連付けを接続でどのように維持するかを示す文字列値を取得または設定します。
TrustServerCertificate	信頼関係を検証するために証明書チェーンを順に調べる処理をバイパスして、チャネルを暗号化するかどうかを示す値を取得または設定します。
TypeSystemVersion	アプリケーションで想定される型システムを表す文字列値を取得または設定します。
UserID	SQL Server との接続時に使用されるユーザー ID を取得または設定します。
UserInstance	SQL Server Express の既定のインスタンスから、ランタイムによって開始され呼び出し元のアカウントで実行されるインスタンスに、接続をリダイレクトするかどうかを示す値を取得または設定します。
Values	ICollection 内の値を格納している SqlConnectionStringBuilder を取得します。
WorkstationID	SQL Server に接続するワークステーションの名前を取得または設定します。

メソッド

Clear()	SqlConnectionStringBuilder インスタンスの内容を消去します。
ContainsKey(String)	SqlConnectionStringBuilder に特定のキーが格納されているかどうかを判断します。
Remove(String)	指定されたキーを持つエントリを SqlConnectionStringBuilder インスタンスから削除します。
ShouldSerialize(String)	指定されたキーが、この SqlConnectionStringBuilder インスタンスに存在するかどうかを示します。
TryGetValue(String, Object)	提供されたキーに対応する値をこの SqlConnectionStringBuilder から取得します。