Microsoft.Data.SqlClient 연결 문자열

Microsoft.Data.SqlClient 연결 문자열은 세미콜론으로 구분된 keyword=value 쌍의 목록입니다. SqlConnection 또는 SqlConnectionStringBuilder에게 넘기세요:

Server=tcp:sql.example.com,1433;Database=Orders;Integrated Security=true;Encrypt=Strict

연결 문자열은 네 가지 질문에 답합니다:

1. 애플리케이션이 사용하는 서버와 데이터베이스는 무엇인가요?
2. 애플리케이션은 어떤 신원으로 실행되나요?
3. 클라이언트는 서버 인증서를 어떻게 검증하나요?
4. 워크로드에 어떤 연결 동작이 필요하나요?

이 글에서는 이러한 선택지들과 드라이버가 텍스트를 읽을 때 사용하는 규칙을 다룹니다. 모든 키워드, 동의어 및 기본값에 대해서는 연결 옵션을 참조하세요. 코드에서 연결 문자열을 생성하고 변경하려면 연결 문자열 빌더를 참조하세요.

인증 패턴을 선택하세요

배치에 맞는 패턴을 사용하세요. 각 자리 표시자(예: <server>)를 값으로 대체하세요.

Environment	Pattern	연결 문자열
도메인 또는 로컬 Windows 계정을 사용하는 Windows의 SQL Server	Windows 통합 인증	Server=<server>;Database=<database>;Integrated Security=true;Encrypt=true
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
개발자 워크스테이션이 Microsoft Fabric에서 SQL 데이터베이스에 연결됨	Microsoft Entra ID 기본 자격 증명 체인	Server=tcp:<server>,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>;Password=<password>;Encrypt=true

Windows 통합 인증은 프로세스의 보안 컨텍스트로 연결됩니다. 데스크톱이나 콘솔 애플리케이션의 경우, 보통 로그인한 사용자입니다. 웹 애플리케이션이나 Windows 서비스의 경우, 애플리케이션 풀이나 서비스 계정입니다. 사칭은 ID를 바꿀 수 있습니다. 애플리케이션이 실제로 사용하는 ID에 로그인 및 데이터베이스 권한을 부여하세요.

이 세 가지 Windows 통합 인증 형태는 동등합니다:

Server=sql.example.com;Database=Orders;Integrated Security=true;Encrypt=true
Server=sql.example.com;Database=Orders;Integrated Security=SSPI;Encrypt=true
Server=sql.example.com;Database=Orders;Trusted_Connection=yes;Encrypt=true

만약 문자열이 User ID을(를) 설정하고 Password 및 Integrated Security=true도 설정하면 드라이버는 Windows 인증을 사용하고 사용자 이름과 비밀번호를 무시합니다.

Microsoft. Data.SqlClient 7.0 및 이후 버전은 드라이버 제공 Microsoft Entra ID 인증 방법에 대해 버전 매칭 Microsoft.Data.SqlClient.Extensions.Azure 패키지가 필요합니다. 애플리케이션 코드가 액세스 토큰이나 액세스 토큰 콜백을 제공할 때는 그런 패키지가 필요하지 않습니다.

허용 Authentication 된 값에 대해서는 인증 옵션을 참조하세요. 인증에는 또한 서버에서의 데이터베이스 사용자, 권한 및 신원 구성이 필요합니다. 설정 단계에 대해서는 Microsoft Entra ID 인증 및 SQL Server 인증을 참조하세요.

서버와 데이터베이스를 지정하세요

Server 및 Database은 가독성이 가장 좋은 키워드 이름입니다. 빌더는 이들을 정식 표준 형태인 Data Source와 Initial Catalog로 표기합니다. 네 가지 이름 모두 연결 문자열 내에서 작동합니다.

Server를 다음 형식 중 하나로 설정하세요:

