文件首頁
MySQL Connector/NET 開發人員指南
相關文件 下載本手冊
PDF (US Ltr) - 1.3Mb
PDF (A4) - 1.3Mb


MySQL Connector/NET 開發人員指南  /  Connector/NET 連線  /  Connector/NET 連線選項參考

4.5 Connector/NET 連線選項參考

本章節說明 MySQL Connector/NET 8.0 的完整連線選項集。您用來與伺服器建立連線的協定(傳統 MySQL 協定或 X 協定)決定了您應該使用的選項。連線選項具有預設值,您可以藉由在連接字串(傳統 MySQL 協定和 X 協定)或類似 URI 的連接字串 (X 協定) 中定義新值來覆寫它。Connector/NET 選項名稱和同義詞不區分大小寫。

如需有關如何使用連接字串的指示,請參閱第 4.1 節「建立 Connector/NET 連接字串」。如需替代的連線樣式,請參閱使用類似 URI 的字串或金鑰值組連線至伺服器

以下各節列出適用於兩種協定、僅適用於傳統 MySQL 協定和僅適用於 X 協定的連線選項

適用於傳統 MySQL 協定和 X 協定的選項

以下 Connector/NET 連線選項可與任一協定搭配使用。Connector/NET 8.0 在 MySql.Data.MySqlClient.MySqlConnectionStringBuilderMySqlX.XDevAPI.MySqlXConnectionStringBuilder 類別中,將本節中的選項公開為屬性。

CertificateFile , Certificate File

預設值:null

此選項指定 PKCS #12 格式 ( .pfx) 的憑證檔路徑。如需使用範例,請參閱第 6.7.2 節「在 Connector/NET 中使用 PFX 憑證」

CertificatePassword , Certificate Password

預設值:null

指定與使用選項 CertificateFile 指定的憑證搭配使用的密碼。如需使用範例,請參閱第 6.7.2 節「在 Connector/NET 中使用 PFX 憑證」

CertificateStoreLocation , Certificate Store Location

預設值:null

讓您可以存取個人存放區中的憑證,而不是使用憑證檔案和密碼組合。如需使用範例,請參閱第 6.7.2 節「在 Connector/NET 中使用 PFX 憑證」

CertificateThumbprint , Certificate Thumbprint

預設值:null

指定憑證指紋,以確保正確識別個人存放區中包含的憑證。如需使用範例,請參閱第 6.7.2 節「在 Connector/NET 中使用 PFX 憑證」

CharacterSet , Character Set , CharSet

指定應用於編碼傳送到伺服器的所有查詢的字元集。結果仍會以結果資料的字元集傳回。

ConnectionProtocol , Protocol , Connection Protocol

預設值:socket (或 tcp)

指定與伺服器建立連線的類型。值可以是

  • sockettcp,用於使用 TCP/IP 的 Socket 連線。

  • pipe,用於具名管道連線(X 協定不支援)。

  • unix,用於 UNIX Socket 連線。

  • memory,用於 MySQL 共用記憶體(X 協定不支援)。

Database , Initial Catalog

預設值:mysql

最初要使用的資料庫區分大小寫的名稱。

dns-srv , dnssrv

預設值:false

讓連線可以在 DNS SRV 記錄中解析服務 (SRV) 位址,當它與預設傳輸協定 (tcp) 搭配使用時,會定義指定服務的伺服器位置 (主機名稱和連接埠號碼)。單一 DNS 網域可以使用 SRV 位址記錄對應至多個目標 (伺服器)。每個 SRV 記錄都包含主機名稱、連接埠、優先順序和權重。Connector/NET 8.0.19 中引入了 DNS SRV 支援,以移除用戶端在連接字串中識別每個可能主機的需求,無論是否有連接集區。

啟用 DNS SRV 時,不允許在連接字串中指定多個主機名稱、連接埠號碼,或 UNIX Socket、具名管道或共用記憶體連線(請參閱 ConnectionProtocol 選項)。

使用傳統 MySQL 協定。 dns-srv 選項適用於連接字串;DnsSrv 屬性在 MySqlConnectionStringBuilder 類別中宣告。

