Bagikan melalui

Panduan pemecahan masalah SqlClient

Mengunduh ADO.NET

Pengecualian saat menyambungkan ke SQL Server

Ada berbagai alasan mengapa koneksi dapat gagal dibuat. Berikut adalah beberapa tips pemecahan masalah yang dapat digunakan sebagai panduan untuk menganalisis dan menyelesaikan banyak masalah.

Tidak dapat memuat pustaka SNI (Antarmuka Jaringan Server) asli

Masalah dalam aplikasi .NET Framework

Stacktrace observed:

TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.SNILoadHandle' threw an exception.
DllNotFoundException: Unable to load DLL 'Microsoft.Data.SqlClient.SNI.x64.dll': The specified module could not be found. (Exception from HRESULT: 0x8007007E)

TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.SNILoadHandle' threw an exception.
DllNotFoundException: Unable to load DLL 'Microsoft.Data.SqlClient.SNI.x86.dll': The specified module could not be found. (Exception from HRESULT: 0x8007007E)

SNI adalah pustaka C++ asli yang bergantung pada SqlClient untuk berbagai operasi jaringan saat berjalan di Windows. Dalam aplikasi .NET Framework yang dibangun dengan MSBuild Project SDK, DLL asli tidak dikelola dengan perintah pemulihan. .targets Jadi file disertakan dalam Microsoft.Data.SqlClient.SNI paket NuGet yang menentukan operasi "Salin" yang diperlukan.

File yang disertakan .targets direferensi secara otomatis ketika dependensi langsung dibuat ke Microsoft.Data.SqlClient library. Dalam skenario saat referensi transitif (tidak langsung) dibuat, file ini .targets harus direferensikan secara manual untuk memastikan operasi "Salin" dapat dijalankan jika diperlukan.

Solusi yang Direkomendasikan: Pastikan file .targets dirujuk dalam file proyek aplikasi untuk memastikan operasi "Salin" dapat dijalankan. Contoh pengeditan ke file proyek dapat ditemukan dalam masalah GitHub terkait ini.

Target ini hanya mencakup target Microsoft yang terkenal dan umum digunakan. Jika alat atau aplikasi eksternal menentukan target kustom untuk menyalin biner, target baru harus didefinisikan oleh penjaga alat untuk memastikan DLL SNI asli disalin bersama Microsoft.Data.SqlClient.dll biner dan tersedia saat menjalankan aplikasi klien.

Masalah dalam aplikasi .NET Core

Stacktrace observed:

System.TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.TdsParser' threw an exception.
---> System.TypeInitializationException: The type initializer for 'Microsoft.Data.SqlClient.SNILoadHandle' threw an exception.
---> System.DllNotFoundException: Unable to load shared library 'Microsoft.Data.SqlClient.SNI.dll' or one of its dependencies.

Note

Kesalahan ini mungkin terjadi hanya pada aplikasi Windows. Jika terjadi di lingkungan Unix, Anda harus memastikan aplikasi Anda dibangun untuk menargetkan runtime Unix dengan tepat dan bukan untuk Windows.

SNI adalah pustaka C++ asli yang bergantung pada SqlClient untuk berbagai operasi jaringan saat berjalan di Windows. Microsoft.Data.SqlClient tidak mengelola pemuatan/pembongkaran pustaka ini di .NET Core.

Solusi yang Direkomendasikan: Pastikan izin "Jalankan" diberikan pada sistem file tempat pustaka runtime asli dimuat dalam proses .NET Core. Jika itu tidak menyelesaikan masalah, Anda dapat mengajukan masalah di repositori dotnet/runtime untuk dukungan lebih lanjut.

Kesalahan SNI asli (pdb tidak ditemukan)

Stacktrace observed:

An assembly specified in the application dependencies manifest (sql2csv.deps.json) was not found:
  package: 'Microsoft.Data.SqlClient.SNI.runtime', version: '2.0.0'
  path: 'runtimes/win-x64/native/Microsoft.Data.SqlClient.SNI.pdb'

