Microsoft.Data.SqlClient의 연결 옵션

Microsoft. Data.SqlClient 연결 옵션은 드라이버가 연결을 어떻게 설정, 식별, 라우팅, 재시도, 풀링하는지 제어합니다. 해당 항목을 연결 문자열에 설정하거나 해당 SqlConnectionStringBuilder 속성을 통해 설정하세요.

Microsoft Entra ID 인증에 대해서는 Microsoft Entra ID 인증을 참조하세요. TLS 설정에 대해서는 암호화 및 인증서 검증을 참조하세요.

SqlConnectionStringBuilder로 옵션 설정

연결 문자열 조각을 연결하는 대신 빌더를 사용하세요:

var builder = new SqlConnectionStringBuilder
{
    DataSource = "tcp:sql.example.com,1433",
    InitialCatalog = "Orders",
    IntegratedSecurity = true,
    Encrypt = SqlConnectionEncryptOption.Mandatory,
    ApplicationName = "Orders.Worker",
    ConnectTimeout = 30,
    ConnectRetryCount = 3,
    ConnectRetryInterval = 10,
    MultiSubnetFailover = true,
};

코드는 빌더 속성 이름을 사용합니다. 표는 일반적으로 사용되는 연결 문자열 표기를 사용합니다. 운전자는 또한 문서화된 가명을 받아들입니다.

타임아웃 옵션

키워드 Default 작동 방식 버전
Connect Timeout 15초 연결을 형성하는 데 걸리는 시간을 제한합니다. 풀이 Max Pool Size 상태일 때는 사용 가능한 풀링된 연결을 기다리는 시간도 제한됩니다. Connection Timeout와 Timeout는 별칭입니다. 모든 Microsoft. Data.Sql클라이언트 버전
Command Timeout 30초 연결과 관련된 명령어에 대한 기본 타임아웃을 설정합니다. 한 작업에 다른 제한이 필요할 경우 명령에서 CommandTimeout를 설정하세요. 의 0 값은 시간 제한이 없으며 일을 무한정 기다리게 할 수 있습니다. Microsoft. Data.SqlClient 2.1 및 이후 버전

연결 타임아웃과 명령 타임아웃은 서로 다른 작업을 측정합니다. Connect Timeout 쿼리 실행을 제한하지 않습니다. Command Timeout 인증이나 풀 연결을 기다리는 데 제한이 없습니다.

A CancellationToken 는 두 설정과 별개입니다. 호출자가 타임아웃이 만료되기 전에 대기를 중단할 수 있도록 OpenAsync, 명령 실행 및 리더 메서드에 전달하세요.

워크로드 식별 및 라우팅 옵션

키워드 Default 작동 방식 버전
Application Name 제공자 정의 이름 SQL Server 세션, 감사, 진단에서 작업 부하를 식별합니다. 배포된 각 워크로드마다 안정적이고 낮은 카디널리티 이름을 하나 사용하세요. 모든 Microsoft. Data.Sql클라이언트 버전
Application Intent ReadWrite ReadOnly 대상 및 가용성 그룹이 이에 대해 구성된 경우 읽기 의도 라우팅을 요청합니다. SQL 문을 읽기 전용으로 만들지는 않습니다. 모든 Microsoft. Data.Sql클라이언트 버전

Application Intent=ReadOnly 일반적으로 가용성 그룹 리스너나 읽기 라우팅을 지원하는 서비스 엔드포인트와 짝지어 사용됩니다. 고가용성 및 재해 복구를 참조하세요.

네트워크 및 패킷 옵션

