Microsoft. Data.SqlClient 연결 문자열은 드라이버에게 어떤 SQL Server 호환 엔드포인트와 데이터베이스를 사용해야 하는지, 어떻게 인증하고 연결을 어떻게 구성할지 알려줍니다. 또는 SqlConnectionStringBuilder로 전달하세요SqlConnection.
네 가지 결정부터 시작하세요:
- 애플리케이션이 사용하는 서버와 데이터베이스는 무엇인가요?
- 애플리케이션은 어떤 신원으로 실행되나요?
- 클라이언트는 서버 인증서를 어떻게 검증하나요?
- 워크로드에 어떤 연결 동작이 필요하나요?
선택한 인증 방식이 해당 설계를 지원할 때는 자격 증명과 접근 토큰을 연결 문자열에서 제외하세요.
인증 패턴을 선택하세요
배치에 맞는 가장 좁은 패턴을 사용하세요.
| Environment | 선호 패턴 | 핵심 연결 문자열 |
|---|---|---|
| 도메인 또는 로컬 Windows 아이덴티티 하에 있는 SQL Server on Windows | Windows 통합 인증 | Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true |
| 개발자 워크스테이션이 Microsoft Fabric에서 SQL 데이터베이스에 연결됨 | Microsoft Entra ID 기본 자격 증명 체인 | Server=tcp:<server>,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict |
| Azure에서 호스팅되고 Azure SQL에 연결되는 애플리케이션 | Microsoft Entra ID 관리 ID | Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Managed Identity;Encrypt=Strict |
| Azure SQL에 연결하는 개발자 워크스테이션 | Microsoft Entra ID 기본 자격 증명 체인 | Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Default;Encrypt=Strict |
| Azure SQL에 연결하는 대화형 데스크톱 도구 | Microsoft Entra ID 인터랙티브 인증 | Server=tcp:<server>.database.windows.net,1433;Database=<database>;Authentication=Active Directory Interactive;Encrypt=Strict |
| SQL 인증이 필요한 환경 | 비밀 저장소에서 사용자 이름과 비밀번호 | Server=<server>;Database=<database>;User ID=<user_id>;Password=<password>;Encrypt=true |
Microsoft. Data.SqlClient 7.0 및 이후 버전은 드라이버 제공 방식의 Microsoft Entra ID 인증 모드에 버전 매칭 Microsoft.Data.SqlClient.Extensions.Azure 패키지가 필요합니다. 애플리케이션 코드가 액세스 토큰이나 액세스 토큰 콜백을 제공할 때는 그런 확장 기능이 필요하지 않습니다.
인증은 데이터베이스 측 사용자, 권한, 신원 설정도 필요하다. 전체 선택 매트릭스와 설정에 대해서는 Microsoft Entra ID 인증과 SQL Server 인증을 참조하세요.
서버와 데이터베이스를 지정하세요
Database 및 Server를 정식 키워드 이름으로 사용하세요. 이 드라이버는 Initial Catalog의 별칭으로 Server를, Data Source의 별칭으로 Database를 허용합니다.
일반적인 서버 형태는 다음과 같습니다:
Server=server-name
Server=server-name\instance-name
Server=tcp:server-name,1433
Server=(localdb)\MSSQLLocalDB
운영 TCP 연결에는 명시적인 프로토콜, 호스트 이름, 포트를 선호합니다. IP 주소 대신 서버 인증서와 일치하는 안정적인 DNS 이름을 사용하세요.
가용성 그룹 리스너, 페일오버 그룹, Azure SQL 엔드포인트 또는 기타 다중 주소 TCP 엔드포인트에 대해서도 Connection 옵션에서 검토 MultiSubnetFailover 하세요.
암호화 및 인증서 검증 구성
Microsoft.Data.SqlClient 4.0 및 이후 버전은 기본적으로 Encrypt를 true로 설정합니다. Microsoft. Data.SqlClient 5.0 및 이후 버전은 TDS 8.0을 협상하는 서버도 지원합니다Encrypt=Strict.
사용:
-
Encrypt=Strict서버가 TDS 8.0을 지원하고 인증서를 가지고 있으면 클라이언트가 검증할 수 있습니다. -
Encrypt=true다른 지원 서버와의 암호화 연결을 위해 사용됩니다. -
TrustServerCertificate=false, 기본 설정으로, 생산 인증서 검증을 위한 것입니다.
일반적인 연결 문제 해결 방법으로 TrustServerCertificate=true를 사용하지 마세요. 채널은 암호화하지만 서버 신원 검증은 건너뛸 수 있습니다. 신뢰할 수 있는 인증서가 없는 통제된 개발 환경에만 제한하세요.
서버 요구사항, 버전 동작 및 인증서 옵션에 대해서는 암호화 및 인증서 검증을 참조하세요.
연결 문자열 문법을 이해하세요
연결 문자열은 세미콜론으로 구분된 키워드와 값 쌍의 목록입니다:
Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=true
다음 규칙을 따릅니다.
- 키워드 이름은 대소문자에 구분되지 않습니다.
- 값은 대소문자에 따라 구분될 수 있습니다.
- 마지막 세미콜론은 선택 사항입니다.
- 세미콜론이나 앞 또는 뒤 공백이 포함된 값에 단일 또는 이중 인용 부호를 붙이세요.
- 가치를 둘러싼 인용문을 피하려면 두 배로 맞추세요.
- 중복 키워드를 사용하지 마세요. 파서는 마지막 값을 사용하기 때문에 효과적인 구성이 검토되기 어렵습니다.
승인된 키워드와 별칭 집합은 제공자에게 속합니다.
Microsoft.Data.SqlClient에서 허용되는 연결 문자열은 System.Data.SqlClient 또는 다른 데이터 공급자에서 작동하지 않을 수 있습니다.
연결 끈을 안전하게 만들기
코드에서 값을 추가, 검증 또는 대체해야 할 때 SqlConnectionStringBuilder를 사용하세요. 신뢰할 수 없는 값을 연결 문자열에 연결하지 마세요.
string baseConnectionString =
configuration.GetConnectionString("Orders")
?? throw new InvalidOperationException(
"Connection string 'Orders' wasn't configured.");
var builder = new SqlConnectionStringBuilder(baseConnectionString)
{
ApplicationName = "Orders.Api",
ConnectTimeout = 30,
};
string connectionString = builder.ConnectionString;
건축업자:
- 지원되지 않는 키워드와 유효하지 않은 값은 거부합니다.
- 별칭을 표준 속성에 매핑합니다.
- 필요할 때 가치를 제시하세요.
- 값을 통해 다른 키워드가 주입되는 것을 방지합니다.
빌더는 프로세스 메모리에 들어가면 비밀번호나 토큰을 보호하지 않습니다. 서버, 신원, 인증서 설정이 안전한지 결정하지도 않습니다.
코드 외부에 연결 정보를 저장합니다
애플리케이션이 사용하는 구성 시스템에서 연결 문자열을 불러옵니다. 현재 .NET 애플리케이션은 일반적으로 환경 변수, 로컬 개발을 위한 사용자 비밀, Azure App Configuration, 그리고 Azure Key Vault 지원 구성을 사용합니다.
다음 규칙을 지키세요:
- 비밀번호, 클라이언트 비밀, 액세스 토큰, 프로덕션 연결 문자열은 커밋하지 마세요.
- 연결 문자열에 비밀번호가 필요 없는 신원 기반 인증 방식을 선호하세요.
- 구성 소스 접근을 제한하세요.
- 저장된 비밀을 순환시키고, 캐시하는 애플리케이션을 재시작하거나 새로고침하세요.
- 로그, 예외, 트레이스, 텔레메트리에 연결 문자열을 쓰지 마세요.
- 개방된 연결이 연결 문자열을 통해 보안 민감 값을 노출하지 않도록 기본값으로 둡
Persist Security Info=false니다.
.NET 구성 제공자에 대해서는 .NET 내 구성 항목을 참조하세요. 추가 제어는 연결 정보 보호(Protect connection information)를 참조하세요.
수영장 키를 안정적으로 유지하세요
연결 풀링은 정확히 일치하는 연결 구성을 풀 키의 일부로 사용합니다. 동등한 문자열은 텍스트가 달라질 때, 예를 들어 키워드가 다른 순서로 나타나는 경우를 포함해 별도의 풀을 생성할 수 있습니다.
애플리케이션 시작 시 하나의 정식 연결 문자열을 만들고 재사용하세요. 요청 ID, 사용자 이름, 접근 토큰 또는 요청별 값을 문자열에 추가하지 마세요. 전체 핵심 규칙은 SQL Server 연결 풀링을 참조하세요.
별도의 연결 및 명령 설정
연결 문자열은 연결 설정과 세션 동작을 제어합니다. 명령어가 하나의 SQL 연산을 제어합니다.
| 요구 사항 | 구성 켜기 |
|---|---|
| 연결을 설정하거나 풀에서 연결 하나를 가져오는 데 허용되는 시간 |
Connect Timeout 연결 옵션 |
| 기본 명령 실행 타임아웃 |
Command Timeout 드라이버 버전에서 지원되는 연결 옵션 |
| 한 명령어에 대한 타임아웃 | CommandTimeout |
| 발신자에 의한 취소 |
CancellationToken 비동기 API로 전달됨 |
| 연결을 열거나 명령 실행을 위한 재시도 정책 |
SqlConnection 또는 SqlCommand에서 설정 가능한 재시도 로직 |
긴 타임아웃을 재시도 논리로 여기지 마세요. 타임아웃은 한 번의 대기 시간을 제한합니다. 재시도는 또 한 번의 시도를 시작하는 것이며, 횟수에 제한이 있어야 하고 반복해도 안전해야 합니다.
버전 민감 동작 검토
| 드라이버 버전 | 연결 문자열 변경 |
|---|---|
| 4.0 |
Encrypt 기본값은 true입니다. |
| 5.0 |
Encrypt=Strict 및 HostNameInCertificate 이용이 가능합니다.
SqlConnectionStringBuilder.Encrypt 을 사용합니다 SqlConnectionEncryptOption. |
| 5.1 |
ServerCertificate 서버 인증서를 파일과 대조할 수 있습니다. |
| 5.2 | AccessTokenCallback 이 토큰은 재생 가능한 애플리케이션 제공 토큰에 대해 제공됩니다. |
| 7.0 | 드라이버에서 제공하는 Microsoft Entra ID 인증이 Microsoft.Data.SqlClient.Extensions.Azure로 이동합니다. |
| 7.0.2 | 핵심 드라이버와 그 동반 패키지는 정렬된 버전을 사용합니다. |
지원되는 안정된 드라이버 버전을 사용하고 업데이트 전에 릴리스 노트를 읽으세요. 현재 버전에 대해서는 SqlClient 드라이버 지원 수명주기를 참조하세요.