이 문서는 Microsoft가 수락하는 모든 연결 문자열 키워드를 나열합니다. Data.SqlClient가 인정합니다. 각 키워드는 매칭 SqlConnectionStringBuilder 속성도 가지고 있습니다. 소개, 일반적인 패턴, 파싱 규칙은 연결 문자열을 참조하세요.
키워드와 별칭은 대소문자에 구분되지 않습니다. 건설업자 부동산을 통해 값을 설정하면, 건설업체는 키 워 드 열에 정식 키워드를 입력합니다.
SqlConnectionStringBuilder로 옵션 설정
서버, 데이터베이스, 인증 설정을 담은 기본 연결 문자열에서 시작하세요. 그 다음 빌더 속성을 통해 작업량별 옵션을 설정하세요. .NET 프레임워크 탭은 C# 7.3을 사용합니다. 샘플을 실행하는 프로젝트를 만들려면 ' 프로젝트 만들기'를 참조하세요.
using Microsoft.Data.SqlClient;
string connectionString =
Environment.GetEnvironmentVariable("SQL_CONNECTION_STRING")
?? throw new InvalidOperationException(
"Set the SQL_CONNECTION_STRING environment variable.");
var builder = new SqlConnectionStringBuilder(connectionString)
{
ApplicationName = "Orders.Worker",
ConnectTimeout = 30,
CommandTimeout = 60,
MaxPoolSize = 50,
};
await using var connection = new SqlConnection(builder.ConnectionString);
await connection.OpenAsync();
await using var command = new SqlCommand("SELECT APP_NAME();", connection);
Console.WriteLine($"APP_NAME(): {await command.ExecuteScalarAsync()}");
Console.WriteLine($"Connection timeout: {connection.ConnectionTimeout}");
Console.WriteLine($"Command timeout: {command.CommandTimeout}");
결과는 다음과 같습니다.
APP_NAME(): Orders.Worker
Connection timeout: 30
Command timeout: 60
새 코드 SqlCommand 는 연결 키워드 Command Timeout 에서 기본 타임아웃을 사용합니다.
기본 값 확인
새로운 SqlConnectionStringBuilder 선택지가 모든 옵션에 대해 기본값을 보고합니다. 이 프로그램은 대부분의 애플리케이션이 검토하는 기본값을 출력합니다:
using Microsoft.Data.SqlClient;
var defaults = new SqlConnectionStringBuilder();
Console.WriteLine($"Connect Timeout: {defaults.ConnectTimeout}");
Console.WriteLine($"Command Timeout: {defaults.CommandTimeout}");
Console.WriteLine($"Connect Retry Count: {defaults.ConnectRetryCount}");
Console.WriteLine($"Connect Retry Interval: {defaults.ConnectRetryInterval}");
Console.WriteLine($"Encrypt: {defaults.Encrypt}");
Console.WriteLine($"Trust Server Certificate: {defaults.TrustServerCertificate}");
Console.WriteLine($"Pooling: {defaults.Pooling}");
Console.WriteLine($"Min Pool Size: {defaults.MinPoolSize}");
Console.WriteLine($"Max Pool Size: {defaults.MaxPoolSize}");
Console.WriteLine($"Connection Idle Timeout: {defaults.IdleTimeout}");
Console.WriteLine($"Load Balance Timeout: {defaults.LoadBalanceTimeout}");
Console.WriteLine($"Packet Size: {defaults.PacketSize}");
Console.WriteLine($"Multi Subnet Failover: {defaults.MultiSubnetFailover}");
Console.WriteLine($"IP Address Preference: {defaults.IPAddressPreference}");
Console.WriteLine($"Pool Blocking Period: {defaults.PoolBlockingPeriod}");
Console.WriteLine($"Application Intent: {defaults.ApplicationIntent}");
Console.WriteLine($"Application Name: {defaults.ApplicationName}");
Console.WriteLine($"Type System Version: {defaults.TypeSystemVersion}");
Console.WriteLine($"Transaction Binding: {defaults.TransactionBinding}");
.NET에서 출력은 다음과 같습니다:
Connect Timeout: 15
Command Timeout: 30
Connect Retry Count: 1
Connect Retry Interval: 10
Encrypt: True
Trust Server Certificate: False
Pooling: True
Min Pool Size: 0
Max Pool Size: 100
Connection Idle Timeout: 300
Load Balance Timeout: 0
Packet Size: 8000
Multi Subnet Failover: False
IP Address Preference: IPv4First
Pool Blocking Period: Auto
Application Intent: ReadWrite
Application Name: Core Microsoft SqlClient Data Provider
Type System Version: Latest
Transaction Binding: Implicit Unbind
Encrypt: True 선택지 Mandatory 입니다. .NET 프레임워크에서 기본 애플리케이션 이름은 Framework Microsoft SqlClient Data Provider.
서버 및 데이터베이스 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Data Source |
Server, Address, , Addr, Network Address |
DataSource |
비어 있음 | 연결할 서버. 호스트 이름, host,port, host\instance, (localdb)\instance, 또는 np:tcp: 프로토콜 접두사를 수용합니다. 승인된 양식에 대해서는 ' 서버 및 데이터베이스 지정'을 참조하세요. |
Initial Catalog |
Database |
InitialCatalog |
비어 있음 | 로그인 후 사용할 수 있는 데이터베이스. 비어 있으면 서버가 로그인 기본 데이터베이스를 사용합니다. |
AttachDbFilename |
Extended Properties, Initial File Name |
AttachDBFilename |
비어 있음 | SQL Server Express와 LocalDB용 기본 데이터베이스 파일의 전체 경로 첨부. |
User Instance |
None | UserInstance |
false |
연결을 SQL Server Express 사용자 인스턴스로 리디렉션합니다. 자세한 내용은 SQL Server Express 사용자 인스턴스를 참조하세요. |
Failover Partner |
FailoverPartner |
FailoverPartner |
비어 있음 | 주 서버가 사용 불가능할 때 시도할 데이터베이스 미러링 파트너. 데이터베이스 미러링은 더 이상 지원되지 않습니다. 새로운 배포에는 가용성 그룹을 사용하세요. |
Current Language |
Language |
CurrentLanguage |
비어 있음 | 세션의 SQL Server 언어 이름, 예를 들어 us_english. 날짜 형식과 시스템 메시지 언어를 제어합니다. |
애플리케이션 식별 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Application Name |
App |
ApplicationName |
Core Microsoft SqlClient Data Provider |
서버가 세션 뷰를 통해 APP_NAME() 보고하는 이름입니다. 배포된 각 워크로드마다 하나의 안정적인 이름을 사용하세요. 서로 다른 값은 서로 다른 연결 풀을 만듭니다. |
Workstation ID |
WorkstationID, WSID |
WorkstationID |
로컬 컴퓨터 이름 | 서버가 보고 HOST_NAME()하는 클라이언트 컴퓨터 이름입니다. |
Application Intent |
ApplicationIntent |
ApplicationIntent |
ReadWrite |
ReadOnly 대상이 지원할 때 읽기 의도 라우팅을 요청합니다. 이 기능은 문장을 읽기 전용으로 만들지 않습니다. 자세한 내용은 고가용성 및 재해 복구를 참조하세요. |
어떤 프레임워크나 도구가 연결을 열었는지 보고하려면 속성을 사용하세요.RegisteredApplication 연결 문자열 키워드가 없습니다. 자세한 내용은 애플리케이션 신원 보고를 참조하세요.
인증 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Authentication |
None | Authentication |
지정되지 않음 | 인증 방법입니다. 허용된 값은 다음 표를 참조하세요. |
Integrated Security |
Trusted_Connection |
IntegratedSecurity |
false |
true, yes, 또는 sspi 현재 프로세스의 항원을 사용합니다. |
User ID |
UID, User |
UserID |
비어 있음 | SQL 로그인 이름 또는 Microsoft Entra ID 사용자 또는 클라이언트 식별자(에 따라 Authentication다릅니다). |
Password |
PWD |
Password |
비어 있음 | 비밀번호나 클라이언트 비밀을 허용하는 메서드에 대해서요. |
Persist Security Info |
PersistSecurityInfo |
PersistSecurityInfo |
false |
이 되면 false운전자는 연결이 열린 후 비밀번호 SqlConnection.ConnectionString 를 제거합니다. 그냥 둬 false. |
Server SPN |
ServerSPN |
ServerSPN |
서버 이름에서 유래함 | 통합 인증에 사용되는 서비스 주체 이름(SPN)을 주 서버에 무시합니다. |
Failover Partner SPN |
FailoverPartnerSPN |
FailoverPartnerSPN |
파트너 이름에서 유래함 | 장애 조치 파트너에 대한 통합 인증에 사용되는 SPN을 덮어씁니다. |
Authentication 이 가치를 받아들입니다. 빌더는 공백 없이 작성하며, 예를 들어 ActiveDirectoryDefault파서는 두 형태를 모두 수용합니다.
| Value | Identity |
|---|---|
Sql Password |
SQL 로그인 User IDPassword과 . |
Active Directory Default |
환경 변수, 관리 신원, 개발자 도구 로그인과 같은 자격 증명 소스 체인입니다. |
Active Directory Managed Identity |
관리된 신원. 사용자 지정 신원의 클라이언트 ID로 설정 User ID 하세요.
Active Directory MSI 는 별칭입니다. |
Active Directory Workload Identity |
쿠버네티스 워크로드 아이덴티티입니다. |
Active Directory Service Principal |
클라이언트 ID Password 가 설정되어 있고 클라이언트 비밀이 설정된 애플리케이션 User ID 입니다. |
Active Directory Interactive |
브라우저 프롬프트로 로그인하는 사용자. |
Active Directory Device Code Flow |
다른 기기에서 코드를 입력해 로그인하는 사용자. |
Active Directory Integrated |
로그인한 Windows 사용자는 연합 또는 원활한 단일 사인온 구성을 통해 가능합니다. |
Active Directory Password |
사용자 이름 및 암호. 이 메서드는 사용되지 않습니다. 다른 방법을 사용하세요. |
Microsoft Entra ID 메서드는 패키지가 Microsoft.Data.SqlClient.Extensions.Azure 필요합니다. 설정과 예제는 Microsoft Entra ID 인증과 SQL Server 인증을 참조하세요.
암호화 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Encrypt |
None | Encrypt |
Mandatory |
Strict TDS 8.0을 사용하며 항상 서버 인증서를 검증합니다.
Mandatory, , true또는 yes 연결을 암호화합니다.
Optional, , false또는 no 서버가 필요할 때만 전체 연결을 암호화합니다. 서버가 암호화를 지원하지만 필요하지 않을 때는 로그인 패킷만 암호화됩니다. |
Trust Server Certificate |
TrustServerCertificate |
TrustServerCertificate |
false |
true 서버 인증서 검증을 건너뛸 수 있습니다.
Encrypt=Strict인 경우 무시됩니다. 프로덕션 환경에서는 사용하지 마세요. |
Host Name In Certificate |
HostNameInCertificate |
HostNameInCertificate |
비어 있음 | 인증서 검증을 위한 대체 명칭입니다. SqlClient는 먼저 .의 Data Source서버 이름과 인증서를 검증합니다. 이름이 일치하지 않을 때만 검사 Host Name In Certificate 하므로, 서버 이름이 이미 일치할 때 잘못된 값이 발생해도 실패를 일으키지 않습니다. 인증서를 고정하지 않습니다. 특정 인증서 Server Certificate를 요구하려면 . 네트워크 목적지를 변경하거나 신뢰 체인 및 만료 검사를 우회하지 않습니다. 서버 이름이 이미 인증서와 일치하면 설정하지 않은 상태로 두세요. |
Server Certificate |
ServerCertificate |
ServerCertificate |
비어 있음 | PEM, DER, 또는 CER 파일의 경로가 서버 인증서와 정확히 일치해야 합니다. 운전자는 인증서를 검증할 때만 일치를 확인하므로 또는 Encrypt=StrictTrust Server Certificate=false와 함께 Encrypt=Mandatory 사용한다. 일치하는 파일은 체인 및 호스트 이름 검증을 대체하므로, 클라이언트가 신뢰하지 않는 자가 서명 인증서와 함께 작동합니다. |
전체 검증 규칙은 암호화 및 인증서 검증을 참조하세요.
항상 암호화된 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Column Encryption Setting |
ColumnEncryption |
ColumnEncryptionSetting |
Disabled |
Enabled 연결을 위해 항상 암호화를 켜는 기능입니다. |
Attestation Protocol |
None | AttestationProtocol |
지정되지 않음 | 엔클레이브 증명 프로토콜: AAS, HGS, 또는 None. |
Enclave Attestation Url |
None | EnclaveAttestationUrl |
비어 있음 | Always Encrypted와 보안 엔클레이브의 증명 서비스 엔드포인트입니다. |
네트워크 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Multi Subnet Failover |
MultiSubnetFailover |
MultiSubnetFailover |
false |
서버 이름이 병렬로 해석되는 모든 IP 주소를 시도합니다. 가용성 그룹 리스너와 TCP를 통해 접근 가능한 장애 조치 클러스터 인스턴스에 사용하세요. 데이터베이스 미러링은 지원되지 않습니다. 명명된 인스턴스는 네트워킹 구현에 따라 다릅니다. 관리형 구현은 리눅스와 macOS에서 .NET가 사용하며, 관리형 네트워킹이 켜진 Windows에서 사용되며, 이름 있는 인스턴스를 지원하고 SQL Server 브라우저 요청을 모든 해결된 주소에 병렬로 전송합니다. Windows의 네이티브 구현은 SNI 오류 48이 있는 이름 있는 인스턴스를 거부할 수 있습니다. |
IP Address Preference |
IPAddressPreference |
IPAddressPreference |
IPv4First |
해석된 주소를 시도하는 순서는 , , IPv6First또는 UsePlatformDefault입니다. IPv4First |
Packet Size |
PacketSize |
PacketSize |
8000 |
표식 데이터 스트림(TDS) 패킷 크기는 바이트 단위로, 512에서 32,768까지 다양합니다. |
프로세스 전체의 AppContext 스위치는 기본값true을 Multi Subnet Failover 로 변경할 수 있습니다. 자세한 내용은 SqlClient의 AppContext 스위치를 참조하세요.
타임아웃 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Connect Timeout |
Connection Timeout, ConnectTimeout, Timeout |
ConnectTimeout |
15 |
연결이 도착할 때까지 몇 초가 걸리며, 풀이 가득 찼을 때 풀 연결을 기다리는 시간도 포함됩니다.
0 무기한 기다려야 합니다. |
Command Timeout |
None | CommandTimeout |
30 |
연결에서 생성된 명령어의 기본값 CommandTimeout 은 초 단위입니다.
0 무기한 기다려야 합니다. |
Connect Timeout 쿼리 실행을 제한하지 않습니다.
Command Timeout 로그인이나 풀 연결 대기 시간을 제한하지 않습니다. a를 비동기 통화로 전달 CancellationToken 하여 호출자가 어느 타임아웃도 만료되기 전에 기다릴 수 있도록 합니다.
연결 복구 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Connect Retry Count |
ConnectRetryCount |
ConnectRetryCount |
1 |
첫 번째 오픈 중 예선 과도 장애가 발생한 후 중단된 유휴 연결을 복구할 때 재시도합니다.
0 재시도를 끄고, 유효한 값은 0~255입니다. |
Connect Retry Interval |
ConnectRetryInterval |
ConnectRetryInterval |
10 |
재시도 사이에 몇 초가 있었다. 유효한 값은 1부터 60까지입니다. |
기본값인 '가 될 때 Connect Retry Count1, 드라이버는 Azure SQL 엔드포인트와 5 Azure Synapse Analytics의 서버리스 SQL 풀 엔드포인트에서 끊긴 유휴 연결을 복원할 때 사용합니다2. 첫 번째 열기는 값을 설정한 값으로 사용하므로 기본값은 각 엔드포인트에서 한 번씩 재시도할 수 있습니다. 운전자는 두 경우 모두 설정된 다른 값을 사용합니다.
이 키워드는 실행 중에 실패한 명령을 다시 시도하지 않습니다. 한 번의 오픈 시 내장된 재시도를 건너뛰려면, 와 함께 OpenWithoutRetry오버로드를 Open 호출하세요. 커스텀 정책에 대해서는 Configurable retry 로직을 참조하세요. 명령어가 안전할 때만 반복하세요.
풀링 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Pooling |
None | Pooling |
true |
물리적 연결을 재사용하여 연결 문자열을 맞추는 것입니다. |
Min Pool Size |
None | MinPoolSize |
0 |
수영장이 생성된 후에도 계속 열려 있는 물리적 연결. |
Max Pool Size |
None | MaxPoolSize |
100 |
한 풀에 가장 많은 물리적 연결이 있습니다. 최소한 1 이상이어야 합니다. |
Connection Idle Timeout |
None | IdleTimeout |
300 |
연결이 풀을 닫기 전에 유휴 상태를 유지할 수 있는 몇 초 동안의 시간을 의미합니다.
0 유휴 만료 기능을 끕니다. AppContext 스위치가 Switch.Microsoft.Data.SqlClient.UseLegacyIdleTimeoutBehaviorfalse.일 때만 강제됩니다. 기본적으로 true입니다. |
Load Balance Timeout |
Connection Lifetime |
LoadBalanceTimeout |
0 |
연결 후 최대 연령이 초 단위로 풀로 돌아왔습니다. 오래된 연결은 닫혔습니다.
0 제한을 끄는 것. |
Pool Blocking Period |
PoolBlockingPeriod |
PoolBlockingPeriod |
Auto |
풀이 짧은 시간 동안 캐시된 로그인 실패를 다시 발생시키는지 여부: Auto, AlwaysBlock, 또는 NeverBlock.
AutoAzure SQL endpoints 嘅 blocking off off. |
각 독립된 연결 문자열은 자체 풀을 받습니다. 풀 키, 지우기, 유휴 시간에 대해서는 SQL Server 연결 풀링을 참조하세요.
트랜잭션 및 세션 옵션
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Enlist |
None | Enlist |
true |
연결이 열릴 때 대기 System.Transactions 거래에 연결(connection)을 등록합니다. |
Transaction Binding |
None | TransactionBinding |
Implicit Unbind |
Implicit Unbind 인리트먼트 트랜잭션이 종료되면 연결을 분리합니다.
Explicit Unbind 연결이 끊기거나 코드가 분리할 때까지 계속 붙어 두는 거죠. |
Multiple Active Result Sets |
MultipleActiveResultSets |
MultipleActiveResultSets |
false |
한 연결에 여러 개의 활성 배치를 허용합니다. |
Type System Version |
None | TypeSystemVersion |
Latest |
드라이버가 노출하는 서버 타입 시스템입니다. , , , 를 SQL Server 2005받아들입니다.LatestSQL Server 2012SQL Server 2008 여기서 남겨 Latest주세요. |
Replication |
None | Replication |
false |
연결을 복제 연결로 식별합니다. |
.NET 프레임워크 전용 옵션
이 키워드는 .NET 프레임워크에서만 허용됩니다. .NET에서는 빌더가 계속 던 NotSupportedExceptionSqlConnectionArgumentException지고 던집니다.
| 키워드 | Aliases | 건축업자 소유 | Default | 설명 |
|---|---|---|---|---|
Network Library |
Net, Network |
NetworkLibrary |
비어 있음 | 네트워크 도서관. a나 np: 접두Data Source사와 tcp: 결합하지 마세요. 연결이 실패할 수 있기 때문입니다. .NET에서는 접두 Data Source 사를 또는 대신 사용 tcp:np: 하세요. |
Connection Reset |
None | ConnectionReset |
true |
Obsolete. |
Transparent Network IP Resolution |
TransparentNetworkIPResolution |
TransparentNetworkIPResolution |
true |
Obsolete. |
지원되지 않는 키워드
| 키워드 | Result |
|---|---|
Context Connection |
Context Connection=true을 throw합니다.InvalidOperationException Microsoft. Data.SqlClient는 SQL CLR 컨텍스트 연결을 지원하지 않습니다. |
Asynchronous Processing |
ArgumentException: Keyword not supported을 던집니다. 비동기식 메서드는 이 없이도 작동합니다. |
Driver, Provider |
ArgumentException: Keyword not supported을 던집니다. 이 키워드들은 ODBC와 OLE DB에 속합니다. |
유효성 검사 규칙
SqlConnectionStringBuilder 설정하면 알 수 없는 키워드와 많은 부적절한 값들을 거부합니다.
SqlConnection사용자가 입력할 때 연결 문자열을 설정할 때 더 많은 검사를 수행하며, 빌더가 받아들이는 단일 값과 키워드 조합 등을 포함합니다. 건설업체가 인정한 끈도 연결을 만들 때 여전히 실패할 수 있습니다.
빌더와 연결은 이 값들을 거부합니다 ArgumentException:
-
Connect Timeout, ,Command TimeoutLoad Balance Timeout,Connection Idle Timeout, 또는Min Pool Size0 미만입니다. -
Max Pool Size1 미만. -
Packet Size512번 외곽에서 32,768번까지. -
Connect Retry Count0부터 255까지의 외부 구간. -
Connect Retry Interval1번부터 60번까지. - 이 글에는 없는 키워드입니다.
SqlConnection 또한 이 값 ArgumentException들을 거부하지만, 건축자가 이를 받아들인다:
-
Type System Version, ,SQL Server 2008, 또는SQL Server 2005를 제외하고Latest는SQL Server 2012. -
Transaction Binding또는 그렇지 않으면Implicit UnbindExplicit Unbind. - , 에
Workstation ID대한 TDS 한도Data SourceCurrent LanguageApplication NameInitial CatalogPasswordFailover PartnerUser ID보다 긴 값입니다.AttachDBFilename
SqlConnection 또한 다음과 같은 조합을 거부한다 ArgumentException:
-
Min Pool Size보다 큼Max Pool Size. -
Failover Partner가 없으면Initial Catalog -
Failover Partner와 함께Multi Subnet Failover=true,User Instance=true, 또는Application Intent=ReadOnly. -
Authentication와Integrated Security=true. -
Password,Active Directory Integrated,Active Directory Interactive,Active Directory Managed IdentityActive Directory MSI,Active Directory Default, , 또는Active Directory Workload Identity. -
User ID또는Password.Active Directory Device Code Flow
옵션 변경 사항 검토
운영 환경에서 옵션을 변경하기 전에:
- 현재 연결 문자열, 드라이버 버전, 엔드포인트 유형, 그리고 해결하려는 문제를 기록하세요.
- 한 번에 한 가지 옵션을 바꾸세요.
- 연결 설정, 인증, 인증서 검증, 풀링, 장애 조치, 취소, 쿼리 실행을 테스트합니다.
- 연결 지연, 풀 대기, 오류 수치를 측정하세요.
- 모든 배포된 인스턴스에서 설정을 확인하세요.
변경된 연결 문자열은 새로운 풀을 생성합니다. 단계적 롤아웃 중에는 기존 풀과 새 풀이 동시에 존재하므로 서버에 대한 물리적 연결 수가 증가할 수 있습니다.