CA1303: Geen letterlijke waarden doorgeven als gelokaliseerde parameters

Artikel
01/16/2025

Eigenschappen	Weergegeven als
Regel-id	CA1303
Titel	Letterlijke waarden niet doorgeven als gelokaliseerde parameters
Categorie	Globalisatie
Oplossing is brekend of niet-brekend	Niet-brekend
Standaard ingeschakeld in .NET 9	Nee

Oorzaak

Een methode geeft een letterlijke tekenreeks als parameter door aan een .NET-constructor of -methode en die tekenreeks moet kunnen worden gelokaliseerd.

Deze waarschuwing wordt gegenereerd wanneer een letterlijke tekenreeks wordt doorgegeven als een waarde aan een parameter of eigenschap en een of meer van de volgende situaties waar is:

Het LocalizableAttribute kenmerk van de parameter of eigenschap is ingesteld op true.
De letterlijke tekenreeks wordt doorgegeven aan de string value of string format parameter van een Console.Write of Console.WriteLine methode-overbelasting.
Regel CA1303 is geconfigureerd voor het gebruik van de heuristiek van de naamgeving en een parameter of eigenschapsnaam bevat de woordgroep Text, Messageof Caption.

Deze regel analyseert standaard de hele codebasis, maar dit kan worden geconfigureerd.

Beschrijving van regel

Letterlijke tekenreeksen die zijn ingesloten in broncode, zijn moeilijk te lokaliseren.

Schendingen oplossen

Als u een schending van deze regel wilt oplossen, vervangt u de letterlijke tekenreeks door een tekenreeks die is opgehaald via een exemplaar van de ResourceManager klasse.

Voor methoden waarvoor geen gelokaliseerde tekenreeksen zijn vereist, kunt u onnodige CA1303-waarschuwingen op de volgende manieren elimineren:

Als de naamgevingsoptie heuristiek is ingeschakeld, wijzigt u de naam van de parameter of eigenschap.
Verwijder het LocalizableAttribute kenmerk van de parameter of eigenschap of stel het in op false ([Localizable(false)]).

Wanneer waarschuwingen onderdrukken

Het is veilig om een waarschuwing van deze regel te onderdrukken als een van de volgende instructies van toepassing is:

De codebibliotheek wordt niet gelokaliseerd.
De tekenreeks wordt niet beschikbaar gemaakt voor de eindgebruiker of een ontwikkelaar die de codebibliotheek gebruikt.

Een waarschuwing onderdrukken

Als u slechts één schending wilt onderdrukken, voegt u preprocessorrichtlijnen toe aan uw bronbestand om de regel uit te schakelen en vervolgens opnieuw in te schakelen.

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

Als u de regel voor een bestand, map of project wilt uitschakelen, stelt u de ernst none ervan in op het configuratiebestand.

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

Zie Codeanalysewaarschuwingen onderdrukken voor meer informatie.

Code configureren om te analyseren

Gebruik de volgende opties om te configureren op welke onderdelen van uw codebase deze regel moet worden uitgevoerd.

Specifieke symbolen uitsluiten
Specifieke typen en hun afgeleide typen uitsluiten
Heuristiek voor naamgeving gebruiken

U kunt deze opties configureren voor alleen deze regel, voor alle regels waarop deze van toepassing is, of voor alle regels in deze categorie (Globalization) waarop deze van toepassing is. Zie de configuratieopties voor de codekwaliteitsregel voor meer informatie.

Specifieke symbolen uitsluiten

U kunt specifieke symbolen, zoals typen en methoden, uitsluiten van analyse. Als u bijvoorbeeld wilt opgeven dat de regel niet mag worden uitgevoerd op code binnen benoemde MyTypetypen, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Notitie

Vervang het XXXX deel van CAXXXX door de id van de toepasselijke regel.

Toegestane notaties voor symboolnamen in de optiewaarde (gescheiden door |):

Alleen symboolnaam (inclusief alle symbolen met de naam, ongeacht het type of de naamruimte).
Volledig gekwalificeerde namen in de documentatie-id-indeling van het symbool. Voor elke symboolnaam is een voorvoegsel van het type symbool vereist, zoals M: voor methoden, T: voor typen en N: voor naamruimten.
.ctor voor constructors en .cctor voor statische constructors.

