Microsoft. Data.SqlClient for SQL Server

ADO.NET 다운로드

Microsoft. Data.SqlClient는 SQL Server, Azure SQL Database, Azure SQL Managed Instance, Azure Synapse Analytics, Microsoft Fabric의 SQL 데이터베이스, Microsoft Fabric의 Warehouse에 지원되는 .NET 데이터 제공자입니다. NuGet 패키지로 배포되며, .NET 런타임과는 독립적으로 진화하고 새로운 개발을 위해 대체 System.Data.SqlClient 합니다. .NET 애플리케이션에 연결, 명령어, 결과 처리, 트랜잭션, 벌크 복사, SQL Server 고유 기능을 제공합니다.

시작점 선택

Azure SQL 대한 프로덕션 기준

이 스니펫을 운영 지향 Azure SQL 데이터 접근 경로의 출발점으로 활용하세요. 서버와 데이터베이스 이름을 IConfiguration에서 읽기 때문에, 값은 호스트가 연결한 구성 제공자(예: appsettings.json, 환경 변수, Azure App Configuration, Key Vault에 저장된 설정)에서 가져옵니다. 이 구성은 다음과 같은 특징들을 결합합니다:

  • 전송 계층 보안(TLS).
  • 관리 ID입니다.
  • 유휴 연결 복원력.
  • 구성 가능한 재시도 논리(CRL)를 통한 초기 연결 재시도와 구조화된 로깅.
  • 쿼리 도중 발생하는 일시적 오류에 대한 명령 수준의 재시도
  • 빠른 페일오버 그룹 복구.
  • 취소 토큰을 받는 비동기 호출.

보안을 강화하고 환경 간 구성을 지원하기 위해 연결 정보를 코드 외부에 보관하세요. 운영 환경에서는 연결 정보를 애플리케이션 구성 시스템에 저장하고, 민감한 값은 Azure Key Vault를 사용하세요. 자세한 내용은 연결 정보 보호참조하세요.

이 글의 C# 스니펫은 간결함을 위해 지시문과 클래스 래퍼를 생략했습니다 using .

이 스니펫은 .NET 8 또는 이후 버전을 대상으로 하는 프로젝트를 가정하며, Microsoft.Data.SqlClient.Extensions.Azure 및 Microsoft.Data.SqlClient 7.1.1 패키지를 참조합니다. .NET Generic Host 또는 ASP.NET Core와 같은 호스트가 ILogger 및 IConfiguration를 제공하고, 구성은 Sql:Server에서 서버 이름을, Sql:Database에서 데이터베이스 이름을 제공합니다.

public static async Task<string> QueryDatabaseNameAsync(
    IConfiguration config, ILogger logger, CancellationToken cancellationToken = default)
{
    string server = config["Sql:Server"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Server'.");
    string database = config["Sql:Database"]
        ?? throw new InvalidOperationException("Missing configuration value 'Sql:Database'.");

    var builder = new SqlConnectionStringBuilder
    {
        DataSource = server,
        InitialCatalog = database,
        Authentication = SqlAuthenticationMethod.ActiveDirectoryManagedIdentity,
        Encrypt = SqlConnectionEncryptOption.Strict, // TDS 8.0 encryption (server must support it)
        ConnectTimeout = 30,                         // per-attempt connect timeout in seconds
        // Retry transient failures during Open() and reconnect a dropped idle connection.
        // The configurable provider below adds another policy around Open().
        ConnectRetryCount = 3,
        ConnectRetryInterval = 10,
        MultiSubnetFailover = true,                  // recommended for TCP endpoints; enables parallel connect
        // ApplicationIntent = ApplicationIntent.ReadOnly, // uncomment to route to a readable secondary
    };

    // Add exponential backoff and jitter around Open().
    // TransientErrors is null, so the provider uses the driver's built-in transient error list.
    var openRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 5,
            DeltaTime = TimeSpan.FromSeconds(3),
            MaxTimeInterval = TimeSpan.FromSeconds(60),
        });
    openRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL connection to {Server}/{Database} (attempt {Attempt}) after {Delay}",
            server, database, args.RetryCount, args.Delay);
    };

    // Retry commands that hit deadlocks, lock timeouts, or common Azure SQL transient errors
    // mid-query on an established connection. Only attach this provider to commands whose
    // effect is safe to repeat.
    var commandRetry = SqlConfigurableRetryFactory.CreateExponentialRetryProvider(
        new SqlRetryLogicOption
        {
            NumberOfTries = 4,
            DeltaTime = TimeSpan.FromSeconds(5),
            MaxTimeInterval = TimeSpan.FromSeconds(30),
            // Deadlock victim, lock-request timeout, and common Azure SQL transient errors.
            TransientErrors = new[] { 1205, 1222, 10928, 10929, 40197, 40501, 40613, 49918 },
        });
    commandRetry.Retrying += (_, args) =>
    {
        Exception last = args.Exceptions[^1];
        logger.LogWarning(
            last,
            "Retrying SQL command (attempt {Attempt}) after {Delay}",
            args.RetryCount, args.Delay);
    };

    await using var connection = new SqlConnection(builder.ConnectionString)
    {
        RetryLogicProvider = openRetry,
    };
    await connection.OpenAsync(cancellationToken);

    await using var command = new SqlCommand("SELECT DB_NAME()", connection)
    {
        RetryLogicProvider = commandRetry,
        CommandTimeout = 30,
    };

    var name = (string)await command.ExecuteScalarAsync(cancellationToken);
    logger.LogInformation("Connected to database {DatabaseName}", name);
    return name;
}