Form	Example	사용
호스트 이름	Server=sql.example.com	포트 1433의 기본 인스턴스입니다.
호스트 이름 및 포트	Server=tcp:sql.example.com,1433	특정 TCP 포트입니다. 포트는 콜론이 아니라 쉼표로 구분하세요.
명명된 인스턴스	Server=sql.example.com\SALES	명명된 인스턴스. 드라이버는 UDP 포트 1434의 SQL Server 브라우저 서비스에 포트를 요청합니다.
로컬 서버	Server=(local) 또는 Server=.	로컬 컴퓨터의 기본 인스턴스입니다.
LocalDB	Server=(localdb)\MSSQLLocalDB	Windows의 SQL Server Express LocalDB 이 연결은 Encrypt=Mandatory를 사용해도 암호화되지 않았고, Encrypt=Strict가 실패합니다.
명명된 파이프	Server=np:\\sql.example.com\pipe\sql\query	Windows의 명명된 파이프 연결

프로덕션 환경에서는 tcp:와 완전한 정규화 호스트 이름, 그리고 명시적인 포트를 사용하세요. IP 주소가 아니라 서버 인증서와 일치하는 DNS 이름을 사용하세요. 인증서 검증은 연결 문자열의 서버 이름과 인증서의 이름을 비교하기 때문입니다.

SQL 인증과 사용자 이름 user@servername 양식으로 Azure SQL Database에 연결하면, servername 부분은 Server의 서버와 일치해야 합니다.

가용성 그룹 리스너 또는 장애 조치(failover) 클러스터 인스턴스의 경우에도 Multi Subnet Failover의 을(를) 검토하세요.

암호화 및 인증서 검증 구성

키워드는 Encrypt 어쨌든 다음과 같은 값을 받아들입니다:

Value	건설자 가치	Meaning
Strict	Strict	TDS 8.0을 사용합니다. 로그인 전에 연결을 암호화하고 항상 서버 인증서를 검증합니다.
Mandatory, true, yes	True	연결을 암호화합니다. 이 값은 기본값입니다.
Optional, false, no	False	서버가 암호화를 요구할 때만 전체 연결을 암호화합니다. 서버가 암호화를 지원하지만 필요하지 않을 때는 로그인 패킷만 암호화합니다.

서버가 TDS 8.0을 지원하고 클라이언트가 검증할 수 있는 인증서를 가지고 있을 때 사용 Strict 하세요. Azure SQL Database와 Microsoft Fabric의 SQL 데이터베이스가 이를 지원합니다. LocalDB 연결은 Strict을 사용해도 암호화되지 않으며 Mandatory은 실패합니다.

Trust Server Certificate 및 Encrypt 값은 다음과 같이 결합됩니다:

암호화	서버 인증서 신뢰	Result
Optional	false	서버가 암호화를 요구할 때는 전체 연결이 암호화되고, 서버 인증서는 검증되어야 합니다. 그렇지 않으면 연결이 실패합니다. 서버가 암호화를 지원하지만 필요하지 않을 때는 로그인 패킷만 암호화되며, 연결에서 AccessToken 또는 AccessTokenCallback를 사용하지 않는 한 드라이버는 서버 인증서를 검증하지 않습니다. 서버가 암호화를 지원하지 않으면 아무것도 암호화되지 않습니다.
Optional	true	서버가 암호화를 요구할 때는 전체 연결이 암호화됩니다. 서버가 암호화를 지원하지만 이를 요구하지 않는 경우 로그인 패킷만 암호화됩니다. 드라이버는 서버 인증서를 검증하지 않습니다.
Mandatory	false	암호화는 서버 인증서가 검증될 때만 이루어집니다. 그렇지 않으면 연결이 실패합니다.
Mandatory	true	암호화는 항상 이루어지지만, 드라이버가 서버 인증서를 검증하지 않습니다.
Strict	무시됨	암호화는 항상 이루어지며, 서버 인증서는 반드시 검증되어야 합니다. 그렇지 않으면 연결이 실패합니다.

운영 환경에서 연결 오류를 해결하기 위해 Trust Server Certificate=true을(를) 설정하지 마세요. 채널을 암호화하지만 서버의 신원을 확인하지는 않습니다. 신뢰할 수 있는 인증서를 사용할 수 없는 개발 환경으로만 제한하세요.

Data Source의 서버 이름이 인증서와 일치하지 않으면, Host Name In Certificate를 인증서에 있는 이름으로 설정하세요. SqlClient는 서버 이름이 일치하지 않을 때만 확인하고, 인증서를 핀하지 않습니다. 특정 인증서 하나만 받으려면, Server Certificate를 PEM, DER 또는 CER 파일의 경로로 설정하세요:

