CA1303: Literale nicht als lokalisierte Parameter übergeben.

Eigenschaft	Wert
Regel-ID	CA1303
Titel	Literale nicht als lokalisierte Parameter übergeben.
Kategorie	Globalisierung
Fix führt zu Unterbrechungen oder bleibt funktionsfähig	Untrennbar
Standardmäßig in .NET 10 aktiviert	Nein
Anwendbare Sprachen	C# und Visual Basic

Ursache

Eine Methode übergibt ein Zeichenfolgenliteral als Parameter an einen .NET-Konstruktor oder eine Methode, und diese Zeichenfolge sollte lokalisierbar sein.

Diese Warnung wird ausgelöst, wenn eine Literalzeichenfolge als Wert an einen Parameter oder an eine Eigenschaft übergeben wird und mindestens eine der folgenden Situationen zutrifft:

• Das LocalizableAttribute-Attribut des Parameters oder der Eigenschaft ist auf true festgelegt.

• Die Literalzeichenfolge wird an den Parameter string value oder string format einer Methodenüberladung von Console.Write oder Console.WriteLine übergeben.

• Die Regel CA1303 ist für die Verwendung der Benennungsheuristik konfiguriert, und ein Parameter- oder Eigenschaftsname enthält den Ausdruck Text, Message oder Caption.

Standardmäßig analysiert diese Regel die gesamte Codebasis, aber dieses Verhalten ist konfigurierbar.

Regelbeschreibung

Zeichenfolgenliterale, welche in Quellcode eingebettet sind, sind schwer zu lokalisieren.

So beheben Sie Verstöße

Um einen Verstoß gegen diese Regel zu beheben, ersetzen Sie das Zeichenfolgenliteral durch eine durch eine Instanz der ResourceManager-Klasse abgerufene Zeichenfolge.

Für Methoden, die keine lokalisierten Zeichenfolgen erfordern, können Sie unnötige CA1303-Warnungen auf folgende Weise eliminieren:

• Wenn die Benennungsheuristik-Option aktiviert ist, benennen Sie den Parameter oder die Eigenschaft um.
• Entfernen Sie das LocalizableAttribute-Attribut für den Parameter oder die Eigenschaft, oder legen Sie es auf false ([Localizable(false)]) fest.

Wann sollten Warnungen unterdrückt werden?

Es ist sicher, eine Warnung aus dieser Regel zu unterdrücken, wenn eine der folgenden Aussagen zutrifft:

• Die Code-Bibliothek wird nicht lokalisiert.
• Die Zeichenfolge wird für den Endbenutzer oder einen Entwickler, der die Code-Bibliothek verwendet, nicht verfügbar gemacht.

Unterdrücken einer Warnung

Um nur eine einzelne Verletzung zu unterdrücken, fügen Sie der Quelldatei Präprozessoranweisungen hinzu, um die Regel zu deaktivieren und dann wieder zu aktivieren.

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

Um die Regel für eine Datei, einen Ordner oder ein Projekt zu deaktivieren, legen Sie den Schweregrad auf none in der Konfigurationsdatei fest.

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

Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken von Codeanalyse-Warnungen.

Konfigurieren des zu analysierenden Codes

Mithilfe der folgenden Optionen können Sie konfigurieren, für welche Teile Ihrer Codebasis diese Regel ausgeführt werden soll.

• Ausschließen bestimmter Symbole
• Ausschließen bestimmter Typen und von diesen abgeleiteten Typen
• Verwenden der Benennungsheuristik

Darüber hinaus gelten für diese Regel die folgenden Optionen für Datenflussanalysen:

• interprocedural_analysis_kind
• max_interprocedural_lambda_or_local_function_call_chain
• max_interprocedural_method_call_chain
• points_to_analysis_kind
• copy_analysis
• sufficient_IterationCount_for_weak_KDF_algorithm

Sie können diese Optionen nur für diese Regel, für alle Regeln, für die sie gelten, oder für alle Regeln in dieser Kategorie (Globalisierung), für die sie gelten, konfigurieren. Weitere Informationen finden Sie unter Konfigurationsoptionen für die Codequalitätsregel.

