다음을 통해 공유

CA1027: 열거형을 FlagsAttribute로 표시하십시오.

  • 아티클
속성 값
규칙 ID CA1027
타이틀 열거형을 FlagsAttribute로 표시하세요.
범주 디자인
수정 사항이 주요 변경인지 여부 주요 변경 아님
.NET 8에서 기본적으로 사용 아니요

원인

열거형 값이 2의 거듭제곱 이거나 열거형에 정의된 다른 값의 결합이며 System.FlagsAttribute 특성이 없습니다. 가양성을 줄이기 위해 이 규칙은 연속 값을 포함하는 열거형에 대한 위반을 보고하지 않습니다.

기본적으로 이 규칙은 외부에 표시되는 열거형만 확인하지만 이는 구성 가능합니다.

규칙 설명

열거형은 서로 관련 있는 명명된 상수 집합을 정의하는 값 형식입니다. 명명된 상수를 의미 있게 결합할 수 있는 경우에 열거형에 FlagsAttribute를 적용합니다. 예를 들어 어느 요일의 리소스를 사용할 수 있는지 추적하는 애플리케이션에 요일을 열거하는 것이 좋습니다. FlagsAttribute를 포함하는 열거형을 사용하여 각 리소스의 가용성을 인코딩한 경우에는 일의 결합을 표현할 수 있습니다. 특성이 없으면 하나의 요일만 표현할 수 있습니다.

결합 가능한 열거형을 저장하는 필드의 경우 개별 열거형 값은 필드의 비트 그룹으로 처리됩니다. 따라서 이러한 필드를 ‘비트 필드’라고 합니다. 비트 필드의 스토리지에 대한 열거형 값을 결합하려면 부울 조건부 연산자를 사용합니다. 비트 필드를 테스트하여 특정 열거형 값이 있는지를 확인하려면 부울 논리 연산자를 사용합니다. 비트 필드가 결합된 열거형 값을 올바르게 저장하고 검색하려면 열거형에 정의된 각 값이 2의 거듭제곱이어야 합니다. 이 경우가 아니면 부울 논리 연산자는 필드에 저장된 개별 열거형 값을 추출할 수 없습니다.

위반 문제를 해결하는 방법

이 규칙 위반 문제를 해결하려면 FlagsAttribute를 열거형에 추가합니다.

경고를 표시하지 않는 경우

열거형 값을 결합할 수 없게 하려면 이 규칙의 경고를 표시하지 마세요.

경고 표시 안 함

단일 위반만 표시하지 않으려면 원본 파일에 전처리기 지시문을 추가하여 규칙을 사용하지 않도록 설정한 후 다시 사용하도록 설정합니다.

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

파일, 폴더 또는 프로젝트에 대한 규칙을 사용하지 않도록 설정하려면 구성 파일에서 심각도를 none으로 설정합니다.

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

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

분석할 코드 구성

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

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

특정 API 화면 포함

접근성을 기반으로 이 규칙을 실행할 코드베이스의 파트를 구성할 수 있습니다. 예를 들어 규칙이 퍼블릭이 아닌 API 표면에서만 실행되도록 지정하려면 프로젝트의 .editorconfig 파일에 다음 키-값 쌍을 추가합니다.

dotnet_code_quality.CAXXXX.api_surface = private, internal

예시

다음 예제에서 DaysEnumNeedsFlags는 FlagsAttribute을 사용하기 위한 요구 사항을 충족하지만 이를 포함하지 않는 열거형입니다. ColorEnumShouldNotHaveFlag 열거형에는 2의 거듭제곱이지만 FlagsAttribute를 잘못 지정하는 값이 없습니다. 이는 CA2217: 열거형을 FlagsAttribute로 표시하지 마세요 규칙을 위반합니다.

// Violates rule: MarkEnumsWithFlags.
public enum DaysEnumNeedsFlags
{
    None = 0,
    Monday = 1,
    Tuesday = 2,
    Wednesday = 4,
    Thursday = 8,
    Friday = 16,
    All = Monday | Tuesday | Wednesday | Thursday | Friday
}

// Violates rule: DoNotMarkEnumsWithFlags.
[FlagsAttribute]
public enum ColorEnumShouldNotHaveFlag
{
    None = 0,
    Red = 1,
    Orange = 3,
    Yellow = 4
}

참고 항목