SqlConnectionStringBuilder クラス

定義

名前空間:

System.Data.SqlClient

アセンブリ:

System.Data.SqlClient.dll

パッケージ:

System.Data.SqlClient v4.8.6

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

継承

Object

DbConnectionStringBuilder

SqlConnectionStringBuilder

例

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

注意

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

using System.Data;
using System.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";
        builder.AsynchronousProcessing = true;

        // 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";
    }
}

Imports System.Data.SqlClient

Module Module1
    Sub Main()
        ' Create a new SqlConnectionStringBuilder and
        ' initialize it with a few name/value pairs:
        Dim builder As 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"
        builder.AsynchronousProcessing = True

        ' 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

        ' The Item property is the default for the class, 
        ' and setting the Item property adds the value to the 
        ' dictionary, if necessary. 
        builder.Item("Trusted_Connection") = True
        Console.WriteLine(builder.ConnectionString)

        Console.WriteLine("Press Enter to finish.")
        Console.ReadLine()
    End Sub

    Private Function GetConnectionString() As String
        ' 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"
    End Function
End Module

注釈

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

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

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

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

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

System.Data.SqlClient.SqlConnectionStringBuilder builder =
  new System.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	プライマリ データ ファイルの名前を表す文字列を取得または設定します。 この文字列には、アタッチ可能なデータベースの完全パス名が含まれています。
BrowsableConnectionString	ConnectionString プロパティを Visual Studio デザイナーに表示するかどうかを示す値を取得または設定します。 (継承元 DbConnectionStringBuilder)
ConnectionString	DbConnectionStringBuilder に関連付けられた接続文字列を取得または設定します。 (継承元 DbConnectionStringBuilder)
ConnectRetryCount	アイドル状態の接続エラーが発生したことが特定された後で試みられた再接続の回数。 この値は 0 から 255 までの整数でなくてはなりません。 既定値は 1 です。 0 に設定すると、アイドル状態の接続エラーが発生した場合、再接続は行われません。 許容範囲外の値が設定された場合は ArgumentException がスローされます。
ConnectRetryInterval	アイドル状態の接続エラーが発生したことが特定された後で、再接続を試行する時間間隔 (秒単位)。 この値は 1 から 60 までの整数でなくてはなりません。 既定は 10 秒です。 許容範囲外の値が設定された場合は ArgumentException がスローされます。
ConnectTimeout	サーバーへの接続を待機する時間の長さ (秒単位) を取得または設定します。この時間が経過すると、接続の試行が終了し、エラーが生成されます。
Count	ConnectionString プロパティ内に含まれる現在のキー数を取得します。 (継承元 DbConnectionStringBuilder)
CurrentLanguage	SQL Server Language レコード名を取得または設定します。
DataSource	接続する先の SQL Server インスタンスの名前またはネットワーク アドレスを取得または設定します。
Encrypt	サーバーに証明書がインストールされている場合に、クライアントとサーバーの間で送信されるすべてのデータに SQL Server が SSL 暗号化を使用するかどうかを示すブール値を取得または設定します。
Enlist	SQL Server の接続プーラーが、作成スレッドの現在のトランザクション コンテキストに、接続を自動的に登録するかどうかを示すブール値を取得または設定します。
FailoverPartner	プライマリ サーバーがダウンした場合に接続先となるパートナー サーバーの名前またはアドレスを取得または設定します。
InitialCatalog	接続に関連付けられたデータベースの名前を取得または設定します。
IntegratedSecurity	User ID および Password を接続文字列中に指定するか (false の場合)、現在の Windows アカウントの資格情報を認証に使用するか (true の場合) を示すブール値を取得または設定します。
IsFixedSize	DbConnectionStringBuilder が固定サイズかどうかを示す値を取得します。 (継承元 DbConnectionStringBuilder)
IsReadOnly	DbConnectionStringBuilder が読み取り専用かどうかを示す値を取得します。 (継承元 DbConnectionStringBuilder)
Item[String]	指定されたキーに関連付けられている値を取得または設定します。 C# の場合、このプロパティはインデクサーです。
Keys	ICollection 内のキーが格納されている SqlConnectionStringBuilder を取得します。
LoadBalanceTimeout	接続プールに維持されている接続が破棄されるまでの最短時間 (秒単位) を取得または設定します。
MaxPoolSize	特定の接続文字列について、接続プール内で許可される最大接続数を取得または設定します。
MinPoolSize	特定の接続文字列について、接続プール内で許可される最小接続数を取得または設定します。
MultipleActiveResultSets	true の場合、アプリケーションは複数のアクティブな結果セット (MARS) を保持できます。 false の場合、その接続で他のバッチを実行するには、その前にアプリケーションは 1 つのバッチからのすべての結果セットを処理するか、取り消す必要があります。 詳細については、「 複数のアクティブな結果セット (MARS)」を参照してください。
MultiSubnetFailover	アプリケーションが異なるサブネット上のAlways On可用性グループ (AG) またはAlways On フェールオーバー クラスター インスタンス (FCI) に接続している場合、MultiSubnetFailover=true を設定すると、(現在) アクティブなサーバーの検出と接続が高速化されます。 Always On機能に対する SqlClient サポートの詳細については、「SqlClient での高可用性のサポート、ディザスター リカバリー」を参照してください。
PacketSize	SQL Server のインスタンスと通信するために使用されるネットワーク パケットのサイズ (バイト単位) を取得または設定します。
Password	SQL Server アカウントのパスワードを取得または設定します。
PersistSecurityInfo	パスワードやアクセス トークンなどのセキュリティに依存する情報を、このSqlConnectionStringBuilder接続が開いている状態になった後に作成された接続の接続文字列の一部として返す必要があるかどうかを示す値を取得または設定します。
Pooling	接続をプールするか、接続要求ごとに明示的に接続を開くかを示すブール値を取得または設定します。
Replication	この接続を使用したレプリケーションをサポートするかどうかを示すブール値を取得または設定します。
TransactionBinding	登録された System.Transactions トランザクションとの関連付けを接続でどのように維持するかを示す文字列値を取得または設定します。
TrustServerCertificate	信頼関係を検証するために証明書チェーンを順に調べる処理をバイパスして、チャネルを暗号化するかどうかを示す値を取得または設定します。
TypeSystemVersion	アプリケーションで想定される型システムを表す文字列値を取得または設定します。
UserID	SQL Server との接続時に使用されるユーザー ID を取得または設定します。
UserInstance	SQL Server Express の既定のインスタンスから、ランタイムによって開始され呼び出し元のアカウントで実行されるインスタンスに、接続をリダイレクトするかどうかを示す値を取得または設定します。
Values	ICollection 内の値を格納している SqlConnectionStringBuilder を取得します。
WorkstationID	SQL Server に接続するワークステーションの名前を取得または設定します。