Server=tcp:sql.example.com,1433;Encrypt=Strict;Host Name In Certificate=sqlhost.example.com
Server=tcp:sql.example.com,1433;Encrypt=Strict;Server Certificate=C:\certificates\server.cer

전체 검증 규칙은 암호화 및 인증서 검증을 참조하세요.

연결 풀링 사용

풀링은 기본적으로 켜져 있습니다. SqlConnection 연결을 열면 드라이버는 해당 연결과 일치하는 풀에서 물리적 연결을 가져옵니다. 연결을 닫거나 폐기하면 물리적 연결이 닫히지 않고 다시 풀로 돌아옵니다. 풀링된 열기는 네트워크 연결, TLS 핸드셰이크, 로그인을 건너뜁니다.

다음 규칙을 따릅니다.

• 필요하기 직전에 연결을 열고, 작업을 마치자마자 using 또는 await using를 사용하여 연결을 해제합니다. 폐기되지 않은 연결은 계속 풀에서 점유된 상태로 남아 있고, 풀이 고갈될 수 있습니다.

• 시작 시 연결 문자열을 한 번 만들고 재사용하세요. 풀 키는 연결 문자열의 정확한 텍스트를 포함하므로, 다른 키워드 순서, 동의어, 또는 요청 ID나 사용자 이름과 같은 요청별 값은 별도의 풀을 만듭니다. 빌더는 하나의 표준형을 작성합니다. 자세한 내용은 하나의 표준 연결 문자열 유지을 참조하세요.

• 통합 인증에서 각 Windows 신원마다, 각 SqlCredential 인스턴스마다, 그리고 각 AccessToken 값마다 별도의 풀이 존재할 것으로 예상하세요. 각 연결에서 AccessTokenCallback을(를) 설정하는 대신, 드라이버에서 제공하는 AccessToken 메서드나 재사용되는 Authentication 메서드를 사용하세요.

• 기본값이 100인 Max Pool Size 값을 높이기 전에, 삭제되지 않은 연결을 찾아보세요. 풀 내 모든 연결이 사용 중일 때, Open는 최대 Connect Timeout까지 기다린 후 다음을 throw합니다: InvalidOperationException

  Timeout expired.  The timeout period elapsed prior to obtaining a connection from the pool.  This may have occurred because all pooled connections were in use and max pool size was reached.
  

• 각 풀마다 서버 용량을 계획하세요. 각 프로세스 또는 .NET Framework의 각 애플리케이션 도메인은 자체 풀을 가지고 있습니다. 서버와의 연결 수는 각 프로세스의 풀 수와 애플리케이션 인스턴스 수를 곱한 값에 Max Pool Size까지 이를 수 있습니다.

• 풀링 문제를 우회하도록 Pooling=false를 설정하지 마세요. 모든 오픈 후 전체 로그인이 이루어집니다.

너무 오래 유휴 상태로 유지되는 풀링 연결을 닫으려면 연결 유휴 시간 제한을 참조하세요. 풀 키, 크기, 지우기 및 트랜잭션에 대해서는 SQL Server 연결 풀링을 참조하세요.

별도의 연결 및 명령 설정

연결 문자열은 연결 설정과 세션 동작을 제어합니다. 명령어가 하나의 SQL 연산을 제어합니다.

요구 사항	구성 켜기
연결을 맺거나 풀에서 연결을 가져오는 데 허용되는 시간	Connect Timeout 키워드
연결에서 명령어에 대한 기본 타임아웃	Command Timeout 키워드
한 명령어에 대한 타임아웃	CommandTimeout
발신자에 의한 취소	CancellationToken 비동기 메서드로 전환됨
연결을 열거나 명령 실행을 위한 재시도 정책	설정 가능한 재시도 로직 또는 SqlConnectionSqlCommand

더 긴 타임아웃은 재시도 논리가 아닙니다. 타임아웃은 한 번의 대기 시간을 제한합니다. 재시도는 또 다른 시도를 시작하며, 반드시 경계가 있고 안전해야 반복됩니다.

애플리케이션 ID 보고