이 메서드는 연결된 데이터베이스 이름을 반환하고 Connected to database <database>를 기록합니다. 재시도가 발생하면, 재시도마다 이를 유발한 예외와 함께 경고가 하나 기록됩니다.

각 부분이 작동하는 방식:

  • 타겟: Microsoft Entra 인증용으로 구성된 모든 SQL 데이터베이스 엔진 엔드포인트: Azure SQL Database, Azure SQL Managed Instance, Microsoft Fabric의 SQL 데이터베이스, 그리고 Azure Virtual Machines에서 실행되거나 Azure Arc를 통해 사용하도록 설정된 SQL Server 2022 및 이후 버전.
  • Encrypt = SqlConnectionEncryptOption.Strict: TDS 8.0 암호화를 선택함. SQL Server 2022 이후 버전, Azure SQL Database, Azure SQL Managed Instance, 또는 Microsoft Fabric의 SQL 데이터베이스가 필요합니다. 오래된 서버에는 SqlConnectionEncryptOption.Mandatory를 사용하세요.
  • ActiveDirectoryManagedIdentity: Azure App Service, Azure Functions 또는 Azure 가상 머신과 같은 경우처럼 관리되는 신원을 사용할 수 있는 곳에서만 작동합니다. 로컬 개발을 위해서는 Azure CLI, Visual Studio 로그인 및 기타 자격 증명 소스를 시도하는 SqlAuthenticationMethod.ActiveDirectoryDefault를 사용하세요. 각 소스를 프로빙하면 연결이 느려지니 프로덕션에서 제외하세요. 자세한 내용은 기본 인증 사용을 참조하세요.
  • MultiSubnetFailover = true: 모든 확인된 IP 주소에 TCP 연결을 병렬로 시도하며, 가장 먼저 성공한 연결을 사용하여 느린 IP별 순차 탐색을 피합니다. Azure SQL Database, Azure SQL Managed Instance, Microsoft Fabric의 SQL 데이터베이스, 가용성 그룹 리스너, 그리고 failover 클러스터 인스턴스에 대해 설정하세요. 단일 IP 대상에는 안전합니다. 명명된 인스턴스, TCP 이외의 프로토콜, 64개 이상의 IP 주소를 가진 인스턴스 또는 더 이상 사용되지 않는 기능인 데이터베이스 미러링에서는 지원되지 않습니다. 대신 Always On 가용성 그룹를 사용하세요. 자세한 내용은 고가용성 및 재해 복구 및 투명 네트워크 IP 해석 비활성화를 참조하세요.
  • ConnectRetryCount = 3 그리고 ConnectRetryInterval = 10: 드라이버는 Open() 중에 해당 조건의 일시적 장애에 대해 다시 시도하고, 다음 명령에서 끊어진 유휴 연결을 다시 연결한다. 기본 수는 1입니다. 10초 간격으로 세 번 시도하면 더 긴 재구성이나 장애 조치 기간도 버틸 수 있습니다. 드라이버는 서버 이름이 알려진 Azure SQL 도메인(예: .database.windows.net)으로 끝날 때만 1을 2로 올리므로, 커스텀 DNS 별칭은 1을 받습니다.
  • openRetry: SqlConnection.RetryLogicProvider에 할당되며, Open() 주변에 지수적 백오프를 추가합니다. 드라이버는 ConnectTimeout가 만료되면 내부 재시도를 중단하므로, 최악의 경우 OpenAsync이 예외를 발생시키기 전까지 각각 최대 30초의 시도를 5번 하고, 백오프 시간이 추가됩니다. 유휴 재연결 시도는 전체 openRetry 정책을 실행하며, 해당 정책이 재시도를 다 소진하면 유휴 복구가 종료됩니다.
  • Serverless auto-pause: Azure SQL Database serverless의 경우 ConnectTimeout자동 일시 중지 지연 시간을 최소 60초로 올려주세요. 첫 번째 Open()는 데이터베이스가 재개되는 동안 오류 40613와 함께 실패할 수 있으며, openRetry에서 이를 다시 시도합니다. 클라이언트 측 타임아웃은 오류 -2로 나타나며, 이 경우 재시도되지 않으므로 각 연결 시도는 재개보다 더 오래 지속되어야 합니다. 자세한 내용은 자동 일시정지와 자동 재개를 참조하세요.
  • commandRetry: 명령을 재실행해도 안전한 경우에만 MERGE에 부착하세요: 읽기, 자연 키로 보호되는 SqlCommand.RetryLogicProvider, 저장 프로시저를 통한 업서트, 기타 멱등 연산. 트랜잭션 내에서 재시도를 건너뛰기 때문에, 애플리케이션 코드는 멀티 스테이트먼트 트랜잭션을 다시 시도해야 합니다. ExecuteReader 및 ExecuteScalar는 첫 결과 세트가 시작되기 전에 반환된 오류만 다시 시도합니다. ExecuteNonQuery 호출 전체를 다시 시도합니다.
  • 일시적 오류 목록: TransientErrors 설정은 기본 제공 목록을 대체합니다. 대신 확장하려면 SqlConfigurableRetryFactory.BaselineTransientErrors(Microsoft.Data.SqlClient 7.0 및 이후 버전)를 사용하세요.
  • Retrying 이벤트: Retrying는 각 재시도 전에 재시도 횟수, 다음 지연, 그리고 지금까지 발생한 예외와 함께 발생합니다. ILogger 또는 텔레메트리 파이프라인으로 라우팅하세요.
  • 예외: 이 메서드는 예외를 포착하지 않습니다. 소진된 공급자가 각 시도의 예외와 함께 AggregateException를 throw합니다. 비일시적 오류가 원래 예외로 전파됩니다. 발신자는 나머지 요청 컨텍스트와 함께 한 번 로그를 남깁니다.
  • 취소: CancellationToken는 재시도 사이에 제공자가 더 이상 대기하지 않도록 합니다. 운전자의 Open 단일 ConnectRetryInterval 시도 내 대기를 방해하지 않습니다. 자세한 내용은 비동기 프로그래밍을 참조하세요.
  • 프로바이더 수명: 스니펫은 호출할 때마다 재시도 프로바이더를 생성하여 자립성을 유지합니다. 애플리케이션에서는 한 번 만들고 재사용하세요.