メソッド

Add(String, Object)	指定したキーおよび値を持つエントリを DbConnectionStringBuilder に追加します。 (継承元 DbConnectionStringBuilder)
Clear()	SqlConnectionStringBuilder インスタンスの内容を消去します。
ClearPropertyDescriptors()	関連する DbConnectionStringBuilder 上の PropertyDescriptor オブジェクトのコレクションをクリアします。 (継承元 DbConnectionStringBuilder)
ContainsKey(String)	SqlConnectionStringBuilder に特定のキーが格納されているかどうかを判断します。
Equals(Object)	指定されたオブジェクトが現在のオブジェクトと等しいかどうかを判断します。 (継承元 Object)
EquivalentTo(DbConnectionStringBuilder)	この DbConnectionStringBuilder オブジェクトの接続情報を、提供されたオブジェクトの接続情報を比較します。 (継承元 DbConnectionStringBuilder)
GetHashCode()	既定のハッシュ関数として機能します。 (継承元 Object)
GetProperties(Hashtable)	指定された Hashtable に、この DbConnectionStringBuilder のすべてのプロパティに関する情報を格納します。 (継承元 DbConnectionStringBuilder)
GetType()	現在のインスタンスの Type を取得します。 (継承元 Object)
MemberwiseClone()	現在の Object の簡易コピーを作成します。 (継承元 Object)
Remove(String)	指定されたキーを持つエントリを SqlConnectionStringBuilder インスタンスから削除します。
ShouldSerialize(String)	指定されたキーが、この SqlConnectionStringBuilder インスタンスに存在するかどうかを示します。
ToString()	DbConnectionStringBuilder に関連付けられた接続文字列を返します。 (継承元 DbConnectionStringBuilder)
TryGetValue(String, Object)	提供されたキーに対応する値をこの SqlConnectionStringBuilder から取得します。

拡張メソッド

こちらもご覧ください

• 接続文字列 (ADO.NET)
• ADO.NET の概要