Solusi yang Direkomendasikan: Pastikan aplikasi klien mereferensikan versi minimum v2.1.0 dari paket Microsoft.Data.SqlClient. Saat menggunakan EF Core, tambahkan referensi ke versi Microsoft.Data.SqlClient paket ini secara langsung untuk mengambil alih dependensi.

Kesalahan resolusi nama host

Stacktrace observed:

Microsoft.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible.
Verify that the instance name is correct and that SQL Server is configured to allow remote connections.
(provider: TCP Provider, error: 0 - No such host is known.)

Microsoft.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible.
Verify that the instance name is correct and that SQL Server is configured to allow remote connections.
(provider: TCP Provider, error: 35 - An internal exception was caught)

Microsoft.Data.SqlClient.SqlException (0x80131904): A network-related or instance-specific error occurred while establishing a connection to SQL Server. The server was not found or was not accessible.
Verify that the instance name is correct and that SQL Server is configured to allow remote connections.
(provider: TCP Provider, error: 35 - An internal exception was caught)
 ---> System.Net.Internals.SocketExceptionFactory+ExtendedSocketException (00000005, 0xFFFDFFFF): Name does not resolve

Possible reasons

  • Protokol Pipa TCP/Bernama tidak diaktifkan di SQL Server

    Solusi yang Direkomendasikan: Aktifkan Protokol Pipa TCP/Bernama pada instans SQL Server dari konsol Pengelola Konfigurasi SQL Server.

  • Nama host tidak diketahui

    Solusi yang Direkomendasikan: Pastikan nama host diselesaikan ke alamat IP Server dari klien tempat koneksi dimulai.

Login-phase errors

Stacktraces observed:

Microsoft.Data.SqlClient.SqlException (0x80131904): A connection was successfully established with the server, but then an error occurred during the pre-login handshake.
(provider: SSL Provider, error: 31 - Encryption(ssl/tls) handshake failed)
System.IO.EndOfStreamException: End of stream reached

A connection was successfully established with the server, but then an error occurred during the login process.
(provider: SSL Provider, error: 0 - The target principal name is incorrect.)

Microsoft.Data.SqlClient.SqlException (0x80131904): Connection Timeout Expired. The timeout period elapsed during the post-login phase. The connection could have timed out while waiting for server to complete the login process and respond; Or it could have timed out while attempting to create multiple active connections.
The duration spent while attempting to connect to this server was - [Pre-Login] initialization=837; handshake=394; [Login] initialization=3; authentication=15; [Post-Login] complete=1027;
---> System.ComponentModel.Win32Exception (258): Unknown error 258
at Microsoft.Data.SqlClient.SqlInternalConnection.OnError(SqlException exception, Boolean breakConnection, Action1 wrapCloseInAction)

Kemungkinan alasan dan solusi

  • SQL Server tidak mendukung TLS 1.2

    Kesalahan ini biasanya terjadi di lingkungan klien seperti kontainer gambar docker, klien Unix, atau klien Windows di mana TLS 1.2 adalah protokol TLS minimum yang didukung.

    Solusi yang Direkomendasikan: Instal pembaruan terbaru pada versi SQL Server yang didukung dan pastikan protokol TLS 1.2 diaktifkan di server.

    Note

    Lihat siklus hidup dukungan driver SqlClient untuk daftar versi SQL Server yang didukung dengan versi yang berbeda dari Microsoft.Data.SqlClient.

    Solusi yang tidak aman: Konfigurasikan pengaturan TLS/SSL di lingkungan gambar/klien docker untuk terhubung dengan TLS 1.0.

    MinProtocol = TLSv1
