System.Data.SqlClient에서 Microsoft.Data.SqlClient로 마이그레이션하세요.

Microsoft. Data.SqlClient는 .NET 애플리케이션에서 새로운 SQL Server 기능을 지원하는 제공자입니다. 이 방식은 에서 사용되는 System.Data.SqlClientADO.NET 프로그래밍 모델을 보존하지만, 패키지, 네임스페이스, 기본값, 일부 공개 타입은 다릅니다.

마이그레이션을 단순한 네임스페이스 교체가 아니라 제공자 업데이트로 간주하세요.

마이그레이션 계획

코드를 변경하기 전:

  1. 애플리케이션이 지원하는 .NET, System.Data.SqlClientSQL Server, Microsoft SQL 서비스 버전을 기록하세요.

  2. 인벤토리 인증 모드, 연결 문자열 키워드, 사용자 지정 인증서, 항상 암호화된 제공자, DbProviderFactories 구성, SQL Server 사용자 정의 타입, 그리고 System.Data.SqlTypes 사용법.

  3. 애플리케이션의 현재 테스트를 실행하고 연결, 쿼리, 트랜잭션, 재시도, 성능 동작에 대한 기준선을 저장하세요.

  4. 직접 및 전이적 패키지 참조 검색:

    dotnet list package --include-transitive

한 번에 하나의 애플리케이션이나 공유 데이터 접근 라이브러리를 마이그레이션하세요. 아직 System.Data.SqlClient를 사용하는 코드와 Microsoft.Data.SqlClient를 사용하는 코드 사이에 공급자별 객체를 전달하지 마세요.

패키지를 교체하세요

명시적인 System.Data.SqlClient 패키지 참조가 있다면 제거하세요:

dotnet remove package System.Data.SqlClient

Microsoft.Data.SqlClient를 추가하세요:

dotnet add package Microsoft.Data.SqlClient

만약 Microsoft. Data.SqlClient 7.0 또는 이후 버전이 드라이버 제공 Microsoft Entra 인증 모드를 사용한다면, 다음 기능도 추가하세요:

dotnet add package Microsoft.Data.SqlClient.Extensions.Azure --version <same-version-as-Microsoft.Data.SqlClient>

버전 및 패키지 선택에 대해서는 Microsoft 설치, 업데이트, 배포를 참조하세요. Data.SqlClient.

네임스페이스 업데이트

주요 제공자 네임스페이스 교체:

-using System.Data.SqlClient;
+using Microsoft.Data.SqlClient;

System.Data.SqlClient을 참조하는 정규화된 이름, 별칭, 생성된 코드, 의존성 주입 등록, 리플렉션 문자열, 구성 및 테스트 더블을 업데이트합니다.

일반 System.Data 이나 System.Data.Common 네임스페이스를 교체하지 마세요. Microsoft.Data.SqlClient이 네임스페이스에서 ADO.NET 타입 CommandTypeDbConnectionDbTypeIsolationLevelDataTableDbCommand 을 계속 사용합니다.

일부 SQL Server 전용 타입은 다른 Microsoft.Data 네임스페이스로 이동합니다:

유형 이전 네임스페이스 Microsoft.Data.SqlClient 네임스페이스
SqlDataRecord, SqlMetaData Microsoft.SqlServer.Server Microsoft.Data.SqlClient.Server
SqlFileStream System.Data.SqlTypes Microsoft.Data.SqlTypes
SqlNotificationRequest System.Data.Sql Microsoft.Data.Sql
OperationAbortedException System.Data Microsoft.Data

Microsoft.Data.SqlClient 5.0 이상에서는 다른 SQL Server CLR(공용 언어 런타임) 형식이 여전히 Microsoft.SqlServer.Server에 남아 있습니다. 컴파일러 오류와 Microsoft. Data.SqlClient API 참조를 통해 각 타입을 업데이트하며, 전체 네임스페이스를 교체하는 것이 아닙니다.

.NET 프레임워크 구성 업데이트

DbProviderFactories를 통해 공급자를 확인하는 애플리케이션은 App.config 또는 Web.config에서 공급자 등록이 필요할 수 있습니다:

<configuration>
  <system.data>
    <DbProviderFactories>
      <add name="SqlClient Data Provider"
           invariant="Microsoft.Data.SqlClient"
           description=".NET data provider for SQL Server"
           type="Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient" />
    </DbProviderFactories>
  </system.data>
</configuration>

제공자 불변 이름을 요청하는 코드 업데이트:

DbProviderFactory factory =
    DbProviderFactories.GetFactory("Microsoft.Data.SqlClient");

애플리케이션이 SqlConnection를 직접 생성하고 DbProviderFactories를 사용하지 않는 경우에는 이 구성을 추가하지 마세요.

암호화 및 인증서 검증 검토

Microsoft. Data.SqlClient는 System.Data.SqlClient보다 더 안전한 기본값을 사용합니다.

작동 방식 System.Data.SqlClient Microsoft.Data.SqlClient
기본 암호화 Encrypt=false Encrypt=true 버전 4.0부터
서버 인증서 유효성 검사 클라이언트 암호화가 활성화되었을 때만 인증서를 검증합니다 버전 2.0부터는 서버가 암호화를 강제하는 시점에 TrustServerCertificate 따라 인증서를 검증합니다. 설령 Encrypt=false
엄격한 암호화 지원되지 않음 Encrypt=Strict TDS 8.0 지원 서버를 위한 버전 5.0부터
SqlConnectionStringBuilder.Encrypt 형식 bool SqlConnectionEncryptOption 버전 5.0부터