// Connection string example
 
 var conn = new MySqlConnection("server=_mysql._tcp.example.abc.com.;
                                 dns-srv=true;
                                 user id=user;
                                 password=****;
                                 database=test");


// MySqlConnectionStringBuilder class example
 
 var sb = new MySqlConnectionStringBuilder();
{
  Server = "_mysql._tcp.example.abc.com.",
  UserID = "user",
  Password = "****",
  DnsSrv = true,
  Database = "test"
};

var conn = new MySqlConnection(sb.ConnectionString);

使用 X 協定。 dns-srv 選項適用於連接字串和匿名物件。DnsSrv 屬性在 MySqlXConnectionStringBuilder 類別中宣告。如果同時使用 dns-srv=falsemysqlx+srv:// 的 URI 配置建立衝突的連線設定,則會引發錯誤。如需在類似 URI 的連接字串中使用 mysqlx+srv:// 配置元素的詳細資訊,請參閱使用 DNS SRV 記錄的連線

// Connection string example

var session = MySQLX.GetSession("server=_mysqlx._tcp.example.abc.com.;
                                 dns-srv=true;
                                 user id=user;
                                 password=****;
                                 database=test");


// Anonymous object example

var connstring = new
{
  server = "_mysqlx._tcp.example.abc.com.",
  user = "user",
  password = "****",
  dnssrv = true
};

var session = MySQLX.GetSession(connString);


// MySqlXConnectionStringBuilder class example

var sb = new MySqlXConnectionStringBuilder();
{
  Server = "_mysqlx._tcp.example.abc.com.",
  UserID = "user",
  Password = "****",
  DnsSrv = true,
  Database = "test"
};

var session = MySQLX.GetSession(sb.ConnectionString);
Keepalive , Keep Alive

預設值:0

對於 TCP 連線,在傳送第一個 keepalive 封包前,閒置連線時間以秒為單位。值為 0 表示不使用 keepalive。在 Connector/NET 6.6.7/6.7.5/6.8.4 之前,此值以毫秒為單位。

Password , Password1 , pwd , pwd1

預設值:空字串

用於單因素/單因子驗證 (1FA/SFA) 的 MySQL 帳戶密碼,僅使用一種驗證方法(例如密碼)。

從 Connector/NET 8.0.28 開始,此選項也為具有多重驗證因子的帳戶提供第一個秘密密碼。伺服器可能需要一組 (1FA)、兩組 (2FA) 或三組 (3FA) 密碼來驗證 MySQL 帳戶。例如,如果使用 2FA 建立帳戶,如下所示

CREATE USER 'abe'@'localhost'
  IDENTIFIED WITH caching_sha2_password
    BY 'sha2_password'
  AND IDENTIFIED WITH authentication_ldap_sasl
    AS 'uid=u1_ldap,ou=People,dc=example,dc=com';

那麼您的應用程式可以使用此選項(password 或其同義詞)指定連線字串和一個值,在本例中為 sha2_password,以滿足第一個驗證因子。

var connString =  "server=localhost;
                   user=abe;
                   password=sha2_password;
                   password2=ldap_password;
                   port=3306";

或者,對於使用 MySqlConnectionStringBuilder 物件建立的連線

MySqlConnectionStringBuilder settings = new MySqlConnectionStringBuilder()
     {
       Server = "localhost", 
       UserID = "abe",
       Pwd1 = "sha2_password",
       Pwd2 = "ldap_password",
       Port = 3306
     };

如果伺服器不要求秘密密碼與驗證方法一起使用,則會忽略為 passwordpassword2password3 選項指定的值。

Password2 , pwd2

預設值:空字串

具有多重驗證因子的帳戶的第二個秘密密碼(請參閱 Password 連線選項)。

Password3 , pwd3

預設值:空字串

具有多重驗證因子的帳戶的第三個秘密密碼(請參閱 Password 連線選項)。

Port

預設值:3306

MySQL 用於監聽連線的埠。如果使用 Unix socket,則會忽略此值。

Server , Host , Data Source , DataSource

預設值:localhost

一個或多個主機電腦的名稱或網路位址。多個主機以逗號分隔,如果提供優先順序(0 到 100),則決定主機選取順序。從 Connector/NET 8.0.19 開始,當省略優先順序或每個主機的優先順序相同時,主機選取是隨機的。

// Selects the host with the highest priority (100) first
server=(address=192.10.1.52:3305,priority=60),(address=localhost:3306,priority=100);

提供者不會嘗試同步寫入資料庫,因此使用此選項時請小心。在具有 Mono 的 UNIX 環境中,這可以是 MySQL socket 檔案的完整路徑。使用此組態時,會使用 UNIX socket 而不是 TCP/IP socket。目前,只能指定單一 socket 名稱,因此目前不支援使用 UNIX socket 在複寫環境中存取 MySQL。

SslCa , Ssl-Ca

預設值:null

根據使用的憑證類型,此選項會指定 PKCS #12 格式 (.pfx) 的憑證檔案路徑,或是包含受信任 SSL 憑證授權單位 (CA) 清單的 PEM 格式 (.pem) 的檔案路徑。

當使用 PFX 憑證時,當 SslMode 連線選項設定為 RequiredVerifyCAVerifyFull 值時,此選項才會啟用;否則會忽略。

當使用 PEM 憑證時,當 SslMode 連線選項設定為 VerifyCAVerifyFull 值時,此選項才會啟用;否則會忽略。

如需使用範例,請參閱第 6.7.1 節「在 Connector/NET 中使用 PEM 憑證」

SslCert , Ssl-Cert

預設值:null

用於建立加密連線的 PEM 格式 SSL 憑證檔案名稱。此選項僅當為 SslMode 連線選項設定 VerifyFullSslCa 連線選項使用 PEM 憑證時才會啟用;否則會忽略。如需使用範例,請參閱第 6.7.1 節「在 Connector/NET 中使用 PEM 憑證」

SslKey , Ssl-Key

預設值:null

用於建立加密連線的 PEM 格式 SSL 金鑰檔案名稱。此選項僅當為 SslMode 連線選項設定 VerifyFullSslCa 連線選項使用 PEM 憑證時才會啟用;否則會忽略。如需使用範例,請參閱第 6.7.1 節「在 Connector/NET 中使用 PEM 憑證」

SslMode , Ssl Mode , Ssl-Mode

預設值:取決於 Connector/NET 的版本和使用的協定。X 協定不支援具名管道和共用記憶體連線。

  • 8.0.8 到 8.0.12 (兩種協定) 為 Required;8.0.13 及更新版本 (僅限 X 協定)。

  • 8.0.13 及更新版本 (僅限傳統 MySQL 協定) 為 Preferred

此選項具有下列值

  • Disabled – 不使用 SSL。非 SSL 啟用的伺服器要求針對 Connector/NET 8.0.29 或更新版本,將此選項明確設定為 Disabled

  • None – 不使用 SSL。非 SSL 啟用的伺服器要求針對 Connector/NET 8.0.8 或更新版本,將此選項明確設定為 None

    注意

    從 Connector/NET 8.0.29 開始,此值已過時。請改用 Disabled

  • Preferred – 如果伺服器支援 SSL,則使用 SSL,但在所有情況下都允許連線。此選項在 Connector/NET 8.0.8 中已移除,並在 8.0.13 中僅針對傳統 MySQL 協定重新實作。

    注意

    請勿針對 X 協定作業使用此選項。

  • Required – 一律使用 SSL。如果伺服器不支援 SSL,則拒絕連線。

  • VerifyCA – 一律使用 SSL。驗證憑證授權單位 (CA),但容許名稱不符。

  • VerifyFull – 一律使用 SSL。如果主機名稱不正確,則失敗。

tlsversion , tls-version , tls version

預設值:備用解決方案會決定要使用的 TLS 版本。

當用戶端和伺服器都支援指示的 TLS 版本,且 SslMode 連線字串選項的值未設定為 DisabledNone(在 Connector/NET 8.0.29 中已過時)時,限制 TLS 交握期間要使用的 TLS 協定版本集合。此選項接受單一版本或以逗號分隔的版本清單,例如 tls-version=TLSv1.2, TLSv1.3;

Connector/NET 支援下列值

  • TLSv1.3

  • TLSv1.2

當指派的值不是列出的值時,會報告錯誤。同樣地,當提供空清單作為值,或清單中的所有版本都不受支援且未嘗試連線時,會報告錯誤。

UserID , User Id , Username , Uid , User name , User

預設值:null

正在使用的 MySQL 登入帳戶。

僅限傳統 MySQL 協定的選項

與使用連線集區的系統相關的選項會一起出現在一般選項清單的末尾(請參閱連線集區選項)。Connector/NET 8.0 會將此區段中的選項公開為 MySql.Data.MySqlClient.MySqlConnectionStringBuilder 類別中的屬性。

一般選項。以下 Connector/NET 選項適用於連線字串的一般用途,並且這些選項適用於所有 MySQL 伺服器組態

AllowBatch , Allow Batch

預設值:true

true 時,可以使用一個命令執行傳送多個 SQL 陳述式。批次陳述式應以伺服器定義的分隔符號分隔。

AllowLoadLocalInfile , Allow Load Local Infile

預設值:false

停用(預設)或啟用伺服器功能以載入本機 infile 資料。如果此選項設定為 true,則無論使用 AllowLoadLocalInfileInPath 選項指定的路徑為何,都會啟用從任何位置上傳檔案。

AllowLoadLocalInfileInPath , Allow Load Local Infile In Path

預設值:null

指定可以從中讀取檔案並上傳到伺服器的安全路徑。當相關的 AllowLoadLocalInfile 選項設定為預設值 false 時,只能載入安全路徑或使用 AllowLoadLocalInfileInPath 選項指定的任何有效子資料夾中的檔案。例如,如果將 /tmp 設定為受限資料夾,則對 /tmp/myfile/tmp/myfolder/myfile 的檔案要求可能會成功。不允許任何超出此路徑的相對路徑或符號連結。

下表顯示當合併 AllowLoadLocalInfileAllowLoadLocalInfileInPath 連線字串選項時產生的行為。

AllowLoadLocalInfile 值 AllowLoadLocalInfileInPath 值 行為
true 空字串或 null 允許所有上傳。
true 有效的路徑 允許所有上傳(不遵守路徑)。
false 空字串或 null 不允許任何上傳。
false 有效的路徑 僅允許從指定的資料夾和子資料夾上傳。
AllowPublicKeyRetrieval

預設值:false

將此選項設定為 true 會通知 Connector/NET 應從伺服器擷取 RSA 公鑰,並且當停用 SSL 時,使用傳統 MySQL 協定的連線預設會失敗。當先前成功嘗試連線,或啟用集區且可以重複使用集區連線時,可能會發生與預設行為的例外情況。此選項是在 8.0.10 連接器中引入的。

注意

此選項容易受到中間人攻擊,因此僅應在您可以透過其他方式確保連線是連線到受信任的伺服器的情況下使用。

AllowUserVariables , Allow User Variables

預設值:false

將此設定為 true 表示提供者預期 SQL 中有使用者變數。

AllowZeroDateTime , Allow Zero Datetime

預設值:false

若設定為 TrueMySqlDataReader.GetValue() 會針對日期或日期時間欄位傳回 MySqlDateTime 物件,這些欄位的值是不允許的,例如零日期時間值;若為有效的值則傳回 System.DateTime 物件。若設定為 False(預設設定),則針對所有有效值傳回 System.DateTime 物件,且針對不允許的值(例如零日期時間值)擲回例外狀況。

AutoEnlist , 自動加入

預設值:true

AutoEnlist 設定為 true(預設值),則使用 TransactionScope 開啟的連線會參與此範圍,當範圍認可時它會認可,若 TransactionScope 未認可則會回滾。然而,此功能被認為是安全性敏感的,因此無法在中度信任環境中使用。

從 8.0.10 開始,此選項在 .NET Core 2.0 實作中受支援。

BlobAsUTF8ExcludePattern

預設值:null

符合不包含 UTF-8 字元資料的 BLOB 欄位名稱的 POSIX 風格正規表示式。有關使用細節,請參閱第 5.16 節「Connector/NET 的字元集考量」

BlobAsUTF8IncludePattern

預設值:null

符合包含 UTF-8 字元資料的 BLOB 欄位名稱的 POSIX 風格正規表示式。有關使用細節,請參閱第 5.16 節「Connector/NET 的字元集考量」

CheckParameters , 檢查參數

預設值:true

指出是否應針對伺服器檢查預存常式參數。

CommandInterceptors , 命令攔截器

可以攔截 SQL 命令操作的攔截器清單。

ConnectionTimeout , 連線逾時 , 連線逾時

預設值:15

在終止嘗試並產生錯誤之前,等待連線到伺服器的時間長度(以秒為單位)。

ConvertZeroDateTime , 轉換零日期時間

預設值:false

使用 true 可讓 MySqlDataReader.GetValue()MySqlDataReader.GetDateTime() 針對具有不允許值的日期或日期時間欄位傳回 DateTime.MinValue

DefaultAuthenticationPlugin

當指定有效的驗證外掛程式時,會優先於伺服器端的預設驗證外掛程式(請參閱第 4.4 節「Connector/NET 驗證」)。Defaultauthenticationplugin 選項對於支援無使用者和無密碼的 Kerberos 驗證是強制性的,其中憑證是從快取或金鑰散佈中心 (KDC) 擷取的。例如

MySqlConnectionStringBuilder settings = new MySqlConnectionStringBuilder()
     {
       Server = "localhost", 
       UserID = "",
       Password = "",
       Database = "mydb",
       Port = 3306,
       DefaultAuthenticationPlugin = "authentication_kerberos_client"
     };

若未設定任何值,則會使用伺服器端的預設驗證外掛程式。

此選項是在 8.0.26 連接器中引入的。

DefaultCommandTimeout , 預設命令逾時

預設值:30

設定要使用的命令逾時預設值。這不會取代個別命令物件上的個別命令逾時屬性。若您設定命令逾時屬性,則會使用該屬性。

DefaultTableCacheAge , 預設表格快取期限

預設值:60

指定 TableDirect 結果應該快取多久(以秒為單位)。有關表格快取的使用資訊,請參閱第 5.3 節「搭配表格快取使用 Connector/NET」

ExceptionInterceptors , 例外狀況攔截器

可以分流擲回的 MySqlException 例外狀況的攔截器清單。

FunctionsReturnString , 函數傳回字串

預設值:false

如果中繼資料中沒有表格名稱,則會導致連接器將 binaryvarbinary 值傳回為字串。

Includesecurityasserts , 包含安全性宣告

預設值:false

在部分信任環境中使用 MySQLClientPermissions 類別時,必須將其設定為 true,並且該程式庫已安裝在主機環境的 GAC 中。詳細資訊,請參閱第 5.7 節「使用部分信任/中度信任」

從 8.0.10 開始,此選項在 .NET Core 2.0 實作中受支援。

InteractiveSession , 互動式 , 互動式工作階段

預設值:false

若設定為 true,則用戶端為互動式。互動式用戶端是指設定了伺服器變數 CLIENT_INTERACTIVE 的用戶端。若設定了互動式用戶端,則 wait_timeout 變數會設定為 interactive_timeout 的值。然後,用戶端工作階段會在不活動的這段期間後逾時。有關詳細資訊,請參閱 MySQL 參考手冊中的伺服器系統變數

從 8.0.10 開始,此選項在 .NET Core 2.0 實作中受支援。

IntegratedSecurity , 整合式安全性

預設值:no

連線至伺服器時使用 Windows 驗證。預設情況下,它是關閉的。若要啟用,請指定值 yes。(您也可以使用值 sspi 來替代 yes。)有關詳細資訊,請參閱第 4.4 節「Connector/NET 驗證」

目前不支援 .NET Core 實作。

KerberosAuthMode , kerberos 驗證模式

預設值:AUTO

在 Windows 上,提供使用安全性支援提供者介面 (SSPI) 的驗證支援,該介面能夠從 Windows 記憶體內快取擷取憑證,以及透過 MIT Kerberos 程式庫提供通用安全性服務應用程式程式設計介面 (GSSAPI)。GSSAPI 能夠擷取先前使用 kinit 命令產生的快取憑證。此選項的預設值 (AUTO) 會在嘗試使用 SSPI 驗證失敗時,嘗試使用 GSSAPI 進行驗證。

注意

此選項僅允許在 Windows 環境中使用。在非 Windows 環境中使用它會產生不支援的選項例外狀況。

此連線選項的可能值為

  • AUTO – 使用 SSPI,若失敗則回復為 GSSAPI。

  • SSPI – 僅使用 SSPI,若失敗則引發例外狀況。

  • GSSAPI – 僅使用 GSSAPI,若失敗則引發例外狀況。透過 Windows 上的 MIT Kerberos 程式庫使用 GSSAPI 時,請務必使用 KRB5_CONFIGKRB5CCNAME 環境變數來指定組態和快取位置。

記錄

預設值:false

當值設定為 true 時,各種資訊會傳送至所有已設定的追蹤接聽程式。有關更詳細的描述,請參閱第 5.12 節「Connector/NET 追蹤」

從 8.0.10 開始,此選項在 .NET Core 2.0 實作中受支援。

ociConfigFile , OCI 組態檔

預設為下列其中一個路徑名稱

  • Linux 和 macOS 主機類型上的 ~/.oci/config

  • Windows 主機類型上的 %HOMEDRIVE%%HOMEPATH%\.oci\config

若設定,此選項會指定 Oracle Cloud Infrastructure 組態檔的替代位置。Connector/NET 8.0.27(及更高版本)使用 Oracle Cloud Infrastructure SDK 來取得用於驗證的 API 金鑰指紋(fingerprint 條目)和包含 API 金鑰私密部分的 PEM 檔案位置(key_file 條目)。條目應在 [DEFAULT] 設定檔中指定。若組態檔中缺少 [DEFAULT] 設定檔,則 Connector/NET 會改為尋找下一個要使用的設定檔。

不支援 .NET Framework 4.5.x 實作。

OciConfigProfile , OCI 設定檔

若在 Connector/NET 8.0.33(或更高版本)中設定,此選項會指定要使用 Oracle Cloud Infrastructure 組態檔中的哪個設定檔。當未提供任何值時,設定檔值預設為 DEFAULT 設定檔。

不支援 .NET Framework 4.5.x 實作。

OldGuids , 舊版 GUID

預設值:false

GUID 類型的後端表示法已從 BINARY(16) 變更為 CHAR(36)。這樣做是為了讓開發人員能夠使用伺服器函數 UUID() 來填入 GUID 表格 - UUID() 會產生一個 36 個字元的字串。較舊應用程式的開發人員可以在連線字串中新增 'Old Guids=true',以使用資料類型為 BINARY(16) 的 GUID。

OldGetStringBehavior

預設值:false

從 Connector/NET 8.3.0 開始,若欄位不是字串類型,則呼叫 MySqlDataReader.GetString() 方法會擲回 InvalidCastException 例外狀況。允許所有文字類型,包括 char 和 varchar;而 blob 不被視為文字類型。

將此 OldGetStringBehavior 連線選項設定為 true 可透過記錄棄用警告而不是擲回例外狀況來還原先前的行為。

此選項是在 8.3.0 中新增,並在 9.0.0 中移除。

PersistSecurityInfo , 保留安全性資訊

預設值:false

當設定為 falseno(強烈建議)時,若連線是開啟的或曾經處於開啟狀態,則不會將安全性敏感資訊(例如密碼)當作連線的一部分傳回。重設連線字串會重設所有連線字串值,包括密碼。可辨識的值為 truefalseyesno

PipeName , 管道名稱 , 管道

預設值:mysql

當設定為具名管道的名稱時,MySqlConnection 會嘗試連線到該具名管道上的 MySQL。此設定僅適用於 Windows 平台。

重要

對於 MySQL 8.0.14 及更新版本、5.7.25 及更新版本,以及 5.6.43 及更新版本,使用具名管道連線至伺服器的用戶端,會被授予最少的權限。但是,Connector/NET 只有在被授予完整存取權時才能使用具名管道。為了變通此問題,請建立一個包含執行用戶端應用程式之使用者的 Windows 本機群組。使用 named_pipe_full_access_group 系統變數重新啟動目標伺服器,並指定本機群組名稱作為其值。

目前不支援 .NET Core 實作。

ProcedureCacheSize , Procedure Cache Size , procedure cache , procedurecache

預設值:25

設定預存程序快取的大小。預設情況下,Connector/NET 會儲存最後 25 個使用的預存程序的 Metadata(輸入/輸出資料類型)。若要停用預存程序快取,請將值設定為零 (0)。

複寫

預設值:false

表示此連線是否要使用複寫伺服器。

從 8.0.10 開始,此選項在 .NET Core 2.0 實作中受支援。

RespectBinaryFlags , Respect Binary Flags

預設值:true

將此選項設定為 false,表示 Connector/NET 會忽略伺服器所設定之資料行的二進位旗標。

SharedMemoryName , Shared Memory Name

預設值:mysql

如果傳輸協定設定為 memory,則用於通訊的共用記憶體物件名稱。此設定僅適用於 Windows 平台。

目前不支援 .NET Core 實作。

SqlServerMode , Sql Server Mode

預設值:false

允許 SQL Server 語法。當設定為 true 時,會啟用 Connector/NET 支援符號周圍的方括號,而不是反引號。這可讓 Visual Studio 精靈在 [] 字元之間括住符號,以使用 Connector/NET。此選項會產生效能損失,因此僅應在必要時使用。

TableCaching , Table Cache , TableCache

預設值:false

啟用或停用 TableDirect 命令的快取。值為 true 會啟用快取,而 false 會停用快取。如需表格快取的使用資訊,請參閱 第 5.3 節「使用 Connector/NET 和表格快取」

TreatBlobsAsUTF8 , Treat BLOBs as UTF8

預設值:false

將此值設定為 true 會導致 BLOB 資料行具有 utf8 字元集,並具有該字元集的預設定序。若要僅轉換某些 BLOB 資料行,您可以使用 'BlobAsUTF8IncludePattern''BlobAsUTF8ExcludePattern' 關鍵字。將這些設定為符合要包含或排除之資料行名稱的正規表示式模式。

TreatTinyAsBoolean , Treat Tiny As Boolean

預設值:true

將此值設定為 false 會導致將 TINYINT(1) 視為 INT。如需 TINYINTBOOL 資料類型的進一步說明,請參閱 數值資料類型語法

UseAffectedRows , Use Affected Rows

預設值:false

true 時,連線會報告變更的資料列,而不是找到的資料列。

UseCompression , Compress , Use Compression

預設值:false

將此選項設定為 true 會啟用用戶端和伺服器之間交換的封包壓縮。此交換是由 MySQL 用戶端/伺服器協定所定義。

如果用戶端和伺服器都支援 ZLIB 壓縮,且用戶端已使用此選項要求壓縮,則會使用壓縮。

壓縮的封包標頭為:封包長度 (3 個位元組)、封包編號 (1 個位元組) 和未壓縮封包長度 (3 個位元組)。未壓縮封包長度是原始未壓縮封包中的位元組數。如果此值為零,則此封包中的資料尚未壓縮。當使用壓縮協定時,用戶端或伺服器可能會壓縮封包。但是,如果壓縮後的長度大於原始長度,則不會發生壓縮。因此,某些封包會包含壓縮資料,而其他封包則不會。

UseDefaultCommandTimeoutForEF , Use Default Command Timeout For EF

預設值:false

強制執行 EFMySqlCommand 的命令逾時,此逾時會設定為 DefaultCommandTimeout 屬性所提供的值。

UsePerformanceMonitor , Use Performance Monitor , UserPerfMon , PerfMon

預設值:false

表示應該在執行期間更新效能計數器。

目前不支援 .NET Core 實作。

UseUsageAdvisor , Use Usage Advisor , Usage Advisor

預設值:false

記錄效率不佳的資料庫作業。

從 8.0.10 開始,此選項在 .NET Core 2.0 實作中受支援。

連線集區選項。 以下選項與連線字串中的連線集區相關。如需連線集區的詳細資訊,請參閱開啟與單一伺服器的連線

CacheServerProperties , Cache Server Properties

預設值:false

指定每次傳回集區連線時是否透過 SHOW VARIABLES 命令更新伺服器變數設定。啟用此設定可加快連線集區環境中的連線速度。您的應用程式不會收到其他連線對組態變數所做的任何變更通知。

ConnectionLifeTime , Connection Lifetime

預設值:0

當連線傳回集區時,會將其建立時間與目前時間進行比較,如果該時間跨度(以秒為單位)超過 Connection Lifetime 指定的值,則會銷毀連線。此選項在叢集組態中很有用,可強制執行在執行中的伺服器和剛上線的伺服器之間進行負載平衡。值為零 (0) 會將集區連線設定為最大連線逾時。

ConnectionReset , Connection Reset

預設值:false

如果為 true,則當從集區擷取連線時,會重設連線狀態。預設值為 false,可避免在取得連線時進行額外的伺服器往返行程,但不會重設連線狀態。

MaximumPoolsize , Max Pool Size , Maximum Pool Size , MaxPoolSize

預設值:100

集區中允許的最大連線數。

MinimumPoolSize , Min Pool Size , Minimum Pool Size , MinPoolSize

預設值:0

集區中允許的最小連線數。

集區

預設值:true

true 時,會從適當的集區提取 MySqlConnection 物件,或在必要時建立並新增至適當的集區。可辨識的值為 truefalseyesno

僅適用於 X 協定的選項

以下連線選項適用於使用 X 協定建立的連線。Connector/NET 8.0 會在此區段中公開選項,作為 MySqlX.XDevAPI.MySqlXConnectionStringBuilder 類別中的屬性。

Auth , Authentication , Authentication Mode

與 X 協定搭配使用的驗證機制。此選項是隨著 8.0.9 連接器引入的,具有以下不區分大小寫的值:MYSQL41PLAINEXTERNAL。如果未設定 Auth 選項,則會根據連線類型選擇機制。PLAIN 用於安全連線(TLS 或 Unix Socket),而 MYSQL41 用於未加密的連線。EXTERNAL 用於外部驗證方法,例如 PAM、Windows 登入 ID、LDAP 或 Kerberos。(目前不支援 EXTERNAL。)

不支援傳統 MySQL 協定連線的 Auth 選項,如果使用,會傳回 NotSupportedException

Compression , use-compression

預設值:preferred

當用戶端和伺服器都支援 X 協定連線且用戶端使用此選項要求壓縮時,會使用壓縮來傳送和接收資料。成功完成演算法交涉後,Connector/NET 可以立即開始壓縮資料。為了防止壓縮小型資料封包或已壓縮的資料,Connector/NET 定義了 1000 個位元組的大小閾值。

當伺服器支援多種壓縮演算法時,Connector/NET 預設會套用下列優先順序:zstd_stream (第一)、lz4_message (第二) 和 deflate_stream (第三)。deflate_stream 演算法支援與 .NET Core 搭配使用,但不適用於 .NET Framework。

提示

使用 compression-algorithms 選項以不同的順序指定一或多個支援的演算法。這些演算法會按照用戶端提供的順序進行交涉。如需使用詳細資訊,請參閱 compression-algorithms 選項。

Connector/NET 8.0.20 版本新增了 X 協定連線的資料壓縮。Compression 選項接受下列值

  • preferred:如果伺服器支援用戶端選擇的演算法,則套用資料壓縮。否則,會傳送和接收未壓縮的資料。

  • required:確保使用壓縮,或終止連線並傳回錯誤訊息。

  • disabled:防止資料壓縮。

compression-algorithms , CompressionAlgorithms

從 Connector/NET 8.0.22 開始,用戶端應用程式可以指定與伺服器交涉支援的壓縮演算法的順序。Compression 連線選項的值必須設定為 preferredrequired,此選項才能套用。系統會忽略不支援的演算法。

此選項接受下列演算法名稱和同義詞

  • lz4_messagelz4

  • zstd_streamzstd

  • deflate_streamdeflate (不適用於 .NET Framework)

演算法名稱和同義詞可以合併在逗號分隔的清單中,或以獨立值形式提供 (含或不含括號)。範例

// Compression option set to preferred (default)
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression-algorithms=[lz4_message,deflate]
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compressionalgorithms=lz4
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=preferred&compression-algorithms=[zstd]

// Compression option set to required
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=required&compression-algorithms=[zstd_stream,lz4_message]
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=required&compression-algorithms=[lz4]
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=required&compression-algorithms=zstd_stream

// Connection string
MySQLX.GetSession("server=localhost;port=3306;uid=test;password=test;compression=required;compression-algorithms=lz4_message;")

// Anonymous object
MySQLX.GetSession(new { 
   server = "localhost", 
   port = "3306", 
   uid = "test", 
   password = "test", 
   compression="required", 
   compressionalgorithms = "deflate_stream" })

如需更多資訊,請參閱使用 X Plugin 的連線壓縮

connection-attributes , ConnectionAttributes

預設值:true

此選項在 Connector/NET 8.0.16 中引入,用於提交一組要與預設連線屬性一起傳遞到伺服器的屬性。用戶端傳送的連線屬性資料總大小受限於performance_schema_session_connect_attrs_size 伺服器變數的值。資料封包的總大小應小於伺服器變數的值。關於連線屬性的一般資訊,請參閱效能綱要連線屬性表格

connection-attributes 參數值可以是空的 (等同於指定 true)、一個布林值 (truefalse 來啟用或停用預設屬性集),或以逗號分隔的零或多個 key=value 規範的清單 (除了預設屬性集之外還要傳送)。在清單中,遺失的鍵值會評估為 NULL 值。範例

// Sessions
MySQLX.GetSession($"mysqlx://user@host/schema")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=true")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=false")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=[attr1=val1,attr2,attr3=]")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=[]")