Application Name 서버가 APP_NAME()를 통해 보고하는 이름을 설정합니다. 배포된 각 워크로드마다 하나의 안정적인 이름을 사용하세요. 애플리케이션을 위한 연결을 열어주는 프레임워크와 도구들도 연결 문자열 키워드가 없는 RegisteredApplication 속성을 통해 스스로를 보고할 수 있습니다. 자세한 내용은 애플리케이션 ID 보고를 참조하세요.

연결 끈을 안전하게 만들기

코드가 값을 추가하거나 변경할 때 사용 SqlConnectionStringBuilder 하세요. 신뢰할 수 없는 텍스트를 연결 문자열에 연결하지 마세요. 그 텍스트의 세미콜론이 키워드를 추가하거나 대체할 수 있기 때문입니다. 빌더는 값을 검증하고, 동의어를 정식 키워드에 매핑하며, 각 값을 따옴표로 표시해 값이 키워드를 추가할 수 없도록 합니다. 예시는 연결 문자열 빌더를 참조하세요.

코드 외부에 연결 정보를 저장합니다

애플리케이션의 구성 시스템에서 연결 문자열을 불러옵니다. .NET 애플리케이션은 일반적으로 환경 변수, 로컬 개발용 사용자 비밀, Azure App Configuration, Azure Key Vault를 사용합니다.

다음 규칙을 따릅니다.

• 비밀번호, 클라이언트 비밀, 액세스 토큰, 프로덕션 연결 문자열은 커밋하지 마세요.
• 연결 문자열에 비밀번호가 필요 없는 인증 방식을 선호합니다.
• 구성 소스 접근을 제한하세요.
• 저장된 시크릿을 교체하고, 해당 시크릿을 캐시하는 애플리케이션을 재시작하거나 새로 고치세요.
• 로그, 예외, 트레이스, 텔레메트리에 연결 문자열을 쓰지 마세요.
• 기본값으로 두Persist Security Info=false세요. 열린 연결이 해당 ConnectionString 속성을 통해 비밀번호를 노출하지 않도록 하세요.

.NET 구성 제공자에 대해서는 .NET 내 구성 항목을 참조하세요. 더 많은 제어 사항은 연결 정보 보호를 참조하세요.

파싱 규칙

운전자는 다음과 같은 규칙을 적용합니다:

• 키워드는 대/소문자를 구분하지 않습니다. DATABASE, Database, database는 동일한 키워드입니다.
• 많은 키워드가 동의어를 가지고 있습니다. Server 및 Data Source은 같은 값으로 설정됩니다. Connection options 문서에는 각 키워드의 동의어가 나와 있습니다.
• 키워드가 두 번 이상 등장하면 마지막 값이 승리합니다. 동의어도 같은 키워드로 간주됩니다.
• 드라이버는 키워드 주변과 인용되지 않은 값 주변의 공백을 무시합니다.
• 뒤에 세미콜론은 선택 사항입니다.
• 운전자가 모르는 키워드가 메시지와 Keyword not supported함께 던 ArgumentException 져집니다.

값은 키워드에 따라 대소문자 구분이 될 수 있습니다. 비밀번호는 대소문자를 구분합니다. Encrypt=STRICT 그리고 Encrypt=strict 동일합니다.

이 프로그램은 빌더가 키워드를 정규화하고, 중복을 해결하며, 특수 문자를 인용하는 방식을 보여줍니다. .NET Framework 탭은 C# 7.3을 사용합니다. 샘플을 실행하는 프로젝트를 만들려면 ' 프로젝트 만들기'를 참조하세요.

.NET

using Microsoft.Data.SqlClient;