CipherString = DEFAULT@SECLEVEL=1

    Note

    Saat terhubung dengan Microsoft.Data.SqlClient v2.0+ dari lingkungan Windows/Linux dengan TLS 1.0 atau TLS 1.1, pesan peringatan keamanan dilemparkan jika target SQL Server dan klien tidak dapat menegosiasikan minimal TLS versi 1.2 saat membuat koneksi:

    Security Warning: The negotiated <TLS1.0 | TLS1.1> is an insecure protocol and is supported for backward compatibility only. The recommended protocol version is TLS 1.2 and later.

  • Enkripsi yang diberlakukan SQL Server

    Jika Server target adalah instans Azure SQL atau SQL Server lokal dengan properti "Enkripsi Paksa" diaktifkan, koneksi terenkripsi dibuat, di mana klien harus membangun kepercayaan dengan server.

    Solusi yang Direkomendasikan: Ada dua opsi yang tersedia untuk memperbaiki masalah ini:

    • Instal sertifikat TLS SQL Server target di lingkungan klien. Ini divalidasi jika enkripsi diperlukan.
    • (Kurang aman) Atur properti "TrustServerCertificate=true" di string koneksi.

    Solusi tidak aman: Nonaktifkan pengaturan "Enkripsi Paksa" di SQL Server.

  • Sertifikat TLS tidak ditandatangani dengan SHA-256 atau yang lebih tinggi.

    Solusi yang Direkomendasikan: Buat sertifikat TLS baru untuk server yang hash-nya ditandatangani dengan setidaknya algoritma hash SHA-256.

  • Suite sandi yang dibatasi dengan ketat di Linux dengan .NET 5+

    .NET 5 memperkenalkan perubahan yang melanggar untuk klien Linux, di mana daftar yang dibatasi ketat dari suite sandi yang diizinkan digunakan secara default. Anda mungkin perlu memperluas daftar cipher suite default untuk menerima klien lama (atau untuk menghubungi server warisan) dengan menentukan CipherSuitePolicy nilai atau mengubah file konfigurasi OpenSSL .

    Baca selengkapnya tentang Cipher suite TLS Default untuk .NET di Linux untuk tindakan yang direkomendasikan.

    Microsoft.Data.SqlClient.SqlException (0x80131904): A connection was successfully established with the server, but then an error occurred during the login process. (provider: SSL Provider, error: 0 - The certificate chain was issued by an authority that is not trusted.)
---> System.ComponentModel.Win32Exception (0x80090325): The certificate chain was issued by an authority that is not trusted.

  • Enkripsi yang diberlakukan SQL Server

    Jika Server target adalah SQL Server lokal dengan properti "Enkripsi Paksa" diaktifkan dan sertifikat yang ditandatangani sendiri, koneksi terenkripsi dibuat, yang kliennya harus membangun kepercayaan dengan server.

    Solusi yang Direkomendasikan: Ada dua opsi yang tersedia untuk memperbaiki masalah ini:

    • Instal sertifikat TLS SQL Server target di lingkungan klien. Ini divalidasi jika enkripsi diperlukan.
    • (Kurang aman) Atur properti "TrustServerCertificate=true" di string koneksi.

    Solusi tidak aman: Nonaktifkan pengaturan "Enkripsi Paksa" di SQL Server.

Kesalahan kelelahan Kumpulan Koneksi

Jejak tumpukan diamati:

System.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.

Kemungkinan alasan dan solusi

Aplikasi klien membuka lebih banyak koneksi daripada kumpulan koneksi dapat tetap aktif pada waktu tertentu.

Solusi yang Direkomendasikan: Konfigurasikan properti koneksi "Ukuran Kumpulan Maks" ke nilai yang lebih tinggi dan tutup koneksi yang tidak digunakan secara tepat waktu.

Contact Support

Jika panduan ini tidak menyelesaikan masalah konektivitas, Anda mungkin melihat masalah yang ada di repositori dotnet/sqlclient dan membuka masalah baru jika diperlukan.

  • Last updated on