2024 年 .NET Driver 版本说明¶

新功能和改进¶

• 添加了 驱动程序包上的签名 (https://github.com/snowflakedb/snowflake-connector-net/blob/43924472903467ad741f8d1ea3ee777c02e21829/README.md#verifying-the-package-signature) 以验证其真实性和完整性。

• 添加了对读取向量类型的支持。有关更多信息，请参阅 VectorType.md (https://github.com/snowflakedb/snowflake-connector-net/blob/d69e2cb42ebd0f076476b979dcd249a0470f4e71/doc/VectorType.md)。

• 为 JSON 结果格式添加了读取结构化类型的支持。有关更多信息，请参阅 `.md StructeredType`_。

• 为客户端环境配置添加了日志记录。

• 实现了 SnowflakeDbDataReader.GetEnumerator()。

错误修复¶

• 将 :codenowrap: SnowflakeDbConnection 终结器更改为不会阻止。

• 修复了某些可处置对象未能正确处置的问题。

• 改进了读取大型查询结果的内存管理。

• 提高了 HTTP 响应失败消息的日志级别。

• 停止了对不可恢复的身份验证异常进行重试。

• 修复了初始化连接池时的并发问题。

• 将 DateTime.Kind 更改为了 Unspecified，旨在读取 DATE、TIME 和 TIMESTAMP_NTZ Snowflake 类型。该驱动程序的 2.1.3 版引入了一项不必要的变更，会将:codenowrap:DateTime.Kind 设置为 Utc。

• 修复了 GCS 客户端中 PUT/GET 操作的 null 响应处理问题。

• 修复了 S3 客户端中 PUT/GET 操作的异常处理。

• 修复了非常大或非常小的时间戳处理。

• 改进了下一次重试时间计算的逻辑。

• 修复了来自多个文件的 COPY 语句的返回行数。

• 修复了对无客户端加密的 PUT/GET 文件的支持。

新功能和改进¶

• 添加了有关驱动程序所连接域目标的日志消息。

• 更新了 DbCommand.Prepare()，使其不再抛出异常，而是不执行任何操作。

错误修复¶

• 修复了取消 OpenAsync 操作时取消异常丢失的问题。

BCR （行为变更版本）变更¶

从 4.0.0 版本开始，.NET 驱动程序引入了以下重大变更：

• 连接池行为变更：

  • 现在，驱动程序为每个唯一的连接字符串使用单独的池。以前，驱动程序对所有连接字符串仅使用一个池。

  • maxPoolSize 参数变更：

    • 以前，该参数表示要存储在池中的连接数。现在，该参数定义了允许为给定池打开的最大连接数（每个唯一的连接字符串有不同的池，因此您可以为其设置不同的连接池）。

    • 如果达到了 maxPoolSize，则请求新连接的线程将等待，直到池中的任何连接都可以在不超过限制的情况下重复使用。如果超时，则会引发异常。

    • 您可以通过设置 waitingForIdleSessionTimeout 属性来配置连接字符串中的等待时间。超时的默认值为 30 秒。您可以将其更改为 0 来禁用等待。

    • maxPoolSize 的默认值为 10。确保根据需要正确设置您的 maxPoolSize 值，以避免线程挂起或出现超时异常。

    • 该 maxPoolSize 属性应大于或等于 minPoolSize。

  • 添加了一个默认值为 2 的新 minPoolSize 参数，当您打开给定连接字符串的第一个连接时，驱动程序会打开两个连接（第二个在后台）。如果要禁用 minPoolSize 功能，可以在连接字符串中将此值设置为 0。

  • 池的配置已变更为连接字符串驱动的方法。控制连接池行为的所有属性现在都可以在连接字符串中传递。无法再通过 SnowflakeDbConnectionPool 设置函数设置连接池的属性，例如 SnowflakeDbConnectionPool.SetTimeout、SetPooling 或 SetMaxPoolSize。现在使用 SnowflakeDbConnectionPool 设置函数会抛出异常。

  • 以前，更改数据库、架构、角色或仓库（例如，通过执行 ALTER SESSION SET 命令）参数的连接会进入池中。对于此类情况，新的默认行为是在关闭时不将更改过的连接返回池中，而是将其销毁。如果您想在池中使用更改过的连接，则需要在连接字符串中添加 ChangedSession=OriginalPool。

  • 默认情况下，具有外部浏览器身份验证的连接或某些 KeyPair/JWT 令牌身份验证的连接不再存储在池中。要使此类连接进入池中，必须在连接字符串中添加 poolingenabled=True。对于其他身份验证方法，默认情况下即可进入池中。

  • 有关使用连接池的更多信息，请参阅 使用连接池 (https://github.com/snowflakedb/snowflake-connector-net/blob/master/doc/ConnectionPooling.md)。

• NONPOXYHOSTS 参数行为变更：

  NONPROXYHOSTS 参数的行为已变更。以前，如果主机名称包含此参数中指定的值，则该主机无法实现代理。现在，只有当主机名称完全为参数中指定的值时，才无法实现代理。例如，以前的 NONPROXYHOSTS=c 会匹配任何包含“c”的主机，例如“your-account.snowflakecomputing.cn”。变更后，必须指定整个主机，例如 NONPROXYHOSTS=your-account.snowflakecomputing.cn，才能使其无法实现代理。

新功能和改进¶

• 使用多个池（每个唯一的连接字符串一个）和连接字符串驱动的配置变更了连接池行为。有关使用连接池的更多信息，请参阅 使用连接池 (https://github.com/snowflakedb/snowflake-connector-net/blob/master/doc/ConnectionPooling.md)。

• 定位到 .netstandard 2.0。

• 为驱动程序集添加了强名称签名。

• 添加了在连接字符串和 SnowflakeDbCommand 对象上设置 QueryTag 参数的功能，以使用标签标记连接和命令查询。

• 升级了 BouncyCastle.Cryptography 依赖关系。

• 升级了 Google.Cloud.Storage.V1 依赖关系。

• 引入了一个新的 DISABLE_SAML_URL_CHECK 参数。在使用 Okta 进行身份验证时，如果 SAML 回传 URL 与主机 URL 匹配，该参数会禁用检查。

错误修复¶

• 针对含有大量绑定（超出 CLIENT_STAGE_ARRAY_BINDING_THRESHOLD）的查询，修复了通过绑定传递日期和时间值的处理方式。

• 修复了向服务器发送 SQL 查询的方式，改为发送原始查询而非经过修剪的查询，后者会导致以注释结尾的查询报错。

• 在 NONPROXYHOSTS 参数中实现了一种更可靠的提供主机的方式。

• 修复了在 DB、SCHEMA、WAREHOUSE、ROLE 连接字符串参数中支持双引号的问题。

• 修复了 S3 客户端，如果缺失，则向 ServiceUrl 添加 “https:// (https://)”。

• 更新了密钥探测器，以便在登录时更好地掩盖密钥。

• 添加了设置适当 SnowflakeDbParameter.DbType 值的功能

• 修复了在 retryTimeout 值为无限大时，connectionTimeout 被 retryTimeout 缩短的逻辑。

• 针对 HTTP 客户端，将增加 maxHttpRetries 的逻辑应用到了默认值。以前，该逻辑仅适用于 Okta 身份验证。

新功能和改进¶

• 添加了对运行异步查询的支持。

错误修复¶

• 改进了从 Okta 身份验证器抛出的异常。

• 修复了验证极短（1-2 个字符）账户名称的问题。

• 修复了有关从包含引用内容的连接字符串（如 "WAREHOUSE=\"two words\""）中检索 WAREHOUSE 属性的问题。

BCR （行为变更版本）变更¶

• 为了提高安全性，驱动程序不再搜索临时目录来进行简单的日志记录配置。此外，驱动程序现在要求 Unix 系统中的日志记录配置文件对文件权限进行限制，只允许文件所有者修改文件（如 chmod 0600、chmod 0644）。

• 对于 PUT/GET 故障，驱动程序现在抛出一个带有 QueryID 的 SnowflakeDbException。此前，驱动程序返回不同类型的异常，如 FileNotFound 和 DirectoryNotFound。如果您的应用程序检查出了这些异常中的任何一个，则必须更新代码，仅处理 PUT/GET 故障的 SnowflakeDbException。

• 驱动程序不再支持块解析器/下载器的旧版本，如 V1 和 V2。作为升级到 V3 版本的一部分，驱动程序不再支持 SFConfiguration.UseV2JsonParser 或 SFConfiguration.UseV2ChunkDownloader 配置选项。如果您使用了类似于下面的命令，则应将其移除：

  • SFConfiguration.Instance().ChunkParserVersion = 1; 或 SFConfiguration.Instance().ChunkParserVersion = 2;

  • SFConfiguration.Instance().ChunkDownloaderVersion = 1; 或 SFConfiguration.Instance().ChunkDownloaderVersion = 2;

  • SFConfiguration.Instance().UseV2JsonParser

  • SFConfiguration.Instance().UseV2ChunkDownloader

新功能和改进¶

• 添加了对多种 SAML 集成的支持。

错误修复¶

• 改进了简单日志记录功能的安全性，包括：

  • 使用更可靠的方式来确定在搜索客户端配置文件时，使用哪个驱动程序目录。

  • 不再使用临时目录进行配置搜索。

  • 在 Unix 下强制执行额外的文件权限检查，以提高安全性。

  • 添加更为详细的日志记录。

• 修复了 SSO/SAML 端点的 Okta 重试问题。

• 为不执行文本的命令添加了快速失败。

• 修复了 PUT/GET 执行失败时抛出的异常，以尽可能包含 QueryId。

• 将 Portable.BouncyCastle 库替换为 BouncyCastle.Cryptography。

BCR （行为变更版本）变更¶

• 从版本 2.2.0 开始，.NET 驱动程序在根据账户名构造主机名时，会自动将账户名中的下划线 (_) 替换为连字符 (-)。此更改影响账户名包含下划线的 PrivateLink 客户。在这种情况下，必须通过将 allowUnderscoresInHost 设置为 true 来替换默认值。您可以在 ConnectionString 中设置 allowUnderscoresInHost=true，来替换此行为。

  做出此更改是为了修复在通过公共链接与账户名称中含有下划线的 Snowflake 账户连接时出现的 DNS 解析错误。

新功能和更新¶

• 改进了 Arrow 性能。

• 在根据账户名构造主机名时，自动将账户名中的下划线 (_) 替换为连字符 (-)。

• 添加了 allowUnderscoresInHost 配置参数，允许在构造的主机名中保留账户名中的下划线 (_)。此参数使您可以替换与此版本关联的行为变更。

错误修复¶

• 为了修复连接超时的问题，驱动程序现在会在连接时异步关闭过期会话。