// Synonyms and keyword case are normalized to canonical keywords.
var parsed = new SqlConnectionStringBuilder(
    "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
Console.WriteLine(parsed.ConnectionString);

// When a keyword repeats, the last value wins.
var duplicate = new SqlConnectionStringBuilder(
    "Server=sql.example.com;Database=Orders;Database=Archive");
Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

// The builder quotes values that contain delimiters.
var quoted = new SqlConnectionStringBuilder
{
    DataSource = "sql.example.com",
    UserID = "app_user",
    Password = "a;b'c\"d",
};
Console.WriteLine(quoted.ConnectionString);
Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");

.NET 프레임워크

using System;
using Microsoft.Data.SqlClient;

class Program
{
    static void Main()
    {
        // Synonyms and keyword case are normalized to canonical keywords.
        var parsed = new SqlConnectionStringBuilder(
            "server=tcp:sql.example.com,1433;DATABASE=Orders;uid=app_user;encrypt=yes;timeout=30");
        Console.WriteLine(parsed.ConnectionString);

        // When a keyword repeats, the last value wins.
        var duplicate = new SqlConnectionStringBuilder(
            "Server=sql.example.com;Database=Orders;Database=Archive");
        Console.WriteLine($"InitialCatalog: {duplicate.InitialCatalog}");

        // The builder quotes values that contain delimiters.
        var quoted = new SqlConnectionStringBuilder
        {
            DataSource = "sql.example.com",
            UserID = "app_user",
            Password = "a;b'c\"d",
        };
        Console.WriteLine(quoted.ConnectionString);
        Console.WriteLine($"Round trip: {new SqlConnectionStringBuilder(quoted.ConnectionString).Password == quoted.Password}");
    }
}

결과는 다음과 같습니다.

Data Source=tcp:sql.example.com,1433;Initial Catalog=Orders;User ID=app_user;Connect Timeout=30;Encrypt=True
InitialCatalog: Archive
Data Source=sql.example.com;User ID=app_user;Password="a;b'c""d"
Round trip: True

첫 번째 줄은 각 동의어가 그 표준 키워드로 대체된 것을 보여줍니다: server 에 의해 Data Source, DATABASE 에 의해, 에 uid 의Initial Catalog해, 에 timeoutConnect Timeout의해, 에 의해 User ID대체되었습니다.

견적 가치

세미콜론이 포함되어 있거나 공백으로 시작하거나 끝나거나 인용 부호로 시작하거나 끝나는 값은 이중 인용 부호(")나 단일 인용 부호'()로 감싸세요. 따옴표 값 안에 인용부호를 두 번 적으세요.

Value	연결 문자열 형식
a;b	Password="a;b"
abc'	Password="abc'"
say "hi"	Password='say "hi"'
a;b'c"d	Password="a;b'c""d"

규칙을 인용하는 것은 쉽게 틀릴 수 있습니다. SqlConnectionStringBuilder 속성을 통해 값을 설정하고 빌더가 해당 값을 따옴표로 묶도록 하세요. 자세한 내용은 '안전하게 연결 문자열을 구축하기'를 참조하세요.

불리언 값을 명시하세요

불 값을 가진 키워드는 어쨌든 , false, yes, , 를 no받아들true입니다. Integrated Security또한 를 받아들이며sspi, 이는 를 의미합니다.true 빌더는 False 또는 True라고 씁니다.

다른 운전자들의 키워드 사용

Microsoft.Data.SqlClient는 Driver 및 Provider와 같은 ODBC 또는 OLE DB 키워드를 받지 않습니다. 다른 드라이버에서 연결 문자열을 옮길 때 이 키워드들을 제거하세요. System.Data.SqlClient연결 문자열은 Microsoft에서 작동합니다. Data.SqlClient, 다음과 같은 차이점이 있습니다:

• Encrypt의 기본값은 Microsoft.Data.SqlClient에서 Mandatory입니다. 신뢰할 수 있는 인증서가 없는 서버는 인증서 검증에 실패합니다. 서버에 신뢰할 수 있는 인증서를 설치하세요.
• .NET에서는 Network Library, Connection Reset, Transparent Network IP Resolution가 지원되지 않습니다. 제거하세요.
• Context Connection=true는 지원되지 않습니다.
• Asynchronous Processing는 지원되는 키워드가 아니며 ArgumentException 오류를 발생시킵니다. 제거합니다. 비동기식 메서드는 이 없이도 작동합니다.
• Type System Version=SQL Server 2000는 지원되지 않습니다. 연결을 생성하면 ArgumentException가 발생합니다. 사용하세요: Latest, SQL Server 2012, SQL Server 2008, 또는 SQL Server 2005.

관련 콘텐츠

• .NET 앱에서 Microsoft.Data.SqlClient 사용
• 연결 옵션
• 연결 문자열 빌더
• 데이터 소스에 연결하세요
• SQL Server 연결 풀링
• Microsoft Entra ID 인증
• 암호화 및 인증서 유효성 검사
• SQL Server Express 사용자 인스턴스
• SqlClient 드라이버 지원 기간