다음을 통해 공유

코드 분석 규칙에 대한 구성 파일

  • 아티클

코드 분석 규칙에는 다양한 구성 옵션이 있습니다. 구성 옵션을 다음 분석기 구성 파일 중 하나에서 키-값 쌍으로 지정합니다.

  • EditorConfig 파일: 파일 기반 또는 폴더 기반 구성 옵션입니다.
  • 전역 AnalyzerConfig 파일: 프로젝트 수준 구성 옵션이며 일부 프로젝트 파일이 프로젝트 폴더 외부에 있을 때 유용합니다.

팁

프로젝트 파일에서 코드 분석 구성 속성을 설정할 수도 있습니다. 이러한 속성은 코드 분석을 완전히 켜거나 끄는 것부터 범주 수준 규칙 구성에 이르기까지 대량 수준에서 코드 분석을 구성합니다. 자세한 내용은 EnableNETAnalyzers, AnalysisLevel, AnalysisLevel<범주>및 AnalysisMode를 참조하세요.

EditorConfig

EditorConfig 파일은 특정 소스 파일이나 폴더에 적용되는 옵션을 제공하는 데 사용됩니다. 옵션은 해당하는 파일 및 폴더를 식별하기 위해 섹션 헤더 아래에 배치됩니다. 구성하려는 각 규칙에 대한 항목을 추가하고 해당하는 파일 확장명 섹션에 배치합니다(예: [*.cs]).

[*.cs]
<option_name> = <option_value>

위의 예에서 [*.cs]은(는) 하위 폴더를 비롯하여 현재 폴더 내에서 .cs 파일 확장명이 있는 모든 C# 파일을 선택하는 editorconfig 섹션 헤더입니다. 후속 항목인 <option_name> = <option_value>는 모든 C# 파일에 적용되는 분석기 옵션입니다.

EditorConfig 파일을 해당 디렉터리에 배치하여 폴더, 프로젝트 또는 전체 리포지토리에 해당 파일 규칙을 적용할 수 있습니다. 관련 옵션은 Visual Studio에서 코드를 편집하고 빌드 시 분석할 때 적용됩니다.

참고 항목

EditorConfig 옵션은 프로젝트 또는 디렉터리에 있는 ‘소스’ 파일에만 적용합니다. 프로젝트에 AdditionalFiles로 포함된 파일은 원본 파일로 간주되지 않으며 이러한 파일에는 EditorConfig 옵션이 적용되지 않습니다. 소스가 아닌 파일에 규칙 옵션을 적용하려면 전역 구성 파일에서 옵션을 지정합니다.

들여쓰기 크기 또는 후행 공백을 잘라낼지와 같은 편집기 설정에 대한 기존 .editorconfig 파일이 있는 경우 코드 분석 구성 옵션을 동일한 파일에 저장할 수 있습니다.

팁

Visual Studio는 프로젝트에 이러한 파일 중 하나를 쉽게 추가할 수 있는 .editorconfig 항목 템플릿을 제공합니다. 자세한 내용은 프로젝트에 EditorConfig 파일 추가를 참조하세요.

예시

다음은 옵션 및 규칙 심각도를 구성하는 예제인 EditorConfig 파일입니다.

# Remove the line below if you want to inherit .editorconfig settings from higher directories
root = true

# C# files
[*.cs]

#### Core EditorConfig Options ####

# Indentation and spacing
indent_size = 4
indent_style = space
tab_width = 4

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

전역 AnalyzerConfig

전체 AnalyzerConfig 파일을 사용하여 분석기 옵션을 구성할 수도 있습니다. 이러한 파일은 파일 이름이나 파일 경로와 관계없이 프로젝트의 모든 소스 파일에 적용되는 옵션을 제공하는 데 사용됩니다.

EditorConfig 파일과 달리 전역 구성 파일은 들여쓰기 크기 또는 후행 공백을 잘라낼지와 같은 IDE용 편집기 스타일 설정을 구성하는 데는 사용할 수 없습니다. 대신 프로젝트 수준 분석기 구성 옵션을 지정하는 데만 사용하도록 설계되었습니다.

형식

해당하는 파일 및 폴더를 식별하기 위해 [*.cs]와 같이 반드시 섹션 헤더를 포함해야 하는 EditorConfig 파일과 달리 전역 AnalyzerConfig 파일에는 섹션 헤더가 없습니다. 대신 일반 EditorConfig 파일과 구분하기 위해 is_global = true 양식의 최상위 항목이 필요합니다. 이는 파일의 모든 옵션이 전체 프로젝트에 적용됨을 나타냅니다. 예시:

is_global = true
<option_name> = <option_value>

이름 지정

.editorconfig로 명명되어야 하는 EditorConfig 파일과 달리 전체 구성 파일에는 특정 이름 또는 확장명이 필요하지 않습니다. 하지만 이 파일 이름을 .globalconfig로 지정하면 하위 폴더를 포함하여 현재 폴더 내의 모든 C# 및 Visual Basic 프로젝트에 암시적으로 적용됩니다. 그러지 않은 경우 MSBuild 프로젝트 파일에 GlobalAnalyzerConfigFiles 항목을 명시적으로 추가해야 합니다.

<ItemGroup>
  <GlobalAnalyzerConfigFiles Include="<path_to_global_analyzer_config>" />
</ItemGroup>