Voorbeelden:

Optiewaarde	Samenvatting
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType`	Komt overeen met alle symbolen met de naam `MyType`.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1\|MyType2`	Komt overeen met alle symbolen met de naam of `MyType1MyType2`.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)`	Komt overeen met een specifieke methode `MyMethod` met de opgegeven volledig gekwalificeerde handtekening.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)\|M:NS2.MyType2.MyMethod2(ParamType)`	Komt overeen met specifieke methoden `MyMethod1` en `MyMethod2` met de respectieve volledig gekwalificeerde handtekeningen.

Specifieke typen en hun afgeleide typen uitsluiten

U kunt specifieke typen en hun afgeleide typen uitsluiten van analyse. Als u bijvoorbeeld wilt opgeven dat de regel niet mag worden uitgevoerd op methoden binnen benoemde MyType typen en de afgeleide typen, voegt u het volgende sleutel-waardepaar toe aan een .editorconfig-bestand in uw project:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Notitie

Vervang het XXXX deel van CAXXXX door de id van de toepasselijke regel.

Toegestane notaties voor symboolnamen in de optiewaarde (gescheiden door |):

Alleen de naam van het type (bevat alle typen met de naam, ongeacht het type of de naamruimte).
Volledig gekwalificeerde namen in de documentatie-id-indeling van het symbool, met een optioneel T: voorvoegsel.

Voorbeelden:

Optiewaarde	Samenvatting
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType`	Komt overeen met alle typen met de naam `MyType` en alle afgeleide typen.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1\|MyType2`	Komt overeen met alle typen met de naam `MyType1` of `MyType2` en alle afgeleide typen.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType`	Komt overeen met een specifiek type `MyType` met een volledig gekwalificeerde naam en alle afgeleide typen.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1\|M:NS2.MyType2`	Komt overeen met specifieke typen `MyType1` en `MyType2` met de respectieve volledig gekwalificeerde namen en alle afgeleide typen.

Heuristiek voor naamgeving gebruiken

U kunt configureren of parameters of eigenschapsnamen die deze regel bevatten Text, Messageof Caption deze regel activeren.

dotnet_code_quality.CA1303.use_naming_heuristic = true

Opmerking

In het volgende voorbeeld ziet u een methode die naar de console schrijft wanneer een van de twee argumenten buiten het bereik ligt. Voor de hour argumentcontrole wordt een letterlijke tekenreeks doorgegeven aan Console.WriteLine, die deze regel schendt. Voor de minute argumentcontrole wordt een tekenreeks die wordt opgehaald via een ResourceManager tekenreeks doorgegeven aan Console.WriteLine, die voldoet aan de regel.

<Assembly: System.Resources.NeutralResourcesLanguageAttribute("en-US")>
Namespace GlobalizationLibrary

    Public Class DoNotPassLiterals

        Dim stringManager As System.Resources.ResourceManager

        Sub New()
            stringManager = New System.Resources.ResourceManager(
                "en-US", System.Reflection.Assembly.GetExecutingAssembly())
        End Sub

        Sub TimeMethod(hour As Integer, minute As Integer)

            If (hour < 0 Or hour > 23) Then
                'CA1303 fires because a literal string
                'is passed as the 'value' parameter.
                Console.WriteLine("The valid range is 0 - 23.")
            End If

            If (minute < 0 Or minute > 59) Then
                Console.WriteLine(
                    stringManager.GetString("minuteOutOfRangeMessage",
                        System.Globalization.CultureInfo.CurrentUICulture))
            End If

        End Sub

    End Class

End Namespace

public class DoNotPassLiterals
{
    ResourceManager stringManager;
    public DoNotPassLiterals()
    {
        stringManager = new ResourceManager("en-US", Assembly.GetExecutingAssembly());
    }

    public void TimeMethod(int hour, int minute)
    {
        if (hour < 0 || hour > 23)
        {
            // CA1303 fires because a literal string
            // is passed as the 'value' parameter.
            Console.WriteLine("The valid range is 0 - 23.");
        }

        if (minute < 0 || minute > 59)
        {
            Console.WriteLine(stringManager.GetString(
            "minuteOutOfRangeMessage", CultureInfo.CurrentUICulture));
        }
    }
}

Delen via