이 구성의 각 부분에 대한 자세한 내용은 다음을 참조하세요.

핵심 데이터 접근 업무를 배우세요

연결 후에는 다음 글들을 순서대로 활용하세요:

  1. 결과 형태를 선택하고 Transact-SQL(T-SQL)을 실행하려면 명령을 실행하세요.
  2. 데이터베이스 사양에 맞게 매개변수를 설정하세요.
  3. SqlDataReader로 데이터를 검색 하여 행과 여러 결과를 처리합니다.
  4. 출력 매개변수와 반환 값을 사용하도록 저장 프로시저를 수정하세요.
  5. 비동기 프로그래밍과 취소를 사용 해 호출자 취소와 제한 타임아웃을 추가하세요.
  6. 재시도나 생산 진단을 추가하기 전에 오류와 메시지를 처리하세요.

주요 기능

  • 최신 .NET 지원: 현재 .NET 및 .NET 프레임워크 버전에서 실행됩니다. 버전별 세부 내역은 지원 수명 주기를 참조하세요.
  • 기본 암호화: TLS 암호화된 연결을 Encrypt=true 기본값으로 사용합니다. Encrypt=Strict를 TDS 8.0 암호화로 설정합니다.
  • Microsoft Entra ID 인증: 관리 ID, 서비스 주체, 대화형, 통합, 기본 자격 증명 체인 및 액세스 토큰 흐름을 사용하는 암호 없는 연결입니다.
  • 케르베로스와 NTLM: 온-프레미스 Active Directory 및 레거시 시나리오를 위한 통합 Windows 인증.
  • Always Encrypted: 민감한 열을 위한 클라이언트 측 암호화로, 선택적으로 제자리 작업을 위한 보안 엔클레이브를 사용합니다.
  • 벌크 복사: SqlBulkCopy을 사용한 대량 삽입.
  • 연결 풀링: 기본적으로 켜져 있습니다. 옵트인 V2 풀 이 평가 중입니다.
  • 연결 복원력: 내장된 연결 재시도(ConnectRetryCount 와 ConnectRetryInterval)와 연결 및 명령에 대한 옵트인 설정 가능한 재시도 로직.
  • 풍부한 SQL Server 데이터 타입: datetimeoffset, sql_variant, JSON, 벡터, 공간, XML, 그리고 테이블 값 매개변수.
  • 진단: 이벤트 소스 추적, 진단 카운터, 제공자 통계, 전용 문제 해결 가이드.
  • 애플리케이션 ID: SqlConnection.RegisteredApplication을 설정하여 SQL Server에 라이브러리 또는 도구를 식별합니다(Microsoft.Data.SqlClient 7.1 및 이후 버전).

