CA1305: Specify IFormatProvider

Value
Rule ID CA1305
Category Globalization
Fix is breaking or non-breaking Non-breaking

Cause

A call is made to a method that has an overload that accepts a System.IFormatProvider parameter, and that overload isn't called.

This rule ignores calls to .NET methods that are documented as ignoring the IFormatProvider parameter. The rule also ignores the following methods:

Rule description

When a System.Globalization.CultureInfo or IFormatProvider object is not supplied, the default value that is supplied by the overloaded member might not have the effect that you want in all locales. Also, .NET members choose default culture and formatting based on assumptions that might not be correct for your code. To make sure that the code works as expected for your scenarios, you should supply culture-specific information according to the following guidelines:

  • If the value will be displayed to the user, use the current culture. See CultureInfo.CurrentCulture.

  • If the value will be stored and accessed by software (persisted to a file or database), use the invariant culture. See CultureInfo.InvariantCulture.

  • If you do not know the destination of the value, have the data consumer or provider specify the culture.

Even if the default behavior of the overloaded member is appropriate for your needs, it is better to explicitly call the culture-specific overload so that your code is self-documenting and more easily maintained.

How to fix violations

To fix a violation of this rule, use the overload that takes an IFormatProvider argument. Or, use a C# interpolated string and pass it to the FormattableString.Invariant method.

When to suppress warnings

It is safe to suppress a warning from this rule when it is certain that the default format is the correct choice, and where code maintainability is not an important development priority.

Suppress a warning

If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.

#pragma warning disable CA1305
// The code that's violating the rule is on this line.
#pragma warning restore CA1305

To disable the rule for a file, folder, or project, set its severity to none in the configuration file.

[*.{cs,vb}]
dotnet_diagnostic.CA1305.severity = none

To disable this entire category of rules, set the severity for the category to none in the configuration file.

[*.{cs,vb}]
dotnet_analyzer_diagnostic.category-Globalization.severity = none

For more information, see How to suppress code analysis warnings.

Example

In the following code, the example1 string violates rule CA1305. The example2 string satisfies rule CA1305 by passing CultureInfo.CurrentCulture, which implements IFormatProvider, to String.Format(IFormatProvider, String, Object). The example3 string satisfies rule CA1305 by passing an interpolated string to Invariant.

string name = "Georgette";

// Violates CA1305
string example1 = String.Format("Hello {0}", name);

// Satisfies CA1305
string example2 = String.Format(CultureInfo.CurrentCulture, "Hello {0}", name);

// Satisfies CA1305
string example3 = FormattableString.Invariant($"Hello {name}");

See also