키워드 Default 작동 방식 버전
Packet Size 8,000바이트 테이블 데이터 스트림(TDS) 네트워크 패킷 크기를 설정합니다. 지원되는 값은 512바이트부터 32,768바이트까지입니다. 워크로드 측정이나 서버 구성이 변경이 정당하지 않은 한 기본 설정을 유지하세요. 모든 Microsoft. Data.Sql클라이언트 버전
MultiSubnetFailover false 다중 주소 엔드포인트에 대해 반환된 IP 주소에 대해 병렬 TCP 연결을 시도합니다. TCP를 통해 연결되는 Azure SQL 엔드포인트, 가용성 그룹 리스너 및 장애 조치(failover) 클러스터 인스턴스의 경우 true로 설정하세요. 모든 Microsoft. Data.Sql클라이언트 버전

MultiSubnetFailover=true 명명 인스턴스, 비-TCP 프로토콜, 데이터베이스 미러링, 또는 64개 이상의 IP 주소로 구성된 엔드포인트에서는 지원되지 않습니다. 단일 IP TCP 엔드포인트에는 안전합니다.

Microsoft. Data.SqlClient 7.0에는 프로세스 전체에 걸친 AppContext 스위치도 있어 모든 연결이 .처럼 MultiSubnetFailover=true동작하도록 할 수 있습니다. 스위치가 활성화되어 있지 않을 때도 연결 문자열 기본값이 유지 false 됩니다. SqlClient의 AppContext 스위치를 참조하세요.

풀링 옵션

키워드 Default 작동 방식 버전
Pooling true 물리적 연결을 재사용하여 연결 구성을 맞추는 것입니다. 진단 목적으로만, 또는 안전하게 풀링할 수 없는 것으로 특성이 확인된 작업 부하에만 이 기능을 비활성화하세요. 모든 Microsoft. Data.Sql클라이언트 버전
Min Pool Size 0 풀이 생성된 후에도 최소 이만큼의 물리적 연결을 풀에 유지합니다. 양수 값은 풀이나 프로세스가 종료될 때까지 데이터베이스 세션을 열어둘 수 있습니다. 모든 Microsoft. Data.Sql클라이언트 버전
Max Pool Size 100 단일 풀에서 물리적 연결 수의 상한을 설정합니다. 풀이 가득 찼을 때 요청은 최대 Connect Timeout까지 대기합니다. 모든 Microsoft. Data.Sql클라이언트 버전
Load Balance Timeout 0 초 연결의 수명이 이 값을 초과하면 풀에 반환될 때 해당 연결을 폐기합니다. Connection Lifetime 는 별칭입니다. 0 연령 기반 삭제를 금지합니다. 모든 Microsoft. Data.Sql클라이언트 버전
Pool Blocking Period Auto 풀이 캐시된 로그인 실패 예외를 일시적으로 다시 발생시키는지 여부를 제어합니다. Auto인식된 Azure SQL 엔드포인트의 차단 기간을 비활성화하고 다른 엔드포인트에 대해 이를 활성화합니다. 모든 Microsoft. Data.Sql클라이언트 버전
Enlist true 자동으로 열린 연결이 대기 System.Transactions 트랜잭션에 등록됩니다. 모든 Microsoft. Data.Sql클라이언트 버전

풀 설정은 전체 프로세스나 데이터베이스 서버가 아니라 각 개별 풀에 적용됩니다. 를 올리기 Max Pool Size전에 연결과 리더가 신속히 폐기되었는지, 데이터베이스가 모든 애플리케이션 인스턴스에서 결과 합계를 수용할 수 있는지 확인하세요.

풀 키, 토큰 동작, 차단 기간, 해제 및 진단에 대해서는 SQL Server 연결 풀링을 참조하세요.

연결 복구 옵션

키워드 Default 작동 방식 버전
Connect Retry Count 1 초기 연결 중 재시도 대상이 되는 일시적 오류와 끊어진 유휴 연결을 복구할 때의 재시도 횟수를 설정합니다. 실제로 적용되는 기본값은 인식되는 Azure SQL 엔드포인트의 경우 5이고, 인식되는 Azure Synapse 및 주문형 엔드포인트의 경우 2입니다. 0 이 재시도를 비활성화합니다. 모든 Microsoft. Data.Sql클라이언트 버전
Connect Retry Interval 10초 초기 연결이나 유휴 복구 시도 전의 지연을 설정합니다. 유효 시간은 1초부터 60초까지입니다. 모든 Microsoft. Data.Sql클라이언트 버전