Get started

조항 Description
SqlClient 드라이버로 시작하세요 프로젝트를 설정하고, 데이터베이스를 만들고, 연결하고, 쿼리하며, 연결 복원력을 추가하세요.
Microsoft.Data.SqlClient를 설치, 업데이트 및 배포 NuGet 패키지를 설치하고, 릴리스를 선택하며, 드라이버를 업데이트하고, 배포 출력을 준비하세요.
지원 수명 주기 지원되는 드라이버 버전과 지원 날짜를 검토하세요.
System.Data.SqlClient에서 Microsoft.Data.SqlClient로 마이그레이션 패키지 참조, 네임스페이스, 구성, 변경된 드라이버 동작을 업데이트하세요.
Microsoft. Data.Sql클라이언트 네임스페이스 및 호환성 SqlClient가 ADO.NET를 어떻게 구현하고 System.Data.SqlClient, .NET, SQL Server와의 호환성을 갖추는지 이해하세요.
Microsoft의 새로운 소식. Data.SqlClient 현재 릴리스, 주요 업그레이드 변경 사항, 그리고 상위 릴리스 노트를 확인하세요.

구성 및 연결

조항 Description
데이터 소스에 연결하세요 연결을 열고 관리하며, 연결 상태 변화에 대응합니다.
연결 문자열 서버, 데이터베이스, 인증, 암호화, 연결 동작을 구성하세요.
암호화 및 인증서 유효성 검사 암호화된 연결과 서버 인증서 검증을 구성하세요.
SQL Server 연결 풀링 물리적 연결을 효율적으로 재사용하세요.
오류 및 메시지 처리 오류를 발견하고 정보 메시지를 받으세요.

인증 및 보안

