적용 대상: 
.NET Framework .NET .NET Standard
AppContext 클래스를 통해 SqlClient는 이전 동작에 의존하는 호출자를 계속 지원하면서 새 기능을 제공할 수 있습니다. 사용자는 특정 AppContext 스위치를 설정하여 동작 변경을 옵트아웃할 수 있습니다.
기본적으로 MultiSubnetFailover 사용
적용 대상: .NET Framework, .NET, .NET Standard
(버전 7.0부터 사용 가능)
개별 연결 문자열을 수정하지 않고 전역적으로
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault", true);
App.Config에서 이 스위치를 사용하도록 설정할 수도 있습니다.
<runtime>
<AppContextSwitchOverrides value="Switch.Microsoft.Data.SqlClient.EnableMultiSubnetFailoverByDefault=true" />
</runtime>
사용하도록 설정하면 모든 연결이 연결 문자열에 설정된 것처럼 MultiSubnetFailover=true 동작합니다. 이 스위치는 기본적으로 사용하지 않도록 설정됩니다.
비동기 읽기에 패킷 멀티플렉싱 사용
적용 대상: .NET Framework, .NET, .NET Standard
(버전 7.0부터 사용 가능)
패킷 멀티플렉싱은 큰 결과 집합, 스트리밍 시나리오 또는 대량 데이터 검색과 같은 ExecuteReaderAsync 대규모 비동기 읽기 작업의 성능을 향상시킵니다. 이 기능은 두 개의 옵트인 AppContext 스위치에 의해 제어됩니다. 두 스위치를 모두 설정하면 false 새 비동기 처리 경로가 활성화됩니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityAsyncBehaviour", false);
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseCompatibilityProcessSni", false);
기본적으로 두 스위치는 true모두 기존(호환 가능) 동작을 유지합니다.
유저 에이전트 기능 확장 활성화
적용 대상: .NET Framework, .NET, .NET Standard
(버전 7.0부터 사용 가능)
AppContext 스위치 "Switch.Microsoft.Data.SqlClient.EnableUserAgent" 를 사용하도록 설정하면 드라이버는 연결의 일부로 사용자 에이전트 세부 정보를 서버에 보냅니다. 이 정보는 버전 및 운영 체제별 드라이버 사용 문제를 해결하고 정량화하는 데 도움이 됩니다. 이 스위치는 기본적으로 사용하지 않도록 설정됩니다. 사용하도록 설정하려면 애플리케이션 시작 시 AppContext 스위치를 true 설정합니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableUserAgent", true);
소수점 절단 기능 활성화
적용 대상: .NET Framework, .NET, .NET Standard
Microsoft.Data.SqlClient 2.0부터 decimal 데이터가 SQL Server에서 하는 것처럼 기본 설정으로 반올림됩니다. 이전 잘라내기 동작을 사용하도록 설정하려면 애플리케이션 시작 시 AppContext 스위치 "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal"을 true로 설정하면 됩니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);
Windows에서 관리 네트워킹 사용
적용 대상: .NET; .NET Standard
(버전 2.0부터 사용 가능)
Windows에서 SqlClient는 기본적으로 SNI 네트워크 인터페이스의 네이티브 구현을 사용합니다. 관리 SNI 구현을 사용하도록 설정하려면 애플리케이션 시작 시 AppContext 스위치 "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows"를 true로 설정하면 됩니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);
이 스위치는 Windows의 .NET Core 2.1 이상 및 .NET Standard 2.0 이상 프로젝트에서 관리 네트워킹 구현을 사용하도록 드라이버의 동작을 토글하여 Microsoft.Data.SqlClient 라이브러리의 네이티브 라이브러리에 대한 모든 종속성을 제거합니다. 테스트 및 디버깅용으로만 사용됩니다.
참고
네이티브 구현과 비교했을 때 몇 가지 알려진 차이점이 있습니다. 예를 들어 관리 구현은 비도메인 Windows 인증을 지원하지 않습니다.
네트워크 IP 투명 해석 해제
적용 대상: .NET Framework
TNIR(투명 네트워크 IP 확인)은 기존 MultiSubnetFailover 기능의 수정 버전입니다. TNIR은 호스트 이름의 첫 번째 확인된 IP가 응답하지 않고 호스트 이름과 연결된 여러 IP가 있는 경우 드라이버의 연결 시퀀스에 영향을 미칩니다. 와 TransparentNetworkIPResolution 의 MultiSubnetFailover 조합은 연결 순서를 선택합니다:
| 트랜스페어런트 네트워크 IP 해상도 | MultiSubnetFailover | 연결 시퀀스 |
|---|---|---|
| 참 | 참 |
TransparentNetworkIPResolution는 무시됩니다. 드라이버는 DNS로 해석된 IP 주소를 병렬로 시도하고, 첫 번째 응답자와 인증을 완료합니다. |
| 참 | 거짓 | 드라이버는 DNS가 해결한 IP 주소에 대해 여러 번 연결 라운드를 실행하며, 첫 시도는 최소 500밀리초, 시도당 타임아웃은 점점 커집니다. 연결이 성공하거나 전체 Connect Timeout 타임아웃에 도달할 때까지 반복됩니다. |
| 거짓 | 참 | 드라이버는 DNS로 해석된 IP 주소를 병렬로 시도하고, 첫 번째 응답자와 인증을 완료합니다. |
| 거짓 | 거짓 | 드라이버는 성공하거나 Connect Timeout 도달할 때까지 각 DNS로 해석된 IP 주소를 순차적으로 시도합니다. |
TransparentNetworkIPResolution기본적으로 .NET 프레임워크에서는 활성화되어 있으며, MultiSubnetFailover 기본적으로 비활성화되어 있습니다. .NET 5 및 이후 버전에서는 TransparentNetworkIPResolution는 인식되는 연결 문자열 키워드가 아니며, 이를 어떤 값으로든 설정하면 ArgumentException(KeywordNotSupported) 예외가 발생합니다. 해당 버전은 MultiSubnetFailover만 지원합니다. 이 섹션의 나머지 부분(자동 오버라이드, 다음 경고의 실패 모드, 그리고 AppContext 전환)은 .NET 프레임워크에 적용됩니다.
팁 (조언)
.NET 버전이나 대상이 Azure SQL인지 온프레미스 SQL Server인지 상관없이 모든 연결 문자열에 설정 MultiSubnetFailover=True 하세요.
MultiSubnetFailover=True 첫 번째 반응형 복제본을 빠르게 찾는 병렬 연결 코드 경로를 선택합니다. .NET 프레임워크에서는 또한 TNIR의 IP 단위 순차 재시도 루프를 우회하는데, 이는 긴 연결 지연과 인증 전 핸드셰이크 타임아웃의 흔한 원인입니다.
.NET Framework에서 연결 문자열에 TransparentNetworkIPResolution이 지정되지 않은 경우, 데이터 원본이 인식된 Azure SQL 엔드포인트이거나, Authentication 키가 Microsoft Entra ID 메서드(Active Directory Password, Active Directory Integrated, Active Directory Interactive, Active Directory Service Principal, Active Directory Device Code Flow, Active Directory Managed Identity, Active Directory MSI, Active Directory Default 또는 Active Directory Workload Identity) 중 하나로 설정되어 있거나, SqlConnection.AccessToken 속성이 설정된 경우 드라이버가 TNIR을 자동으로 비활성화합니다. 드라이버가 인식하는 엔드포인트 접미사는 SqlConnection.ConnectionString의 TransparentNetworkIPResolution 항목을 참조하세요.
명시적 값은 이 자동 동작 TransparentNetworkIPResolution 을 우회하여 TNIR을 True 활성화하고 False 무조건 비활성화합니다. 자동 동작을 복원하려면 연결 문자열에서 키워드를 제거하세요. 또한 연결 문자열이 사용자 정의 CNAME이나 vanity DNS 이름을 통해 Azure SQL을 가리키는데, 접미사가 Azure SQL 엔드포인트로 인식되지 않을 때도 자동 오버라이드가 적용되지 않습니다. 자동 오버라이드는 Azure SQL을 대상으로 하며, 온프레미스 SQL Server에서는 실행되지 않으므로 기본적으로 TNIR이 켜져 있습니다.
.NET 프레임워크에서의 긴 연결 지연
.NET 프레임워크 TransparentNetworkIPResolution=True 에서는 (기본값)이 대상 DNS 이름이 여러 IP로 해석될 때 긴 연결 지연과 인증 전 핸드셰이크 타임아웃을 유발할 수 있으며, 이전 IP 중 하나가 건강하지 않거나 오래된 상태이거나 접근 불가능할 때 발생합니다. TNIR은 해결된 IP를 순차적으로 시도하며, 전체 Connect Timeout 결과에 도달할 때까지 매 라운드마다 시도당 타임아웃을 증가시킵니다. 보통 예상치 못하게 긴 연결 지연이 나타나 이런 오류로 끝납니다:
Connection Timeout Expired. The timeout period elapsed while attempting to consume the pre-authentication handshake acknowledgement. This could be because the pre-authentication handshake failed or the server was unable to respond back in time.
이 패턴은 여러 위상에서 나타난다:
- Azure SQL Database, Azure SQL Managed Instance, 또는 Microsoft Fabric의 SQL 데이터베이스. Azure SQL 게이트웨이는 각 인증을 백엔드 레플리카로 라우팅합니다. 라우팅된 연결이 실패하면, TNIR은 게이트웨이로 돌아가지 않고 라우팅된 백엔드를 재시도하여 백엔드 장애 조치 시 지연을 연장합니다.
- DNS 이름이 여러 복제본 IP 주소로 확인되는 Always On 가용성 그룹 수신기 뒤에 있는 온-프레미스 SQL Server 오래된 DNS 항목이나 건강하지 않은 복제본 IP는 TNIR이 작동하는 복제본에 도달하기 전에 순차적으로 시도됩니다.
-
다중 서브넷 클러스터 리스너를 가진 장애 전환 클러스터 인스턴스나 대상 DNS 이름이 여러
A/AAAA레코드를 가진 기타 구성(예: DNS 라운드로빈)입니다.
이 동작을 피하기 위해 연결 문자열에 다음과 같이 설정하세요MultiSubnetFailover=True:
MultiSubnetFailover=True
이 권고안은 모든 .NET 버전에서 작동하며 Azure SQL과 온프레미스 SQL Server 모두를 커버합니다.
MultiSubnetFailover=True인 경우 드라이버는 TransparentNetworkIPResolution을 무시하고, DNS로 확인된 IP 주소들을 병렬로 시도하며, 가장 먼저 응답하는 복제본으로 인증을 완료합니다. 이름과 상관없이, MultiSubnetFailover DNS 이름이 여러 대상 IP로 해석되는 리스너에게 적용되며, 해당 IP가 서로 다른 서브넷에 있든 상관없고, DNS가 단일 IP로 해석되는 독립 실행형 서버에서는 안전합니다.
모든 연결 문자열을 편집하지 않고 프로세스 전체를 제어하려면 기본 AppContext 스위치에서 Enable MultiSubnetFailover를 사용하세요.
AppContext 스위치로 TNIR을 비활성화하세요
.NET Framework에서 TransparentNetworkIPResolution의 기본값을 true에서 false로 변경하려면, 애플리케이션 시작 시 AppContext 스위치 Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString를 true로 설정하세요. 이 스위치는 TransparentNetworkIPResolution가 연결 문자열에 없을 때만 기본값을 변경하며, 명시적으로 지정된 값은 덮어쓰지 않습니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString", true);
이러한 속성 설정에 대한 자세한 내용은 SqlConnection.ConnectionString 속성 설명서를 참조하세요.
로그인 중 최소 시간 제한 사용
적용 대상: .NET Framework, .NET, .NET Standard
로그인 시도가 무기한 대기하지 않도록 하려면 애플리케이션 시작 시 AppContext 스위치 Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin을 true로 설정하면 됩니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin", false);
ReadAsync 차단 동작 사용 안 함
적용 대상: .NET Framework, .NET, .NET Standard
버전 3.0부터 ReadAsync는 비동기적으로 실행됩니다. 이전 버전은 ReadAsync를 동기적으로 실행하고 .NET Framework에서 호출 스레드를 차단합니다. 이 차단 동작을 제어하려면 애플리케이션 시작 시 AppContext 스위치 Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking을 true 또는 false로 설정하면 됩니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false);
rowversion의 null 동작 설정 사용
적용 대상: .NET Framework, .NET, .NET Standard
버전 3.0부터 rowversion의 값이 null 이면 SqlDataReader는 빈 DBNull 값 대신 byte[] 값을 반환합니다. 빈 byte[]를 반환하는 레거시 동작을 사용하도록 설정하려면 애플리케이션 시작 시 AppContext 스위치 Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior를 사용하도록 설정합니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);
안전하지 않은 TLS 경고 표시 안 함
적용 대상: .NET Framework, .NET, .NET Standard
(버전 4.0.1부터 사용 가능)
연결 문자열에서 Encrypt=false를 사용할 때 TLS 버전이 1.2 이하인 경우 콘솔에 보안 경고가 출력됩니다. 애플리케이션 시작 시 다음 AppContext 스위치를 사용하도록 설정하여 이 경고를 표시하지 않을 수 있습니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning", true);
서버 제공 장애 조치 파트너 무시
적용 대상: .NET Framework, .NET, .NET Standard
(버전 5.1.8, 6.0.4 및 6.1.3부터 사용 가능)
장애 조치 시 서버에서 제공하는 장애 조치(failover) 파트너 정보는 연결 문자열에 제공된 장애 조치(failover) 파트너 정보보다 선호됩니다. 서버에서 제공하는 장애 조치(failover) 파트너 정보를 무시하고 연결 문자열에 제공된 장애 조치(failover) 파트너 정보만 고려하려면 애플리케이션 시작 시 이 AppContext 스위치를 사용하도록 설정합니다.
AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.IgnoreServerProvidedFailoverPartner", true);