System.Data.SqlClientからMicrosoftへ移行してください。Data.SqlClient

Microsoft。Data.SqlClientは、.NETアプリケーションにおける新しいSQL Server機能のサポートプロバイダーです。 これはSystem.Data.SqlClientが使用していたADO.NETプログラミングモデルを保持していますが、パッケージ、名前空間、デフォルト、一部のパブリック型には異なっています。

移行は単なる名前空間の置き換えではなく、プロバイダーの更新として扱いましょう。

移行の計画

コード変更前に:

1. アプリケーションがサポートする.NET、System.Data.SqlClient、SQL 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型.NETCommandType、DbType、IsolationLevel、DataTable、DbConnection、DbCommandを引き続き使用しています。

一部のSQL Server固有のタイプは他のMicrosoft.Data名前空間に移動します:

Microsoft.Data.SqlClient 5.0 以降では、その他の SQL Server 共通言語ランタイム (CLR) 型は Microsoft.SqlServer.Server に残されています。 各型をコンパイラエラーやMicrosoftの API 参照から更新します。名前空間全体を置き換えるのではなく、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よりも安全なデフォルトを使用しています。

Encrypt=falseやTrustServerCertificate=trueを一般的な移行修正として設定しないでください。 クライアントが信頼する証明書を設定し、その証明書に合うサーバー名を使いましょう。 検証ができない管理された開発環境でのみ TrustServerCertificate=true を使いましょう。

SqlConnectionEncryptOptionへの変更は暗黙の変換を通じて共通割り当てでソース互換性がありますが、バイナリ的な破壊的な変更です。 SqlConnectionStringBuilder.Encryptにアクセスするすべてのアセンブリを再コンパイルしてください。

詳細については、「暗号化と証明書の検証」を参照してください。

接続文字列の確認

Microsoft。Data.SqlClientはSystem.Data.SqlClientが認識できないキーワードやエイリアスを追加します。 例えば、 Application Intent や Multi Subnet Failoverのようなスペースを持つエイリアスを受け入れます。

Microsoft.Data.SqlClient.SqlConnectionStringBuilderで接続文字列を作ってからそれをSystem.Data.SqlClientに渡さないでください。 段階的な移行中は、各接続文字列 builderをプロバイダーとペアに保ちます。

認証、暗号化、再試行、フェイルオーバー、証明書キーワードを 接続文字列の構文と比較してください。

レビューパラメータの挙動

テストの日付と時間パラメータを明示的に示します:

SQL Server の型推論によってクエリ プランや変換動作が変わる可能性があるパラメーターでは、SqlDbType、長さ、精度、およびスケールを指定します。 データベースの種類が分かっている場合、 AddWithValue を移行のショートカットとして使わないでください。

推移的なプロバイダー参照を確認してください

パッケージを直接削除しても、System.Data.SqlClient がなくなるとは限りません。 走れ

dotnet list package --include-transitive

両プロバイダーが残っている場合:

1. System.Data.SqlClientを運ぶ荷物を特定しましょう。
2. 可能であればその依存関係を更新または置き換えてください。
3. 両方が依存関係に留まる必要がある場合は、提供者固有のタイプを依存境界内に置いてください。
4. 明示的な名前空間の別名は一時的な補助としてのみ使用してください。 接続、トランザクション、パラメータ、リーダーを一方のプロバイダーからもう一方へ渡さないでください。

特に、SQL Server CLR 型ライブラリと、パブリック API で System.Data.SqlClient 型を公開している古いデータ アクセス フレームワークに注意を払ってください。

グローバリゼーションの行動を見直す

.NETフレームワークおよび.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交渉、証明書検証、接続文字列解析。
• 接続プーリングとアクセストークンの更新。
• パラメータの種類、ヌル値、精度、スケール、日付、時間の挙動。
• トランザクション、キャンセル、タイムアウト、リトライ、フェイルオーバー。
• 常に暗号化されている、SQL ServerのCLRタイプ、バルクコピー、クエリ通知、その他アプリケーションで使用されるプロバイダー固有の機能。
• ログ、カウンター、トレース、例外処理などです。

サポートされているすべてのデータベースエンジンバージョンに対して代表的なクエリを実行します。 コンパイルが成功しても、接続のセキュリティやランタイム依存関係、データ変換の検証は行われません。

関連するコンテンツ

• Microsoft。Data.Sqlクライアント名前空間と互換性
• Microsoft。Data.SqlClient リリースノートとアップデート
• SqlClientリポジトリでのチートシートの移植
• Microsoft.Data.SqlClient API リファレンス