文档主页
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 的套接字连接。

  • 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=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 连接选项)。

端口

默认值: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 连接选项设置为 RequiredVerifyCAVerifyFull 时,此选项将启用;否则,将忽略此选项。

使用 PEM 证书时,当 SslMode 连接选项设置为 VerifyCAVerifyFull 时,此选项将启用;否则,将忽略此选项。

有关用法示例,请参阅第 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 连接字符串选项的值未设置为 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

如果设置为 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

如果 binaryvarbinary 值在元数据中没有表名,则使连接器将它们作为字符串返回。

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_CONFIGKRB5CCNAME 环境变量来指定配置和缓存位置。

日志记录

默认值: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

当设置为 falseno(强烈建议)时,如果连接处于打开状态或曾经处于打开状态,则不会将密码等安全敏感信息作为连接的一部分返回。重置连接字符串会重置所有连接字符串值,包括密码。识别的值为 truefalseyesno

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。有关 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 选项,则会根据连接类型选择机制。对于安全连接(TLS 或 Unix 套接字),使用 PLAIN,而对于未加密连接,则使用 MYSQL41EXTERNAL 用于外部身份验证方法,例如 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 插件进行连接压缩

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 消息。