DbConnectionStringBuilder.ShouldSerialize() doesn't state purpose

[Cygon]

Type of issue

Missing information

Description

The documentation for the DbConnectionStringBuilder.ShouldSerialize() method looks like a copy and paste of the documentation on the DbConnectionStringBuilder.ContainsKey() method.

A bit more clarity on the purpose of the method and how it is diffeent from .ContainsKey() would be useful for implementers.

My best guess is that the ShouldSerialize() method is intended to check if a key is valid for the ADO.NET client implementing the specialized connection string builder from the perspective that unsupported keys do not have to be serialized when the connection string builder serializes its key/value dictionary into a string.

If that's the case, I would suggest the following documentation (which, just in case, I hereby declare to have just written myself in this browser window and which I offer freely and for use for any purpose, including modification, re-licensing and inclusion in differently-licensed works)

/// <summary>
///   Allows the database-specific ADO.NET provider's specialized connection string builder inheriting
///   from this class to indicate whether the specified key is supported by that ADO.NET provider.
/// </summary>
/// <param name="keyword">The key to check for support by the specific ADO.NET provider</param>
/// <returns>
///   True if the ADO.NET provider recognized and supports the specified key, false otherwise
/// </returns>
/// <remarks>
///   This method can be used to sanitize connection strings and to avoid confusion by removing any
///   keys for options that an ADO.NET provider does not support anyway, but which the user may
///   believe to have some effect for the database connection
/// </remarks>
public virtual bool ShouldSerialize(string keyword) { /* ... */ }

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.data.common.dbconnectionstringbuilder.shouldserialize?view=net-9.0

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Data.Common/DbConnectionStringBuilder.xml

Document Version Independent Id

ff1c22c0-fe31-1d68-eb45-9305d6725db7

Article author

@dotnet-bot

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-runtime