Ausschließen bestimmter Symbole

Sie können bestimmte Symbole, wie z. B. Typen und Methoden, von der Analyse ausschließen, indem Sie die Option excluded_symbol_names festlegen. Sie können beispielsweise festlegen, dass die Regel nicht für Code innerhalb von Typen namens MyType ausgeführt werden soll, indem Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzufügen:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Hinweis

Ersetzen Sie das XXXX-Element von CAXXXX durch die ID der entsprechenden Regel.

Zulässige Formate für Symbolnamen im Optionswert (durch | getrennt):

• Nur Symbolname (schließt alle Symbole mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace)
• Vollqualifizierte Namen im Dokumentations-ID-Format der Symbole. Jeder Symbolname erfordert ein Symbolartpräfix, z. B. M: für Methoden, T: für Typen und N: für Namespaces.
• .ctor für Konstruktoren und .cctor für statische Konstruktoren

Beispiele:

Optionswert	Zusammenfassung
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType	Trifft auf alle Symbole namens MyType zu
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2	Trifft auf alle Symbole namens MyType1 oder MyType2 zu
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)	Entspricht der speziellen Methode MyMethod mit der angegebenen vollqualifizierten Signatur.
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType)	Ordnet die spezifischen Methoden MyMethod1 und MyMethod2 ihren jeweiligen vollqualifizierten Signaturen zu.

Ausschließen bestimmter Typen und von diesen abgeleiteten Typen

Sie können bestimmte Typen und ihre abgeleiteten Typen von der Analyse ausschließen, indem Sie die Option excluded_type_names_with_derived_types festlegen. Wenn Sie z. B. festlegen möchten, dass die Regel nicht für Methoden innerhalb von MyType-Typen und von diesen abgeleiteten Typen ausgeführt werden soll, fügen Sie einer EDITORCONFIG-Datei in Ihrem Projekt das folgende Schlüssel-Wert-Paar hinzu:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Hinweis

Ersetzen Sie das XXXX-Element von CAXXXX durch die ID der entsprechenden Regel.

Zulässige Formate für Symbolnamen im Optionswert (durch | getrennt):

• Nur Typname (schließt alle Typen mit dem Namen ein, unabhängig vom enthaltenden Typ oder Namespace)
• Vollqualifizierte Namen im Dokumentations-ID-Format des Symbols mit einem optionalen Präfix T:

Beispiele:

Optionswert	Zusammenfassung
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType	Stimmt mit allen MyType-Typen und allen von diesen abgeleiteten Typen überein.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2	Stimmt mit allen MyType1- oder MyType2-Typen und allen von diesen abgeleiteten Typen überein.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType	Stimmt mit einem bestimmten Typ MyType überein, der anhand eines angegebenen vollqualifizierten Namens und aller von ihm abgeleiteten Typen identifiziert wird.
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2	Bestimmte MyType1- und MyType2-Typen werden mit ihren entsprechenden vollqualifizierten Namen und allen abgeleiteten Typen abgeglichen.

Verwenden der Benennungsheuristik

Sie können konfigurieren, ob Parameter- oder Eigenschaftsnamen, die Text, Message, oder Caption enthalten, diese Regel auslösen.

dotnet_code_quality.CA1303.use_naming_heuristic = true

Beispiel

Das folgende Beispiel zeigt eine Methode, welche in die Konsole schreibt, wenn eines der beiden Argumente außerhalb des gültigen Bereichs liegt. Bei der Überprüfung des hour-Arguments wird eine Literalzeichenfolge an Console.WriteLine übermittelt, was gegen diese Regel verstößt. Bei der Argumentprüfung des minute wird eine durch ResourceManager abgerufene Zeichenfolge zu Console.WriteLine übergeben, wodurch die Regel erfüllt wird.

<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));
        }
    }
}

Siehe auch

• Ressourcen in .NET-Apps
• Community-Anforderung für Verhaltensänderung