조항 Description
Microsoft.Data.SqlClient를 위한 보안 모범 사례 인증, 승인, 애플리케이션 보안 지침을 검토하세요.
Microsoft Entra 인증 관리 신원, 서비스 주체, 비밀번호, 인터랙티브 플로우와 연결됩니다.
연결 정보 보호 자격 증명과 연결 설정은 애플리케이션 코드에서 제외하세요.
항상 암호화되어 있습니다 데이터베이스 시스템에서 민감한 열 값을 보호하세요.
보안 엔클레이브를 사용하는 Always Encrypted 암호화된 데이터에 대해 안전한 엔클레이브를 통해 풍부한 연산을 실행하세요.

데이터 검색 및 업데이트

조항 Description
명령 실행하기 매개변수화된 SQL 문과 저장 프로시저를 실행합니다.
DataAdapters 및 DataReaders 결과 집합을 스트리밍하거나 분리된 데이터 구조를 채우는 것.
SqlBatch로 여러 명령을 실행하세요 명령어 집합을 순서대로 보내고 그 결과를 처리하세요.
스트림 데이터 전체 값을 버퍼링하지 않고 큰 바이너리, 텍스트, XML, JSON 값을 전송할 수 있습니다.
트랜잭션 및 동시성 로컬 및 분산 트랜잭션과 동시성 제어를 사용하세요.
데이터베이스 스키마 정보 조회 스키마 컬렉션과 제한 사항을 발견하세요.
대량 복사 작업 SqlBulkCopy를 사용하여 대용량 데이터 세트를 효율적으로 로드하세요.
테이블 반환값 매개변수 매개변수화된 문장이나 저장 프로시저에 여러 행을 보냅니다.
MARS(Multiple Active Result Sets) 하나의 연결에서 여러 배치를 교차 처리하세요.

데이터 형식

조항 Description
SQL Server 데이터 타입 매핑 SQL Server 타입을 .NET 및 System.Data.SqlTypes 타입으로 매핑하세요.
JSON 데이터 SQL Server json 데이터 타입을 전송하고 조회하세요.
벡터 데이터 벡터 값을 보내고 가져오세요.
XML 데이터 XML 값을 읽고, 쓰고, 매개변수화합니다.
이진 및 대값 데이터 바이너리, FILESTREAM, 대용량 데이터를 스트리밍하고 업데이트할 수 있습니다.

신뢰성 및 진단

조항 Description
구성 가능한 다시 시도 논리 일시적 연결 및 명령 실패를 제한 정책으로 재시도하세요.
고가용성 및 재해 복구 가용성 그룹 리스너 및 장애 조치 파트너에 연결하세요.
SqlClient의 이벤트 카운터 활성 연결, 풀된 연결, 기타 드라이버 지표를 모니터링하세요.
이벤트 소스 추적 활성화 진단을 위한 상세한 운전자 사건을 기록하세요.
SqlClient 문제 해결 가이드 공통 연결 문제와 드라이버 문제를 진단하세요.
쿼리 알림 쿼리 결과가 변경될 때 알림을 받아야 합니다.

SQL Server 기능

조항 Description
SQL Server 기능 및 ADO.NET SqlClient를 통해 제공되는 SQL Server 전용 기능을 둘러보세요.
로컬DB SQL Server Express LocalDB 인스턴스에 연결하세요.
데이터 검색 및 분류 결과 집합에서 민감도 분류 메타데이터를 읽으세요.

참조 및 리소스

조항 Description
Microsoft. Data.SqlClient API 참고 드라이버에 대한 .NET API 참고 자료를 둘러보세요.
AppContext 전환 옵션 호환성과 보안 동작을 설정하세요.
Microsoft.Data.SqlClient GitHub 리포지토리 드라이버 소스 코드, 릴리스 노트, 샘플을 읽어보세요.
Microsoft.Data.SqlClient 샘플 드라이버 API를 위한 C# 샘플을 둘러보세요.
.NET 런타임 GitHub 저장소 .NET 런타임 라이브러리의 소스를 읽어보세요.

기능 요청

기능을 요청하려면 Microsoft. Data.SqlClient GitHub 저장소에서 이슈를 열어보세요.

관련 콘텐츠

  • 에 마지막으로 업데이트됨