연결 복구 중 첫 번째 재시도는 즉시 이루어집니다. Connect Retry Interval 이후 시도 전에 적용됩니다. 특정 작업에 대해 내장된 초기 열기 재시도를 우회하려면 OpenWithoutRetry가 있는 open 오버로드를 사용하세요.

이 키워드는 실행 중에 실패한 명령을 다시 시도하지 않습니다. 사용자 지정 가능한 재시도 로직 을 사용해 사용자 지정 열기나 명령 정책을 설정하세요. 반복 명령은 효과가 안전할 때만 반복하세요.

서버 신원 및 인증서 옵션

이 옵션들은 특정 인증서 또는 케르베로스 명명 요구사항을 해결합니다. 이들은 일반적인 인증과 인증서 검증을 대체하지 않습니다.

키워드 Default 작동 방식 버전
Host Name In Certificate 서버 호스트 이름 연결이 인증서와 다른 DNS 별칭을 사용할 때 예상되는 공통명(CN) 또는 주제 대체명(SAN)을 제공합니다. Microsoft. Data.SqlClient 5.0 및 이후 버전
Server Certificate 비어 있음 Encrypt=Mandatory 또는 Encrypt=Strict인 경우 서버 인증서와 정확히 일치해야 하는 PEM, DER 또는 CER 파일을 제공합니다. Microsoft. Data.SqlClient 5.1 및 이후 버전
Server SPN 서버 이름에서 유래함 통합 인증에 사용되는 서비스 주체 이름(SPN)을 주 서버에 무시합니다. 배포된 Kerberos 명명이 명시적인 SPN을 요구할 때만 설정하세요. Microsoft. Data.SqlClient 5.0 및 이후 버전
Failover Partner SPN 페이얼오버 파트너에서 파생됨 데이터베이스 미러링 페일오버 파트너의 SPN을 덮어씁니다. 데이터베이스 미러링은 더 이상 지원되지 않습니다. 새로운 배포에는 가용성 그룹을 사용하세요. Microsoft. Data.SqlClient 5.0 및 이후 버전

Host Name In Certificate 인증서 매칭에 사용되는 이름이 변경됩니다. 신뢰할 수 없는 발행사는 신뢰하지 않습니다. Server Certificate 정확한 인증서 파일을 고정하고, 인증서가 회전할 때 애플리케이션 업데이트를 요구합니다.

잘못된 SPN 오버라이드는 Kerberos 인증을 방해하거나 의도한 신원 확인을 약화시킬 수 있습니다. 가능하면 오버라이드 대신 DNS와 SPN 등록을 수정하세요.

연결 줄은 작게 유지하세요. 어떤 동작이 변하는지, 그리고 작업 부하가 그 동작을 어떻게 검증하는지 지정할 수 있을 때만 옵션을 추가하세요.

옵션 변경 사항 검토

프로덕션 옵션에 변경하기 전에:

  1. 현재 연결 문자열, 드라이버 버전, 엔드포인트 유형, 그리고 관찰된 문제를 기록하세요.
  2. 한 번에 한 가지 행동을 바꾸세요.
  3. 연결 설정, 인증, 인증서 검증, 풀링, 장애 조치, 취소, 쿼리 실행을 테스트합니다.
  4. 하드 커넥팅, 풀 대기, 연결 지연, 오류 수치를 측정하세요.
  5. 모든 배포된 인스턴스에서 설정을 확인하세요.

연결 문자열은 풀 키의 일부입니다. 단계적 롤아웃은 일시적으로 구와 새 풀을 모두 생성할 수 있어 물리적 데이터베이스 연결 수를 증가시킵니다.

관련 콘텐츠

  • Last updated on