CA1303 : Ne pas passer de littéraux en paramètres localisés

Cause

Une méthode passe un littéral de chaîne en tant que paramètre à un constructeur .NET ou une méthode et cette chaîne doit être localisable.

Cet avertissement est déclenché lorsqu’une chaîne littérale est passée en tant que valeur à un paramètre ou une propriété et qu’une ou plusieurs des situations suivantes sont vraies :

• L’attribut LocalizableAttribute du paramètre ou de la propriété a la valeur true.

• La chaîne littérale est passée au paramètre string value ou string format d’une surcharge de méthode Console.Write ou Console.WriteLine.

• La règle CA1303 est configurée pour utiliser l’heuristique de nommage, et un paramètre ou un nom de propriété contient l’expression Text, Message ou Caption.

Par défaut, cette règle analyse l’intégralité du codebase, mais elle est configurable.

Description de la règle

Les littéraux de chaîne incorporés dans le code source sont difficiles à localiser.

Comment corriger les violations

Pour corriger une violation de cette règle, remplacez le littéral de chaîne par une chaîne récupérée via une instance de la classe ResourceManager.

Pour les méthodes qui ne nécessitent pas de chaînes localisées, vous pouvez éliminer les avertissements CA1303 inutiles des manières suivantes :

• Si l’option heuristique de nommage est activée, renommez le paramètre ou la propriété.
• Supprimez l’attribut LocalizableAttribute sur le paramètre ou la propriété, ou définissez-le sur false ([Localizable(false)]).

Quand supprimer les avertissements

Il est prudent de supprimer un avertissement de cette règle si l’une des conditions suivantes s’applique :

• La bibliothèque de code ne sera pas localisée.
• La chaîne n’est pas exposée à l’utilisateur final ou à un développeur utilisant la bibliothèque de code.

Supprimer un avertissement

Si vous voulez supprimer une seule violation, ajoutez des directives de préprocesseur à votre fichier source pour désactiver et réactiver la règle.

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

Pour désactiver la règle sur un fichier, un dossier ou un projet, définissez sa gravité sur none dans le fichier de configuration.

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

Pour plus d’informations, consultez Comment supprimer les avertissements de l’analyse de code.

Configurer le code à analyser

Utilisez l’option suivante pour configurer les parties de votre codebase sur lesquelles exécuter cette règle.

• Exclure des symboles spécifiques
• Exclure des types spécifiques et leurs types dérivés
• Utiliser l’heuristique de nommage

Vous pouvez configurer ces options pour cette règle uniquement, pour toutes les règles auxquelles elles s’appliquent ou pour toutes les règles de cette catégorie (Globalisation) auxquelles elles s’appliquent. Pour plus d’informations, consultez Options de configuration des règles de qualité du code.

Exclure des symboles spécifiques

Vous pouvez exclure de l’analyse des symboles spécifiques, comme des types et des méthodes. Par exemple, pour spécifier que la règle ne doit pas s’exécuter sur du code dans des types nommés MyType, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Formats de nom de symbole autorisés dans la valeur d’option (séparés par |) :

• Nom du symbole uniquement (inclut tous les symboles avec le nom, quel que soit le type ou l’espace de noms qui les contient).
• Noms qualifiés complets au format d’ID de documentation du symbole. Chaque nom de symbole nécessite un préfixe de type symbole, comme M: pour les méthodes, T: pour les types et N: pour les espaces de noms.
• .ctor pour les constructeurs et .cctor pour les constructeurs statiques.

Exemples :

Exclure des types spécifiques et leurs types dérivés

Vous pouvez exclure de l’analyse des types spécifiques et leurs types dérivés. Par exemple, pour spécifier que la règle ne doit s’exécuter sur aucune méthode dans des types nommés MyType et leurs types dérivés, ajoutez la paire clé-valeur suivante à un fichier .editorconfig dans votre projet :

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Formats de nom de symbole autorisés dans la valeur d’option (séparés par |) :

• Nom du type uniquement (inclut tous les types avec le nom, quel que soit le type ou l’espace de noms qui les contient).
• Noms qualifiés complets au format d’ID de documentation du symbole, avec un préfixe T: facultatif.

Exemples :

Utiliser l’heuristique de nommage

Vous pouvez configurer si les paramètres ou les noms de propriétés contenant Text, Message ou Caption déclenchent cette règle.

dotnet_code_quality.CA1303.use_naming_heuristic = true

Exemple

L’exemple suivant montre une méthode qui écrit dans la console lorsque l’un de ses deux arguments est hors de portée. Pour la vérification d’argument hour, une chaîne littérale est passée à Console.WriteLine, ce qui enfreint cette règle. Pour la vérification d’argument minute, une chaîne récupérée par le biais d’un ResourceManager est passée à Console.WriteLine, ce qui satisfait à la règle.

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

Voir aussi

• Ressources dans les applications .NET
• Demande de changement de comportement de la communauté