CA1305: Zadejte možnosti IFormatProvider
Vlastnost | Hodnota |
---|---|
ID pravidla | CA1305 |
Název | Určete IFormatProvider |
Kategorie | Globalizace |
Oprava způsobující chybu nebo chybu způsobující chybu | Nenarušující |
Povoleno ve výchozím nastavení v .NET 9 | No |
Příčina
Volání metody, která má přetížení, které přijímá System.IFormatProvider argument, a toto přetížení není volána.
Toto pravidlo ignoruje volání metod .NET, které jsou zdokumentované jako ignorování parametru IFormatProvider . Pravidlo také ignoruje následující metody:
- Activator.CreateInstance
- ResourceManager.GetObject
- ResourceManager.GetString
- Boolean.ToString
- Char.ToString
- Guid.ToString
Popis pravidla
System.Globalization.CultureInfo Pokud není zadán objekt nebo IFormatProvider objekt, výchozí hodnota zadaná přetíženým členem nemusí mít vliv, který chcete mít ve všech národních prostředích. Členové .NET také volí výchozí jazykovou verzi a formátování na základě předpokladů, které nemusí být pro váš kód správné. Abyste měli jistotu, že kód funguje podle očekávání pro vaše scénáře, měli byste zadat informace specifické pro jazykovou verzi podle následujících pokynů:
Pokud se uživateli zobrazí hodnota, použijte aktuální jazykovou verzi. Viz třída CultureInfo.CurrentCulture.
Pokud bude hodnota uložená a přístupná softwarem (trvale uložená v souboru nebo databázi), použijte neutrální jazykovou verzi. Viz třída CultureInfo.InvariantCulture.
Pokud neznáte cíl hodnoty, zadejte jazykovou verzi příjemce dat nebo zprostředkovatele.
I když je výchozí chování přetíženého členu vhodné pro vaše potřeby, je lepší explicitně volat přetížení specifické pro jazykovou verzi, aby váš kód byl samodokumentován a snadněji udržován.
Jak opravit porušení
Chcete-li opravit porušení tohoto pravidla, použijte přetížení, které přebírá IFormatProvider argument. Nebo pokud chcete použít invariantní jazykovou verzi, použijte interpolovaný řetězec jazyka C# a předejte ho String.Create(IFormatProvider, DefaultInterpolatedStringHandler) spolu s CultureInfo.InvariantCulturenimi, například:
string.Create(CultureInfo.InvariantCulture, $"{major}.{minor}.{build}.{revision}");
Kdy potlačit upozornění
Je bezpečné potlačit upozornění z tohoto pravidla, pokud je jisté, že výchozí formát je správnou volbou a kde udržovatelnost kódu není důležitou prioritou vývoje.
Potlačení upozornění
Pokud chcete pouze potlačit jedno porušení, přidejte do zdrojového souboru direktivy preprocesoru, abyste pravidlo zakázali a znovu povolili.
#pragma warning disable CA1305
// The code that's violating the rule is on this line.
#pragma warning restore CA1305
Pokud chcete pravidlo pro soubor, složku nebo projekt zakázat, nastavte jeho závažnost v none
konfiguračním souboru.
[*.{cs,vb}]
dotnet_diagnostic.CA1305.severity = none
Další informace naleznete v tématu Jak potlačit upozornění analýzy kódu.
Konfigurace kódu pro analýzu
Pomocí následujících možností můžete nakonfigurovat, pro které části základu kódu se má toto pravidlo spouštět.
Tyto možnosti můžete nakonfigurovat jenom pro toto pravidlo, pro všechna pravidla, která platí, nebo pro všechna pravidla v této kategorii (globalizace), na která platí. Další informace naleznete v tématu Možnosti konfigurace pravidla kvality kódu.
Vyloučení konkrétních symbolů
Z analýzy můžete vyloučit konkrétní symboly, jako jsou typy a metody. Pokud chcete například určit, že pravidlo by se nemělo spouštět u žádného kódu v rámci pojmenovaných MyType
typů, přidejte do souboru .editorconfig v projektu následující dvojici klíč-hodnota:
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType
Povolené formáty názvů symbolů v hodnotě možnosti (oddělené ):|
- Pouze název symbolu (zahrnuje všechny symboly s názvem bez ohledu na typ nebo obor názvů).
- Plně kvalifikované názvy ve formátu ID dokumentace symbolu. Každý název symbolu vyžaduje předponu typu symbolu, například
M:
pro metody,T:
typy aN:
obory názvů. .ctor
pro konstruktory a.cctor
statické konstruktory.
Příklady:
Hodnota možnosti | Shrnutí |
---|---|
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType |
Odpovídá všem symbolům s názvem MyType . |
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2 |
Porovná všechny symboly pojmenované buď MyType1 nebo MyType2 . |
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType) |
Odpovídá konkrétní metodě MyMethod se zadaným plně kvalifikovaným podpisem. |
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType) |
Odpovídá konkrétním metodám MyMethod1 a MyMethod2 příslušným plně kvalifikovaným podpisům. |
Vyloučení konkrétních typů a jejich odvozených typů
Z analýzy můžete vyloučit konkrétní typy a jejich odvozené typy. Pokud chcete například určit, že pravidlo by se nemělo spouštět u žádné metody v rámci pojmenovaných MyType
typů a jejich odvozených typů, přidejte do souboru .editorconfig v projektu následující dvojici klíč-hodnota:
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType
Povolené formáty názvů symbolů v hodnotě možnosti (oddělené ):|
- Pouze název typu (zahrnuje všechny typy s názvem bez ohledu na typ nebo obor názvů).
- Plně kvalifikované názvy ve formátu ID dokumentace symbolu s volitelnou
T:
předponou.
Příklady:
Hodnota možnosti | Shrnutí |
---|---|
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType |
Odpovídá všem pojmenovaným MyType typům a všem jejich odvozeným typům. |
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2 |
Odpovídá všem typům pojmenovaným buď MyType1 nebo MyType2 a všem jejich odvozeným typům. |
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType |
Odpovídá určitému typu MyType s daným plně kvalifikovaným názvem a všemi jeho odvozenými typy. |
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2 |
Odpovídá konkrétním typům MyType1 a MyType2 příslušným plně kvalifikovaným názvům a všem jejich odvozeným typům. |
Příklad
V následujícím kódu example1
řetězec porušuje pravidlo CA1305. Řetězec example2
splňuje pravidlo CA1305 předáním CultureInfo.CurrentCulture, který implementuje IFormatProvider, do String.Format(IFormatProvider, String, Object). Řetězec example3
splňuje pravidlo CA1305 předáním interpolovaného řetězce spolu String.Create(IFormatProvider, DefaultInterpolatedStringHandler) s CultureInfo.InvariantCulture.
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 = string.Create(CultureInfo.InvariantCulture, $"Hello {name}");