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

예를 들어 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 서버리스 또는 주문형 엔드포인트의 경우 기본값은 유휴 또는 일시 중지된 instance 연결에 대한 연결 성공을 개선하기 위한 5입니다. 유휴 연결 실패 후 재연결을 시도하지 않으려면 0으로 설정합니다. 허용되는 범위를 벗어나는 값으로 설정되면 ArgumentException이 발생합니다.
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 이상에서만 사용 가능)
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	애플리케이션이 다른 서브넷의 AG(AlwaysOn 가용성 그룹)에 연결 중인 경우 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입니다. 지정된 경우 제공된 이 정확히 일치하는지 ServerCertificate 확인하여 SQL Server 인증서를 확인합니다. (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에서 제공된 키에 해당하는 값을 검색합니다.