SqlConnectionStringBuilder 클래스

정의

네임스페이스:

Microsoft.Data.SqlClient

어셈블리:

Microsoft.Data.SqlClient.dll

Package(패키지):

Microsoft.Data.SqlClient v7.1.0

SqlConnection 클래스에서 사용하는 연결 문자열의 콘텐츠를 만들고 관리하는 간단한 방법을 제공합니다.

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

[System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))]
public sealed class SqlConnectionStringBuilder : System.Data.Common.DbConnectionStringBuilder

[<System.ComponentModel.TypeConverter(typeof(Microsoft.Data.SqlClient.SqlConnectionStringBuilder+SqlConnectionStringBuilderConverter))>]
type SqlConnectionStringBuilder = class
    inherit DbConnectionStringBuilder

Public NotInheritable Class SqlConnectionStringBuilder
Inherits DbConnectionStringBuilder

상속

DbConnectionStringBuilder

SqlConnectionStringBuilder

특성

TypeConverterAttribute

예제

다음 콘솔 애플리케이션은 SQL Server 데이터베이스에 대한 연결 문자열을 빌드합니다. 이 코드는 클래스를 SqlConnectionStringBuilder 사용하여 연결 문자열 만든 다음 인스턴스의 SqlConnectionStringBuilder 속성을 연결 클래스의 생성자에 전달합니다ConnectionString. 또한 이 예제에서는 기존 연결 문자열 구문 분석하고 연결 문자열 내용을 조작하는 다양한 방법을 보여 줍니다.

메모

이 예제에는 연결 문자열의 작동 방식을 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=********;initial catalog=AdventureWorks";

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

        // 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 키/값 쌍에 대한 검사를 수행합니다. 따라서 이 클래스를 사용하여 잘못된 연결 문자열을 만들 수 없습니다. 잘못된 쌍을 추가하려고 하면 예외가 throw됩니다. 클래스는 고정된 동의어 컬렉션을 유지 관리하며 동의어에서 잘 알려진 해당 키 이름으로 변환할 수 있습니다.

예를 들어 Item 속성을 사용하여 값을 검색하는 경우 필요한 키의 동의어를 포함하는 문자열을 지정할 수 있습니다. 예를 들어 Item 속성 Remove 또는 메서드와 같이 키 이름이 포함된 문자열이 필요한 멤버를 사용할 경우 연결 문자열 내에서 이 키에 대해 "네트워크 주소", "addr" 또는 기타 허용되는 동의어를 지정할 수 있습니다. 허용되는 동의어의 전체 목록은 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  

생성자

속성	Description
SqlConnectionStringBuilder()	SqlConnectionStringBuilder 클래스의 새 인스턴스를 초기화합니다.
SqlConnectionStringBuilder(String)	SqlConnectionStringBuilder 클래스의 새 인스턴스를 초기화합니다. 제공된 연결 문자열은 인스턴스의 내부 연결 정보에 대한 데이터를 제공합니다.

속성