다음 명명 권장 사항을 따르는 것이 좋습니다.

  • 최종 사용자는 전역 구성 파일의 이름을 .globalconfig로 지정해야 합니다.
  • NuGet 패키지 작성자는<%Package_Name%>.globalconfig 전역 구성 파일의 이름을 지정해야 합니다.
  • MSBuild 도구에서 생성된 전역 구성 파일은 <%Target_Name%>_Generated.globalconfig으로 이름이 지정되어야 합니다.

참고 항목

파일 이름을 .globalconfig로 지정할 때 최상위 항목 is_global = true가 필수는 아니지만 명확성을 위해 권장됩니다.

조건 포함

전체 구성 파일을 사용하여 다른 환경에서 특정 코드 분석 규칙을 사용하거나 사용하지 않도록 설정할 수 있습니다. 예를 들어 단위 테스트 프로젝트에 대해 일부 코드 분석 규칙을 사용하지 않도록 설정할 수 있습니다. 이를 위해서는 예컨대 구성 파일에서 적용 가능한 규칙의 심각도를 none으로 설정할 수 있습니다.

# CA1861: Prefer 'static readonly' fields over constant array arguments
dotnet_diagnostic.CA1861.severity = none

그런 다음 빌드와 관련된 조건에 따라 테스트 프로젝트에 구성 파일만 포함하도록 빌드를 사용자 지정할 수 있습니다. 예시:

<ItemGroup Condition="'$(IsShipping)' == 'false'">
  <!-- Include CodeAnalysis.test.globalconfig to override (relax) some rules from the primary configuration. -->
  <GlobalAnalyzerConfigFiles Include="$(MSBuildThisFileDirectory)CodeAnalysis.test.globalconfig" />
</ItemGroup>

NuGet 패키지의 배포

Global AnalyzerConfig 파일은 NuGet 패키지로 배포할 수 있습니다. 이렇게 하려면 .props 파일을 NuGet 패키지에 추가합니다. .props 파일에서 Project 노드 아래에 GlobalAnalyzerConfigFiles 항목을 추가합니다.

<Project>
  <ItemGroup>
    <GlobalAnalyzerConfigFiles Include="Relative/Path/to/PackageName.globalconfig" />
  </ItemGroup>
</Project>

예시

다음은 프로젝트 수준에서 옵션 및 규칙 심각도를 구성하는 예제인 전역 AnalyzerConfig 파일입니다.

# Top level entry required to mark this as a global AnalyzerConfig file
is_global = true

# NOTE: No section headers for configuration entries

#### .NET Coding Conventions ####

# this. and Me. preferences
dotnet_style_qualification_for_method = true:warning

#### Diagnostic configuration ####

# CA1000: Do not declare static members on generic types
dotnet_diagnostic.CA1000.severity = warning

우선 순위

EditorConfig 파일 및 전역 AnalyzerConfig 파일은 모두 각 옵션에 대한 키-값 쌍을 지정합니다. 키가 같지만 값이 다른 항목이 여러 개 있으면 충돌이 발생합니다. 충돌을 해결하는 데는 다음 우선 순위 규칙이 사용됩니다.

충돌하는 항목 위치 우선 순위 규칙
동일한 구성 파일 파일에서 뒤에 나타나는 항목이 우선합니다. 이는 단일 EditorConfig 파일 내에 그리고 단일 전역 AnalyzerConfig 파일 내에 충돌하는 항목이 있는 경우에도 마찬가지입니다.
두 EditorConfig 파일 파일 시스템에서 더 깊이 위치하여 파일 경로가 더 긴 EditorConfig 파일의 항목이 우선합니다.
두 전역 AnalyzerConfig 파일 .NET 5: 컴파일러 경고가 보고되고 두 항목이 모두 무시됩니다.
.NET 6 이상 버전: 파일에서 global_level 값이 더 큰 항목이 우선합니다. global_level이 명시적으로 정의되어 있지 않고 파일 이름이 .globalconfig이면 global_level 값은 기본적으로 100으로 설정되고, 다른 모든 전역 AnalyzerConfig 파일의 경우 global_level은 기본적으로 0으로 설정됩니다. 충돌하는 항목이 있는 구성 파일의 global_level 값이 같으면 컴파일러 경고가 보고되고 두 항목이 모두 무시됩니다.
EditorConfig 파일 및 전역 AnalyzerConfig 파일 EditorConfig 파일의 항목이 우선합니다.

심각도 옵션

심각도 구성 옵션의 경우 다음과 같은 ‘추가’ 우선 순위 규칙이 적용됩니다.

  • 명령줄에서 컴파일러 옵션(-nowarn 또는 -warnaserror)은 항상 EditorConfig 및 전역 AnalyzerConfig 파일에 지정된 심각도 구성 옵션을 재정의합니다.

  • 규칙 집합 파일과 EditorConfig 또는 전역 AnalyzerConfig 파일의 충돌하는 심각도 항목에 대한 우선 순위 규칙은 ‘정의되지 않습니다’.

    규칙 집합 파일 대신 EditorConfig 및 전역 AnalyzerConfig 파일이 사용됩니다. 규칙 집합 파일을 동일한 EditorConfig 파일로 변환하는 것이 좋습니다.

  • 서로 다른 키를 사용하는 관련 심각도 옵션의 우선 순위 규칙(예: 단일 규칙 및 해당 규칙이 적용되는 범주에 대해 서로 다른 심각도가 지정된 경우)에 대한 자세한 내용은 코드 분석에 대한 구성 옵션을 참조하세요.

참고 항목