本章節說明 MySQL Connector/NET 8.0 的完整連線選項集。您用來與伺服器建立連線的協定(傳統 MySQL 協定或 X 協定)決定了您應該使用的選項。連線選項具有預設值,您可以藉由在連接字串(傳統 MySQL 協定和 X 協定)或類似 URI 的連接字串 (X 協定) 中定義新值來覆寫它。Connector/NET 選項名稱和同義詞不區分大小寫。
如需有關如何使用連接字串的指示,請參閱第 4.1 節「建立 Connector/NET 連接字串」。如需替代的連線樣式,請參閱使用類似 URI 的字串或金鑰值組連線至伺服器。
以下各節列出適用於兩種協定、僅適用於傳統 MySQL 協定和僅適用於 X 協定的連線選項
以下 Connector/NET 連線選項可與任一協定搭配使用。Connector/NET 8.0 在 MySql.Data.MySqlClient.MySqlConnectionStringBuilder
和 MySqlX.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
)指定與伺服器建立連線的類型。值可以是
socket
或tcp
,用於使用 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=false
和mysqlx+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 };
如果伺服器不要求秘密密碼與驗證方法一起使用,則會忽略為
password
、password2
或password3
選項指定的值。-
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
連線選項設定為Required
、VerifyCA
或VerifyFull
值時,此選項才會啟用;否則會忽略。當使用 PEM 憑證時,當
SslMode
連線選項設定為VerifyCA
或VerifyFull
值時,此選項才會啟用;否則會忽略。如需使用範例,請參閱第 6.7.1 節「在 Connector/NET 中使用 PEM 憑證」。
-
SslCert
,Ssl-Cert
預設值:
null
用於建立加密連線的 PEM 格式 SSL 憑證檔案名稱。此選項僅當為
SslMode
連線選項設定VerifyFull
且SslCa
連線選項使用 PEM 憑證時才會啟用;否則會忽略。如需使用範例,請參閱第 6.7.1 節「在 Connector/NET 中使用 PEM 憑證」。-
SslKey
,Ssl-Key
預設值:
null
用於建立加密連線的 PEM 格式 SSL 金鑰檔案名稱。此選項僅當為
SslMode
連線選項設定VerifyFull
且SslCa
連線選項使用 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
連線字串選項的值未設定為Disabled
或None
(在 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 登入帳戶。
與使用連線集區的系統相關的選項會一起出現在一般選項清單的末尾(請參閱連線集區選項)。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
的檔案要求可能會成功。不允許任何超出此路徑的相對路徑或符號連結。下表顯示當合併
AllowLoadLocalInfile
和AllowLoadLocalInfileInPath
連線字串選項時產生的行為。-
AllowPublicKeyRetrieval
預設值:
false
將此選項設定為
true
會通知 Connector/NET 應從伺服器擷取 RSA 公鑰,並且當停用 SSL 時,使用傳統 MySQL 協定的連線預設會失敗。當先前成功嘗試連線,或啟用集區且可以重複使用集區連線時,可能會發生與預設行為的例外情況。此選項是在 8.0.10 連接器中引入的。注意此選項容易受到中間人攻擊,因此僅應在您可以透過其他方式確保連線是連線到受信任的伺服器的情況下使用。
-
AllowUserVariables
,Allow User Variables
預設值:
false
將此設定為
true
表示提供者預期 SQL 中有使用者變數。-
AllowZeroDateTime
,Allow Zero Datetime
預設值:
false
若設定為
True
,MySqlDataReader.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
如果中繼資料中沒有表格名稱,則會導致連接器將
binary
或varbinary
值傳回為字串。-
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_CONFIG
和KRB5CCNAME
環境變數來指定組態和快取位置。
-
記錄
預設值:
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
當設定為
false
或no
(強烈建議)時,若連線是開啟的或曾經處於開啟狀態,則不會將安全性敏感資訊(例如密碼)當作連線的一部分傳回。重設連線字串會重設所有連線字串值,包括密碼。可辨識的值為true
、false
、yes
和no
。-
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
。如需TINYINT
和BOOL
資料類型的進一步說明,請參閱 數值資料類型語法。-
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
物件,或在必要時建立並新增至適當的集區。可辨識的值為true
、false
、yes
和no
。
以下連線選項適用於使用 X 協定建立的連線。Connector/NET 8.0 會在此區段中公開選項,作為 MySqlX.XDevAPI.MySqlXConnectionStringBuilder
類別中的屬性。
-
Auth
,Authentication
,Authentication Mode
與 X 協定搭配使用的驗證機制。此選項是隨著 8.0.9 連接器引入的,具有以下不區分大小寫的值:
MYSQL41
、PLAIN
和EXTERNAL
。如果未設定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
連線選項的值必須設定為preferred
或required
,此選項才能套用。系統會忽略不支援的演算法。此選項接受下列演算法名稱和同義詞
lz4_message
或lz4
zstd_stream
或zstd
deflate_stream
或deflate
(不適用於 .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
)、一個布林值 (true
或false
來啟用或停用預設屬性集),或以逗號分隔的零或多個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
訊息。