속성	Description
ApplicationIntent	SQL Server 가용성 그룹의 데이터베이스에 연결할 때 애플리케이션 워크로드 유형을 선언합니다. ApplicationIntent사용하여 이 속성의 값을 설정할 수 있습니다. Always On 가용성 그룹에 대한 SqlClient 지원에 관한 자세한 내용은 고가용성 및 재해 복구에 대한 SqlClient 지원을 참조하세요.
ApplicationName	연결 문자열과 연결된 애플리케이션의 이름을 가져오거나 설정합니다.
AttachDBFilename	기본 데이터 파일의 이름을 포함하는 문자열을 가져오거나 설정합니다. 여기에는 연결 가능한 데이터베이스의 전체 경로 이름이 포함됩니다.
AttestationProtocol	증명 프로토콜의 값을 가져오거나 설정합니다.
Authentication	리소스를 Azure SQL 위해 Microsoft Entra 연결에 사용되는 인증 방법을 가져오거나 설정합니다.
ColumnEncryptionSetting	연결 문자열 작성기에서 열 암호화 설정을 가져오거나 설정합니다.
CommandTimeout	명령 실행 시도를 종료하고 오류를 생성하기 전의 기본 대기 시간(초)입니다. 기본값은 30초입니다.
ConnectionReset	사용되지 않음. Obsolete. 연결 풀에서 그릴 때 연결이 다시 설정되는지 여부를 나타내는 부울 값을 가져오거나 설정합니다.
ConnectRetryCount	유휴 연결 오류가 있음을 확인한 후 시도한 다시 연결 수입니다. 0에서 255 사이의 정수여야 합니다. 비 Azure 엔드포인트의 기본값은 1입니다. Azure SQL 엔드포인트의 경우 기본값은 2입니다. 버전 5.x부터 Azure SQL 서버리스 또는 주문형 엔드포인트의 경우 기본값은 유휴 또는 일시 중지된 인스턴스에 대한 연결의 연결 성공을 개선하기 위한 5입니다. 유휴 연결 실패 시 다시 연결을 사용하지 않도록 설정하려면 0으로 설정합니다. ArgumentException 허용되는 범위를 벗어난 값으로 설정하면 throw됩니다.
ConnectRetryInterval	유휴 연결 오류가 있음을 확인한 후 각 다시 연결 시도 사이의 시간(초)입니다. 1에서 60 사이의 정수여야 합니다. 기본값은 10초입니다.
ConnectTimeout	시도를 종료하고 오류를 생성하기 전에 서버에 대한 연결을 기다리는 시간(초)을 가져오거나 설정합니다.
CurrentLanguage	데이터베이스 서버 경고 또는 오류 메시지에 사용되는 언어를 가져오거나 설정합니다.
DataSource	연결할 SQL Server 인스턴스의 이름 또는 네트워크 주소를 가져오거나 설정합니다.
EnclaveAttestationUrl	Enclave 기반 Always Encrypted와 함께 사용할 enclave 증명 URL을 가져오거나 설정합니다.
Encrypt	버전 5.0 이후의 값 또는 Boolean 클라이언트와 서버 간에 전송된 모든 데이터에 TLS 암호화가 필요한지 여부를 나타내는 이전 버전의 값을 가져오거나 설정합니다SqlConnectionEncryptOption.
Enlist	SQL Server 연결 풀이 생성 스레드의 현재 트랜잭션 컨텍스트에서 연결을 자동으로 등록하는지 여부를 나타내는 부울 값을 가져오거나 설정합니다.
FailoverPartner	주 서버가 다운된 경우 연결할 파트너 서버의 이름 또는 주소를 가져오거나 설정합니다.
FailoverPartnerSPN	연결에 대한 장애 조치(failover) 파트너의 SPN(서비스 사용자 이름)을 가져오거나 설정합니다.
HostNameInCertificate	연결에 대한 서버 인증서의 유효성을 검사할 때 사용할 호스트 이름을 가져오거나 설정합니다. 지정하지 않으면 인증서 유효성 검사에 Data Source 서버 이름이 사용됩니다. (v5.0 이상에서만 사용 가능)
IdleTimeout	연결이 삭제되기 전에 연결 풀에서 사용하지 않고 유휴 상태로 앉을 수 있는 최대 시간(초)을 가져오거나 설정합니다. 기본값은 300(5분)입니다.
InitialCatalog	연결과 연결된 데이터베이스의 이름을 가져오거나 설정합니다.
IntegratedSecurity	연결에 사용자 ID와 암호가 지정되었는지(시기 false ) 또는 현재 Windows 계정 자격 증명이 인증에 사용되는지(시기 true ) 여부를 나타내는 부울 값을 가져오거나 설정합니다.
IPAddressPreference	TCP 연결을 설정할 때 IP 주소 패밀리 기본 설정을 가져오거나 설정합니다.
IsFixedSize	SqlConnectionStringBuilder 고정 크기인지 여부를 나타내는 값을 가져옵니다.
Item[String]	지정된 키와 연결된 값을 가져오거나 설정합니다. C#에서 이 속성은 인덱서입니다.
Keys	에 ICollection 있는 키가 들어 있는 SqlConnectionStringBuilder키를 가져옵니다.
LoadBalanceTimeout	연결이 소멸되기 전에 연결 풀에 있는 최소 시간(초)을 가져오거나 설정합니다.
MaxPoolSize	이 특정 연결 문자열에 대해 연결 풀에 허용되는 최대 연결 수를 가져오거나 설정합니다.
MinPoolSize	이 특정 연결 문자열에 대해 연결 풀에 허용되는 최소 연결 수를 가져오거나 설정합니다.
MultipleActiveResultSets	true이면 애플리케이션이 MARS(여러 활성 결과 집합)를 유지할 수 있습니다. false이면 애플리케이션이 한 일괄 처리의 모든 결과 집합을 처리하거나 취소해야 해당 연결에서 다른 일괄 처리를 실행할 수 있습니다. 자세한 내용은 MARS(다중 활성 결과 집합)를 참조하세요.
MultiSubnetFailover	애플리케이션이 다른 서브넷의 AlwaysOn AG(가용성 그룹)에 연결하는 경우 설정 MultiSubnetFailover=true 은 (현재) 활성 서버에 대한 빠른 검색 및 연결을 제공합니다. Always On 가용성 그룹에 대한 SqlClient 지원에 관한 자세한 내용은 고가용성 및 재해 복구에 대한 SqlClient 지원을 참조하세요.
NetworkLibrary	SQL Server에 대한 연결을 설정하는 데 사용되는 네트워크 라이브러리의 이름을 포함하는 문자열을 가져오거나 설정합니다.
PacketSize	SQL Server 인스턴스와 통신하는 데 사용되는 네트워크 패킷의 크기(바이트)를 가져오거나 설정합니다.
Password	SQL Server 계정의 암호를 가져오거나 설정합니다.
PersistSecurityInfo	암호 또는 액세스 토큰과 같은 보안에 중요한 정보가 해당 연결이 열린 상태가 된 후 생성된 SqlConnectionStringBuilder 연결에서 연결 문자열 일부로 반환되어야 하는지 여부를 나타내는 부울 값을 가져오거나 설정합니다. 이 속성은 애플리케이션이 이미 열려 있는 데이터베이스 연결에서 암호를 읽어야 하는 경우에만 설정 true 해야 합니다. 기본값 false 은 더 안전한 설정입니다. 이 속성을 사용하면 true 실수로 데이터베이스 암호를 로깅하거나 추적하는 등의 보안 위험에 애플리케이션이 열립니다.
PoolBlockingPeriod	연결 풀에 대한 차단 기간 동작입니다.
Pooling	연결이 요청될 때마다 연결을 풀하거나 명시적으로 열지 여부를 나타내는 부울 값을 가져오거나 설정합니다.
Replication	연결을 사용하여 복제가 지원되는지 여부를 나타내는 부울 값을 가져오거나 설정합니다.
ServerCertificate	연결에 대한 SQL Server TLS/SSL 인증서와 일치하는 인증서 파일의 경로를 가져오거나 설정합니다. 허용되는 인증서 형식은 PEM, DER 및 CER입니다. 지정된 경우 제공된 인증서가 정확히 일치하는지 ServerCertificate 확인하여 SQL Server 인증서를 확인합니다. (v5.1 이상에서만 사용 가능)
ServerSPN	데이터 원본의 SPN(서비스 사용자 이름)을 가져오거나 설정합니다.
TransactionBinding	연결이 인리스트먼트된 System.Transactions 트랜잭션과의 연결을 유지하는 방법을 나타내는 문자열 값을 가져오거나 설정합니다.
TransparentNetworkIPResolution	사용되지 않음. .NET Framework에서 이 키의 값이 설정된 true경우 드라이버는 연결이 성공하거나 전체에 Connect Timeout 도달할 때까지 순차 모드 시도에서 시도당 시간 제한 및 최소 500ms를 사용하여 DNS로 확인된 IP 주소에서 여러 연결 라운드를 실행합니다.
TrustServerCertificate	트러스트의 유효성을 검사하기 위해 인증서 체인을 건너뛰는 동안 채널이 암호화되는지 여부를 나타내는 값을 가져오거나 설정합니다.
TypeSystemVersion	애플리케이션에서 예상하는 형식 시스템을 나타내는 문자열 값을 가져오거나 설정합니다.
UserID	SQL Server에 연결할 때 사용할 사용자 ID를 가져오거나 설정합니다.
UserInstance	기본 SQL Server Express 인스턴스에서 호출자의 계정으로 실행되는 런타임 시작 인스턴스로 연결을 리디렉션할지 여부를 나타내는 값을 가져오거나 설정합니다.
Values	에 ICollection 있는 값이 들어 있는 SqlConnectionStringBuilder 값을 가져옵니다.
WorkstationID	SQL Server에 연결하는 워크스테이션의 이름을 가져오거나 설정합니다.

메서드

속성	Description
Clear()	인스턴스의 SqlConnectionStringBuilder 내용을 지웁니다.
ContainsKey(String)	SqlConnectionStringBuilder 특정 키가 포함되어 있는지 여부를 확인합니다.
Remove(String)	SqlConnectionStringBuilder 인스턴스에서 지정된 키가 있는 항목을 제거합니다.
ShouldSerialize(String)	지정된 키가 이 SqlConnectionStringBuilder 인스턴스에 있는지 여부를 나타냅니다.
TryGetValue(String, Object)	이 키에서 SqlConnectionStringBuilder 제공된 키에 해당하는 값을 검색합니다.