CA1303: Nie należy przekazywać literałów jako parametrów zlokalizowanych

Artykuł
09/06/2023

Właściwości	Wartość
Identyfikator reguły	CA1303
Tytuł	Nie przekazuj literałów jako zlokalizowanych parametrów
Kategoria	Globalizacja
Poprawka powodująca niezgodność lub niezgodność	Niezgodność
Domyślnie włączone na platformie .NET 9	Nie.

Przyczyna

Metoda przekazuje literał ciągu jako parametr do konstruktora lub metody .NET i ten ciąg powinien być lokalizowalny.

To ostrzeżenie jest zgłaszane, gdy ciąg literału jest przekazywany jako wartość do parametru lub właściwości, a co najmniej jedna z następujących sytuacji ma wartość true:

Atrybut LocalizableAttribute parametru lub właściwości jest ustawiony na truewartość .
Ciąg literału jest przekazywany do parametru string value Console.Write lub string format przeciążenia metody lubConsole.WriteLine.
Reguła CA1303 jest skonfigurowana do używania heurystyki nazewnictwa, a parametr lub nazwa właściwości zawiera frazę Text, Messagelub Caption.

Domyślnie ta reguła analizuje całą bazę kodu, ale można to skonfigurować.

Opis reguły

Literały ciągu osadzone w kodzie źródłowym są trudne do zlokalizowania.

Jak naprawić naruszenia

Aby naprawić naruszenie tej reguły, zastąp literał ciągu ciągiem pobranym za pomocą wystąpienia ResourceManager klasy.

W przypadku metod, które nie wymagają zlokalizowanych ciągów, można wyeliminować niepotrzebne ostrzeżenia CA1303 w następujący sposób:

Jeśli opcja heurystyczna nazewnictwa jest włączona, zmień nazwę parametru lub właściwości.
LocalizableAttribute Usuń atrybut parametru lub właściwości albo ustaw go na false ([Localizable(false)]).

Kiedy pomijać ostrzeżenia

Można bezpiecznie pominąć ostrzeżenie z tej reguły, jeśli ma zastosowanie którakolwiek z następujących instrukcji:

Biblioteka kodu nie zostanie zlokalizowana.
Ciąg nie jest udostępniany użytkownikowi końcowemu ani deweloperowi przy użyciu biblioteki kodu.

Pomijanie ostrzeżenia

Jeśli chcesz po prostu pominąć pojedyncze naruszenie, dodaj dyrektywy preprocesora do pliku źródłowego, aby wyłączyć, a następnie ponownie włączyć regułę.

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

Aby wyłączyć regułę dla pliku, folderu lub projektu, ustaw jego ważność na none w pliku konfiguracji.

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

Aby uzyskać więcej informacji, zobacz Jak pominąć ostrzeżenia dotyczące analizy kodu.

Konfigurowanie kodu do analizowania

Użyj poniższych opcji, aby skonfigurować, które części bazy kodu mają być uruchamiane w tej regule.

Wykluczanie określonych symboli
Wykluczanie określonych typów i ich typów pochodnych
Używanie heurystyki nazewnictwa

Możesz skonfigurować te opcje tylko dla tej reguły, dla wszystkich reguł, których dotyczy, lub dla wszystkich reguł w tej kategorii (globalizacja), których dotyczy. Aby uzyskać więcej informacji, zobacz Opcje konfiguracji reguły jakości kodu.

Wykluczanie określonych symboli

Z analizy można wykluczyć określone symbole, takie jak typy i metody. Aby na przykład określić, że reguła nie powinna być uruchamiana w żadnym kodzie w typach o nazwie MyType, dodaj następującą parę klucz-wartość do pliku editorconfig w projekcie:

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

Dozwolone formaty nazw symboli w wartości opcji (oddzielone przez |):

Tylko nazwa symbolu (zawiera wszystkie symbole o nazwie, niezależnie od typu zawierającego lub przestrzeni nazw).
W pełni kwalifikowane nazwy w formacie identyfikatora dokumentacji symbolu. Każda nazwa symboli wymaga prefiksu typu symboli, takiego jak M: metody, T: dla typów i N: przestrzeni nazw.
.ctor dla konstruktorów i .cctor konstruktorów statycznych.

Przykłady:

Wartość opcji	Podsumowanie
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType`	Pasuje do wszystkich symboli o nazwie `MyType`.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1\|MyType2`	Pasuje do wszystkich symboli o nazwie `MyType1` lub `MyType2`.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)`	Pasuje do określonej metody `MyMethod` z określonym w pełni kwalifikowanym podpisem.
`dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)\|M:NS2.MyType2.MyMethod2(ParamType)`	Pasuje do określonych metod `MyMethod1` i `MyMethod2` z odpowiednimi w pełni kwalifikowanymi podpisami.

Wykluczanie określonych typów i ich typów pochodnych

Z analizy można wykluczyć określone typy i ich typy pochodne. Aby na przykład określić, że reguła nie powinna być uruchamiana na żadnych metodach w typach nazwanych MyType i ich typach pochodnych, dodaj następującą parę klucz-wartość do pliku .editorconfig w projekcie:

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

Dozwolone formaty nazw symboli w wartości opcji (oddzielone przez |):

Nazwa typu (zawiera tylko wszystkie typy o nazwie, niezależnie od typu zawierającego lub przestrzeni nazw).
W pełni kwalifikowane nazwy w formacie identyfikatora dokumentacji symbolu z opcjonalnym T: prefiksem.

Przykłady:

Wartość opcji	Podsumowanie
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType`	Pasuje do wszystkich typów nazwanych `MyType` i wszystkich ich typów pochodnych.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1\|MyType2`	Dopasuje wszystkie typy o nazwie `MyType1` lub `MyType2` i wszystkie ich typy pochodne.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType`	Pasuje do określonego typu `MyType` z daną w pełni kwalifikowaną nazwą i wszystkimi jego typami pochodnymi.
`dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1\|M:NS2.MyType2`	Pasuje do określonych typów `MyType1` i `MyType2` z odpowiednimi w pełni kwalifikowanymi nazwami i wszystkimi ich typami pochodnymi.

Używanie heurystyki nazewnictwa

Możesz skonfigurować, czy parametry lub nazwy właściwości zawierające TextMessage, lub Caption wyzwolą tę regułę.

dotnet_code_quality.CA1303.use_naming_heuristic = true

Przykład

W poniższym przykładzie pokazano metodę zapisującą w konsoli, gdy jeden z dwóch argumentów jest poza zakresem. W przypadku sprawdzania argumentów hour ciąg literału jest przekazywany do Console.WriteLineelementu , co narusza tę regułę. W przypadku sprawdzania minute argumentów ciąg pobrany za pośrednictwem elementu ResourceManager jest przekazywany do Console.WriteLineelementu , który spełnia regułę.

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

Udostępnij za pośrednictwem