SqlClient 中的 AppContext 參數

下載 ADO.NET

AppContext 類別允許 SqlClient 提供新功能，同時繼續支援相依於之前行為的呼叫端。 使用者可以透過設定特定的 AppContext 參數，選擇退出行為中的變更。

強制使用作業系統加密通訊協定

適用於：.NET Framework .NET .NET Standard

Microsoft.Data.SqlClient 4.0 起，驅動程式不再支援 TLS 1.3，且其預設已從支援的通訊協定清單中移除。 使用者可以將 AppContext 參數 "Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols" 設定為 true，以切換回強制使用作業系統的用戶端通訊協定：

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseSystemDefaultSecureProtocols", true);

從 5.0 版開始，TDS 8 連線支援 TLS 1.3，而不需要使用上述參數。 Encrypt 設定為 Strict 時，TDS 8 會啟用。

啟用十進位截斷行為

適用於：.NET Framework .NET .NET Standard

從 Microsoft.Data.SqlClient 2.0 開始，十進位資料預設會四捨五入，和 SQL Server 一樣。 若要啟用之前的截斷行為，您可以在應用程式啟動時將 AppContext 參數 "Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal" 設為 true：

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.TruncateScaledDecimal", true);

在 Windows 上啟用受控網路

適用於： .NET Framework .NET Core .NET Standard

(2.0 版開始提供使用)

在 Windows 上，SqlClient 預設使用 SNI 網路介面的原生實作。 若要使用受控的 SNI 實作，您可以在應用程式啟動時將 AppContext 參數 "Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows" 設為 true：

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseManagedNetworkingOnWindows", true);

此參數會切換驅動程式的行為，以在 Windows 的 .NET Core 2.1+ 與 .NET Standard 2.0+ 專案中使用受控網路實作，同時消除 Microsoft.Data.SqlClient 程式庫之原生程式庫的所有相依性。 此僅用於測試與偵錯用途。

注意

與原生實作相比，有一些已知差異。 例如，受控實作不支援非網域 Windows 驗證。

停用透明網路 IP 解析

適用於： .NET Framework .NET Core .NET Standard

透明網路 IP 解析 (TNIR) 為現有 MultiSubnetFailover 功能的修訂版本。 TNIR 在第一個解析主機名稱 IP 未回應，且有多個與該主機名稱建立關聯的 IP 時，影響驅動程式的連線順序。 TNIR 會與 MultiSubnetFailover 互動，以提供下列三種連線順序：

• 0：嘗試一個 IP，然後以並行方式嘗試所有 IP
• 1：以並行方式嘗試所有 IP
• 2：逐一嘗試所有 IP

TransparentNetworkIPResolution	MultiSubnetFailover	行為
True	True	1
True	否	0
False	True	1
False	False	2

TransparentNetworkIPResolution 預設為啟用。 MultiSubnetFailover 預設為停用。 若要停用 TNIR，您可以在應用程式啟動時將 AppContext 參數 "Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString" 設為 true：

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.DisableTNIRByDefaultInConnectionString", true);

如需設定這些屬性的詳細資訊，請參閱 SqlConnection.ConnectionString 屬性 (英文) 文件。

在登入期間啟用逾時最小值

適用於：.NET Framework .NET .NET Standard

若要避免登入嘗試永遠等候，您可以在應用程式啟動時將 AppContext 參數 Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin 設為 true：

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.UseOneSecFloorInTimeoutCalculationDuringLogin", false);

停用 ReadAsync 的封鎖行為

適用於：.NET Framework .NET .NET Standard

從 3.0 版開始，ReadAsync 會以非同步的方式執行。 舊版會同步執行並禁止呼叫 .NET Framework 上的執行緒。 若要控制此封鎖行為，您可以在應用程式啟動時將 AppContext 參數 Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking 設為 true 或 false：

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.MakeReadAsyncBlocking", false);

啟用可設定重試邏輯

適用於：.NET Framework .NET .NET Standard

(3.0 版開始提供使用)

根據預設，會停用可設定重試邏輯。 如要啟用此功能，請在應用程式啟動時，將 AppContext 參數 Switch.Microsoft.Data.SqlClient.EnableRetryLogic 設定為 true。 即使重試提供者指派給連線或命令，也需要這個參數。

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.EnableRetryLogic", true);

• 如需使用設定檔啟用參數的資訊，請參閱啟用安全參數。

注意

從 Microsoft.Data.SqlClient v4.0 開始，將不再需要應用程式內容參數「Switch.Microsoft.Data.SqlClient.EnableRetryLogic」以使用可設定的重試邏輯功能。 生產現已支援此功能。 此功能的預設行為將維持非重試原則，用戶端應用程式必須覆寫此原則才能啟用重試。

啟用 rowversion null 行為

適用於：.NET Framework .NET .NET Standard

3.0 版開始，當 rowversion 有 null 值時，SqlDataReader 會傳回 DBNull 值，而非空白的 byte[]。 如要啟用舊版傳回空白 byte[] 的行為，請在應用程式啟動時啟用 AppContext 參數 Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior。

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.LegacyRowVersionNullBehavior", true);

隱藏不安全的 TLS 警告

適用於：.NET Framework .NET .NET Standard

(4.0.1 版開始提供使用)

當在連接字串中使用 Encrypt=false 時，會在於 TLS 版本為 1.2 或以下時將安全性警告輸出至主控台。 您可在應用程式啟動時啟用以下 AppContext 參數來隱藏此警告：

AppContext.SetSwitch("Switch.Microsoft.Data.SqlClient.SuppressInsecureTLSWarning", true);

另請參閱

AppContext 類別 (機器翻譯)