일반적인 마이그레이션 해결책으로 설정 Encrypt=falseTrustServerCertificate=true 하지 마세요. 클라이언트가 신뢰하는 인증서를 설정하고, 인증서와 일치하는 서버 이름을 사용하세요. 검증이 불가능한 통제된 개발 환경에만 사용됩니다 TrustServerCertificate=true .

SqlConnectionEncryptOption로의 변경은 암시적 변환으로 인해 일반적인 할당에서는 소스 호환되지만, 바이너리 호환성이 깨지는 변경입니다. 에 접근 SqlConnectionStringBuilder.Encrypt하는 모든 어셈블리를 다시 컴파일하세요.

자세한 내용은 암호화 및 인증서 유효성 검사를 참조하세요.

연결 문자열 검토

Microsoft. Data.SqlClient는 System.Data.SqlClient가 인식하지 못하는 키워드와 별칭을 추가합니다. 예를 들어, 공백 Application IntentMulti Subnet Failover이 포함된 별칭을 받아들입니다.

Microsoft.Data.SqlClient.SqlConnectionStringBuilder로 연결 문자열을 만든 다음 System.Data.SqlClient에 전달하지 마세요. 단계별 마이그레이션 중에는 각 연결 문자열 빌더를 제공자와 계속 짝지어 유지하세요.

인증, 암호화, 재시도, 장애 조치, 인증서 키워드를 연결 문자열 문법과 비교해 검토하세요.

매개변수 동작 검토

테스트 날짜와 시간 매개변수를 명시적으로 설명하세요:

매개 변수 System.Data.Sql클라이언트 동작 Microsoft. Data.Sql클라이언트 동작
DbType.Time이 값은 DateTime 값을 받아들입니다. TimeSpan 값을 사용하세요
DateTime 값을 가진 DbType.Date 날짜와 시간 구성 요소를 보낼 수 있습니다 시간 구성 요소를 절단합니다

SQL Server 타입 추론이 쿼리 계획이나 변환 동작을 변경할 수 있는 매개변수에 대해 , 길이, 정밀도, 그리고 스케일을 지정SqlDbType하세요. 데이터베이스 유형이 알려져 있다면 마이그레이션 단축키로 사용하지 AddWithValue 마세요.

전이적 프로바이더 참조 확인

패키지를 직접 제거해도 System.Data.SqlClient가 제거되었다고 보장할 수는 없습니다. Run:

dotnet list package --include-transitive

두 제공자가 모두 남아 있을 경우:

  1. System.Data.SqlClient를 가져오는 패키지를 식별하세요.
  2. 가능하면 그 의존성을 업데이트하거나 교체하세요.
  3. 양쪽 모두 의존 경계 내에 있어야 할 경우, 제공자 전용 유형을 유지하세요.
  4. 명시적인 네임스페이스 별칭은 임시 보조 수단으로만 사용하세요. 한 공급자에서 다른 공급자로 연결, 트랜잭션, 매개변수, 리더를 전달하지 마세요.

특히 SQL Server CLR 형식 라이브러리와 공개 API에 System.Data.SqlClient 형식을 노출하는 이전 데이터 액세스 프레임워크에 각별히 주의하세요.

세계화 행동 검토

.NET Framework 및 .NET 5 이전 버전의 .NET은 Windows에서 국가 언어 지원(NLS) 글로벌화를 사용합니다. 현재 .NET 버전은 Windows, Linux, macOS에서 기본적으로 International Components for Unicode(ICU)를 사용합니다.

이 런타임 차이는 일부 SqlString 비교에 영향을 줄 수 있습니다. SQL Server는 NLS 비교 동작을 사용합니다. 클라이언트 측 SqlString 비교가 서버 동작과 일치해야 한다면, 영향을 받는 값을 테스트하고 글로벌리케이션과 ICU를 검토하세요. 필요할 때 애플리케이션은 ICU 대신 NLS를 사용할 수 있습니다.

Microsoft.Data.SqlClient는 세계화 고정 모드를 지원하지 않습니다.

마이그레이션된 애플리케이션을 검증합니다

지원되는 모든 대상 프레임워크와 운영체제에서 빌드하고 테스트하세요.

유효성 검사:

  • 패키지 복원 및 게시 출력.
  • SQL 인증, Windows 통합 인증, 그리고 애플리케이션에서 사용하는 Microsoft Entra 인증이 포함됩니다.
  • TLS 협상, 인증서 검증, 그리고 연결 문자열 파싱.
  • 연결 풀링과 액세스 토큰 갱정.
  • 매개변수 유형, null 값, 정밀도, 규모, 날짜, 시간 동작 등이 포함됩니다.
  • 트랜잭션, 취소, 타임아웃, 재시도, 그리고 장애 조치 등이 있습니다.
  • 항상 암호화된 SQL Server CLR 유형, 대량 복사, 쿼리 알림 및 애플리케이션에서 사용하는 기타 제공자 특화 기능들.
  • 로그, 카운터, 추적, 예외 처리.

지원되는 모든 데이터베이스 엔진 버전에 대해 대표적인 쿼리를 실행하세요. 성공적인 컴파일 자체가 연결 보안, 런타임 의존성, 데이터 변환을 검증하지 않습니다.

관련 콘텐츠

  • Last updated on