CA1303:ローカライズされるパラメーターとしてリテラルを渡さない

プロパティ	値
ルール ID	CA1303
Title	ローカライズされるパラメーターとしてリテラルを渡さない
[カテゴリ]	グローバリゼーション
修正が中断ありか中断なしか	なし
.NET 9 では既定で有効	いいえ

原因

メソッドで .NET コンストラクターまたはメソッドへのパラメーターとして、リテラル文字列を渡しています。その文字列はローカライズ可能です。

この警告は、リテラル文字列が値としてパラメーターまたはプロパティに渡され、次の 1 つ以上の状況に該当する場合に発生します。

• パラメーターまたはプロパティの LocalizableAttribute 属性が true に設定されています。

• リテラル文字列は、string value または string format メソッド オーバーロードの Console.Write または Console.WriteLine パラメーターに渡されます。

• 規則 CA1303 は名前付けヒューリスティックを使用するように構成されており、パラメーターまたはプロパティ名には Text、Message、または Caption という語句が含まれています。

既定で、このルールではコードベース全体を分析しますが、これは構成可能です。

規則の説明

ソース コードに埋め込まれている文字列リテラルをローカライズするのは困難です。

違反の修正方法

この規則違反を修正するには、文字列リテラルを ResourceManager クラスのインスタンスを介して取得される文字列に置き換えます。

ローカライズされた文字列を必要としないメソッドでは、次の方法で不要な CA1303 警告を除去できます。

• 名前付けヒューリスティック オプションが有効になっている場合は、パラメーターまたはプロパティの名前を変更します。
• パラメーターまたはプロパティの LocalizableAttribute 属性を削除するか、またはそれを false ([Localizable(false)]) に設定します。

どのようなときに警告を抑制するか

次のいずれかのステートメントが適用される場合は、この規則による警告を抑制しても問題ありません。

• コード ライブラリはローカライズされません。
• この文字列は、コード ライブラリを使用してエンド ユーザーまたは開発者に公開されることはありません。

警告を抑制する

単一の違反を抑制するだけの場合は、ソース ファイルにプリプロセッサ ディレクティブを追加して無効にしてから、規則をもう一度有効にします。

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

ファイル、フォルダー、またはプロジェクトの規則を無効にするには、noneでその重要度を に設定します。

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

詳細については、「コード分析の警告を抑制する方法」を参照してください。

分析するコードを構成する

次のオプションを使用して、コードベースのどの部分に対してこのルールを実行するかを構成します。

• 特定のシンボルを除外する
• 特定の型とその派生型を除外する
• 名前付けヒューリスティックを使用する

さらに、このルールには、次のデータフロー分析関連のオプションが適用されます。

• 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

これらのオプションは、このルールのみ、適用されるすべてのルール、または適用先のこのカテゴリ (グローバリゼーション) のすべてのルールに対して構成できます。 詳細については、「コード品質規則の構成オプション」を参照してください。

特定のシンボルを除外する

excluded_symbol_names オプションを設定することで、種類やメソッドなどの特定のシンボルを分析から除外できます。 たとえば、MyType という名前の型のコードで規則を実行しないように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

メモ

CAXXXX の XXXX 部分を該当するルールの ID に置き換えます。

オプションの値で使用できるシンボル名の形式 (| で区切ります):

• シンボル名のみ (包含する型または名前空間に関係なく、その名前が指定されたすべてのシンボルが含まれます)。
• そのシンボルのドキュメント ID 形式の完全修飾名。 各シンボル名には、メソッドには M:、型には T:、名前空間には N: のように、シンボルの種類のプレフィックスが必要です。
• コンストラクターには .ctor、静的コンストラクターには .cctor。

例 :

オプション値	まとめ
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType	MyType という名前のすべてのシンボルを検索します。
dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType1|MyType2	MyType1 または MyType2 という名前のすべてのシンボルを検索します。
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS.MyType.MyMethod(ParamType)	指定された完全修飾シグネチャを持つ特定のメソッド MyMethod を検索します。
dotnet_code_quality.CAXXXX.excluded_symbol_names = M:NS1.MyType1.MyMethod1(ParamType)|M:NS2.MyType2.MyMethod2(ParamType)	それぞれの完全修飾シグネチャを持つ特定のメソッド MyMethod1 または MyMethod2 を検索します。

特定の型とその派生型を除外する

excluded_type_names_with_derived_types オプションを設定することで、特定の型とその派生型を分析から除外できます。 たとえば、MyType という名前の型のメソッドとその派生型で規則を実行しないように指定するには、プロジェクトの .editorconfig ファイルに次のキーと値のペアを追加します。

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

メモ

CAXXXX の XXXX 部分を該当するルールの ID に置き換えます。

オプションの値で使用できるシンボル名の形式 (| で区切ります):

• 型の名前のみ (包含する型または名前空間に関係なく、その名前が指定されたすべての型が含まれます)。
• そのシンボルのドキュメント ID 形式の完全修飾名 (オプションで T: プレフィックスも使用可)。

例 :

オプション値	まとめ
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType	MyType という名前のすべての型と、そのすべての派生型を検索します。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType1|MyType2	MyType1 または MyType2 という名前のすべての型と、そのすべての派生型を検索します。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS.MyType	指定された完全修飾名を持つ特定の型 MyType と、そのすべての派生型を検索します。
dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = M:NS1.MyType1|M:NS2.MyType2	それぞれの完全修飾名を持つ特定の型 MyType1 または MyType2 と、そのすべての派生型を検索します。

名前付けヒューリスティックを使用する

Text、Message、または Caption を含むパラメーターまたはプロパティ名でこの規則がトリガーされるかどうかを構成できます。

dotnet_code_quality.CA1303.use_naming_heuristic = true

例

次の例は、2 つの引数のいずれかが範囲外にある場合に、コンソールに書き込むメソッドを示しています。 hour 引数のチェックでは、リテラル文字列が Console.WriteLine に渡され、この規則に違反しています。 minute 引数のチェックでは、ResourceManager によって取得される文字列が Console.WriteLine に渡され、この規則に従っています。

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

関連項目

• .NET アプリのリソース
• 動作の変更に関するコミュニティの要求