CA1303: 리터럴을 지역화된 매개 변수로 전달하지 마십시오.

아티클
01/31/2024

속성	값
규칙 ID	CA1303
제목	리터럴을 지역화된 매개 변수로 전달하지 마세요.
범주	전역화
수정 사항이 주요 변경인지 여부	주요 변경 아님
.NET 9에서 기본적으로 사용	아니요

원인

메서드가 문자열 리터럴을 .NET 생성자 또는 메서드에 매개 변수로 전달하며 이 문자열은 지역화할 수 있어야 합니다.

이 경고는 리터럴 문자열이 매개 변수 또는 속성에 값으로 전달되고 다음 상황 중 하나 이상이 충족되는 경우에 발생합니다.

매개 변수 또는 속성의 LocalizableAttribute 특성이 true로 설정되어 있습니다.
리터럴 문자열이 Console.Write 또는 Console.WriteLine 메서드 오버로드의 string value 또는 string format 매개 변수에 전달됩니다.
규칙 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

자세한 내용은 방법: 코드 분석 경고 표시 안 함을 참조하세요.

분석할 코드 구성

다음 옵션을 사용하여 이 규칙이 실행될 코드베이스 부분을 구성합니다.

특정 기호 제외
특정 형식 및 해당 파생 형식 제외
명명 휴리스틱 사용

이 규칙, 적용되는 모든 규칙 또는 적용되는 이 범주(세계화)의 모든 규칙에 대해 이러한 옵션을 구성할 수 있습니다. 자세한 내용은 코드 품질 규칙 구성 옵션을 참조하세요.

특정 기호 제외

분석에서 형식 및 메서드와 같은 특정 기호를 제외할 수 있습니다. 예를 들어 MyType이라는 형식 내 코드에서 규칙을 실행하지 않도록 지정하려면 프로젝트의 .editorconfig 파일에 다음 키-값 쌍을 추가합니다.

dotnet_code_quality.CAXXXX.excluded_symbol_names = MyType

옵션 값의 허용되는 기호 이름 형식(|로 구분):

기호 이름만(포함하는 형식 또는 네임스페이스와 관계없이 해당 이름의 모든 기호 포함).
기호의 설명서 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`를 개별 정규화된 시그니처와 비교합니다.

특정 형식 및 해당 파생 형식 제외

분석에서 특정 형식과 해당 파생 형식을 제외할 수 있습니다. 예를 들어 MyType이라는 형식 및 해당 파생 형식 내에 있는 메서드에서 규칙이 실행되지 않도록 지정하려면 프로젝트의 .editorconfig 파일에 다음 키-값 쌍을 추가합니다.

dotnet_code_quality.CAXXXX.excluded_type_names_with_derived_types = MyType

옵션 값의 허용되는 기호 이름 형식(|로 구분):

형식 이름만(포함하는 형식이나 네임스페이스와 관계없이 해당 이름의 모든 형식 포함)
기호의 설명서 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

예시

다음 예제에서는 두 인수 중 하나가 범위를 벗어난 경우 콘솔에 쓰는 메서드를 보여 줍니다. 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));
        }
    }
}

다음을 통해 공유