// Pooling
MySQLX.GetClient($"mysqlx://user@host/schema")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=true")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=false")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=[attr1=val1,attr2,attr3=]")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=[]")

應用程式定義的屬性名稱不能以 _ 開頭,因為此類名稱保留用於內部屬性。

如果連線屬性的指定方式不正確,則會發生錯誤,且連線嘗試將失敗。

Connect-Timeout , ConnectTimeout

預設值: 10000

在終止嘗試並產生錯誤之前,等待與伺服器建立 X 通訊協定連線的時間長度(以毫秒為單位)。您可以將值設定為零來停用連線逾時。此選項可以指定如下:

  • 類似 URI 的連線字串範例

    MySQLX.GetSession("mysqlx://test:test@localhost:33060?connect-timeout=2000");
  • 連線字串範例

    MySQLX.GetSession("server=localhost;user=test;port=33060;connect-timeout=2000");
  • 匿名物件範例

    MySQLX.GetSession(new { server="localhost", user="test", port=33060, connecttimeout=2000 });
  • MySqlXConnectionStringBuilder 類別範例

    var builder = new MySqlXConnectionStringBuilder("server=localhost;user=test;port=33060");
    builder.ConnectTimeout = 2000;
    MySQLX.GetSession(builder.ConnectionString);
SslCrl , Ssl-Crl

預設值:null

包含憑證撤銷清單的本機檔案路徑。

重要

雖然 SslCrl 連線字串選項可有效使用,但應用它會引發 NotSupportedException 訊息。