本章介绍了 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 的套接字连接。pipe
,用于命名管道连接(X 协议不支持)。unix
,用于 UNIX 套接字连接。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 套接字、命名管道或共享内存连接(请参阅
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
连接选项)。-
端口
默认值:
3306
MySQL 用于侦听连接的端口。如果使用 Unix 套接字,则忽略此值。
-
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 套接字文件的完全限定路径。使用此配置时,将使用 UNIX 套接字而不是 TCP/IP 套接字。目前,只能指定一个套接字名称,因此当前不支持使用 UNIX 套接字访问复制环境中的 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 协议),Required
为必需。对于 8.0.13 及更高版本(仅限经典 MySQL 协议),
Preferred
为首选。
此选项具有以下值
Disabled
- 不使用 SSL。对于 Connector/NET 8.0.29 或更高版本,不支持 SSL 的服务器需要将此选项显式设置为Disabled
。None
- 不使用 SSL。对于 Connector/NET 8.0.8 或更高版本,不支持 SSL 的服务器需要将此选项显式设置为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
,Auto Enlist
默认值:
true
如果
AutoEnlist
设置为默认值true
,则使用TransactionScope
打开的连接将参与此范围,并在范围提交时提交,如果TransactionScope
未提交,则回滚。但是,此功能被认为是安全敏感的,因此不能在中等信任环境中使用。从 8.0.10 开始,.NET Core 2.0 实现中支持此选项。
-
BlobAsUTF8ExcludePattern
默认值:
null
一个 POSIX 风格的正则表达式,用于匹配不包含 UTF-8 字符数据的 BLOB 列的名称。有关用法详细信息,请参阅第 5.16 节“Connector/NET 的字符集注意事项”。
-
BlobAsUTF8IncludePattern
默认值:
null
一个 POSIX 风格的正则表达式,用于匹配包含 UTF-8 字符数据的 BLOB 列的名称。有关用法详细信息,请参阅第 5.16 节“Connector/NET 的字符集注意事项”。
-
CheckParameters
,Check Parameters
默认值:
true
指示是否应根据服务器检查存储的例程参数。
-
CommandInterceptors
,Command Interceptors
可以拦截 SQL 命令操作的拦截器列表。
-
ConnectionTimeout
,Connect Timeout
,Connection Timeout
默认值:
15
等待连接到服务器的时间长度(以秒为单位),超过此时间后将终止尝试并生成错误。
-
ConvertZeroDateTime
,Convert Zero Datetime
默认值:
false
使用
true
使MySqlDataReader.GetValue()
和MySqlDataReader.GetDateTime()
对于具有不允许值的日期或日期时间列返回DateTime.MinValue
。-
DefaultAuthenticationPlugin
当指定了有效的身份验证插件时,优先于服务器端默认身份验证插件(请参阅第 4.4 节“连接器/网络身份验证”)。
Defaultauthenticationplugin
选项对于支持无用户和无密码的 Kerberos 身份验证是必需的,在这种身份验证中,凭据是从缓存或密钥分发中心 (KDC) 中检索的。例如MySqlConnectionStringBuilder settings = new MySqlConnectionStringBuilder() { Server = "localhost", UserID = "", Password = "", Database = "mydb", Port = 3306, DefaultAuthenticationPlugin = "authentication_kerberos_client" };
如果未设置任何值,则使用服务器端默认身份验证插件。
此选项是在 8.0.26 连接器中引入的。
-
DefaultCommandTimeout
,Default Command Timeout
默认值:
30
设置要使用的命令超时默认值。这不会取代单个命令对象上的单个命令超时属性。如果设置了命令超时属性,则将使用该属性。
-
DefaultTableCacheAge
,Default Table Cache Age
默认值:
60
指定
TableDirect
结果应缓存多长时间(以秒为单位)。有关表缓存的使用信息,请参阅第 5.3 节“将连接器/网络与表缓存一起使用”。-
ExceptionInterceptors
,Exception Interceptors
可以对抛出的
MySqlException
异常进行分类的拦截器列表。-
FunctionsReturnString
,Functions Return String
默认值:
false
如果
binary
或varbinary
值在元数据中没有表名,则使连接器将它们作为字符串返回。-
Includesecurityasserts
,Include security asserts
默认值:
false
在部分信任环境中使用
MySQLClientPermissions
类时,必须将其设置为true
,并将库安装在托管环境的 GAC 中。有关详细信息,请参阅第 5.7 节“使用部分信任/中等信任”。从 8.0.10 开始,.NET Core 2.0 实现中支持此选项。
-
InteractiveSession
,Interactive
,Interactive Session
默认值:
false
如果设置为
true
,则客户端是交互式的。交互式客户端是指服务器变量CLIENT_INTERACTIVE
设置为 true 的客户端。如果设置了交互式客户端,则wait_timeout
变量将设置为interactive_timeout
的值。然后,客户端会话将在该非活动时间段后超时。有关更多信息,请参阅 MySQL 参考手册中的服务器系统变量。从 8.0.10 开始,.NET Core 2.0 实现中支持此选项。
-
IntegratedSecurity
,Integrated Security
默认值:
no
连接到服务器时使用 Windows 身份验证。默认情况下,它是关闭的。要启用,请指定值
yes
。(您也可以使用值sspi
作为yes
的替代值。)有关详细信息,请参阅第 4.4 节“连接器/网络身份验证”。当前不支持 .NET Core 实现。
-
KerberosAuthMode
,kerberos auth mode
默认值:
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 节“连接器/网络跟踪”。从 8.0.10 开始,.NET Core 2.0 实现中支持此选项。
-
ociConfigFile
,OCI Config File
默认为以下路径名之一
Linux 和 macOS 主机类型上的
~/.oci/config
Windows 主机类型上的
%HOMEDRIVE%%HOMEPATH%\.oci\config
如果设置,此选项指定 Oracle Cloud Infrastructure 配置文件的备用位置。连接器/网络 8.0.27(及更高版本)使用 Oracle Cloud Infrastructure SDK 获取用于身份验证的 API 密钥指纹(
fingerprint
条目)以及包含 API 密钥私钥部分的 PEM 文件的位置(key_file
条目)。应在[DEFAULT]
配置文件中指定这些条目。如果配置文件中缺少[DEFAULT]
配置文件,连接器/网络将找到下一个配置文件来代替使用。不支持 .NET Framework 4.5.
x
实现。-
OciConfigProfile
,OCI Config Profile
如果在连接器/网络 8.0.33(或更高版本)中设置,此选项指定要使用的 Oracle Cloud Infrastructure 配置文件中的哪个配置文件。如果未提供任何值,则配置文件值默认为
DEFAULT
配置文件。不支持 .NET Framework 4.5.
x
实现。-
OldGuids
,Old Guids
默认值:
false
GUID 类型的后端表示已从
BINARY(16)
更改为CHAR(36)
。这样做是为了允许开发人员使用服务器函数UUID()
来填充 GUID 表 -UUID()
生成一个 36 个字符的字符串。较旧应用程序的开发人员可以将'Old Guids=true'
添加到连接字符串以使用数据类型为BINARY(16)
的 GUID。-
OldGetStringBehavior
默认值:
false
从连接器/网络 8.3.0 开始,如果列不是字符串类型,则调用 MySqlDataReader.GetString() 方法会引发
InvalidCastException
异常。允许所有文本类型,包括 char 和 varchar;blob 不被视为文本类型。将此 OldGetStringBehavior 连接选项设置为
true
可以通过记录弃用警告而不是引发异常来恢复先前的行为。此选项在 8.3.0 中添加,在 9.0.0 中删除。
-
PersistSecurityInfo
,Persist Security Info
默认值:
false
当设置为
false
或no
(强烈建议)时,如果连接处于打开状态或曾经处于打开状态,则不会将密码等安全敏感信息作为连接的一部分返回。重置连接字符串会重置所有连接字符串值,包括密码。识别的值为true
、false
、yes
和no
。-
PipeName
,Pipe Name
,Pipe
默认值:
mysql
当设置为命名管道的名称时,
MySqlConnection
尝试连接到该命名管道上的 MySQL。此设置仅适用于 Windows 平台。重要对于 MySQL 8.0.14 及更高版本、5.7.25 及更高版本以及 5.6.43 及更高版本,将向使用命名管道连接到服务器的客户端授予最小权限。但是,连接器/网络只能在被授予对命名管道的完全访问权限时才能使用它们。作为一种解决方法,创建一个 Windows 本地组,其中包含执行客户端应用程序的用户。使用
named_pipe_full_access_group
系统变量重新启动目标服务器,并将本地组名指定为其值。当前不支持 .NET Core 实现。
-
ProcedureCacheSize
,Procedure Cache Size
,procedure cache
,procedurecache
默认值:
25
设置存储过程缓存的大小。默认情况下,连接器/网络存储有关最后使用的 25 个存储过程的元数据(输入/输出数据类型)。要禁用存储过程缓存,请将该值设置为零 (0)。
-
复制
默认值:
false
指示此连接是否使用复制服务器。
从 8.0.10 开始,.NET Core 2.0 实现中支持此选项。
-
RespectBinaryFlags
,Respect Binary Flags
默认值:
true
将此选项设置为
false
表示连接器/网络忽略服务器设置的列的二进制标志。-
SharedMemoryName
,Shared Memory Name
默认值:
mysql
如果传输协议设置为
memory
,则用于通信的共享内存对象的名称。此设置仅适用于 Windows 平台。当前不支持 .NET Core 实现。
-
SqlServerMode
,Sql Server Mode
默认值:
false
允许 SQL Server 语法。当设置为
true
时,连接器/网络将支持使用方括号而不是反引号来括起符号。这使得在[
和]
字符之间使用方括号括起符号的 Visual Studio 向导能够与连接器/网络一起使用。此选项会降低性能,因此应仅在必要时使用。-
TableCaching
,Table Cache
,TableCache
默认值:
false
启用或禁用
TableDirect
命令的缓存。值为true
将启用缓存,而false
将禁用缓存。有关表缓存的使用信息,请参阅第 5.3 节“将连接器/网络与表缓存一起使用”。-
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
选项,则会根据连接类型选择机制。对于安全连接(TLS 或 Unix 套接字),使用PLAIN
,而对于未加密连接,则使用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 插件进行连接压缩。
-
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
消息。