Roslyn 분석기 규칙 사용자 지정

각 Roslyn 분석기 규칙 또는 진단에는 프로젝트에 대해 사용자 지정할 수 있는 기본 심각도 및 제거 상태가 있습니다. 이 문서에서는 분석기 심각도 설정 및 분석기 위반 억제에 대해 설명합니다.

심각도 수준

EditorConfig 파일 및 전구 메뉴에서 분석기 규칙의 심각도를 구성할 수 있습니다.

다음 표에서는 진단에 대해 구성할 수 있는 다양한 심각도 옵션을 보여줍니다.

심각도(솔루션 탐색기)	심각도(EditorConfig 파일)	빌드 시간 동작	편집기 동작
오류	error	오류 목록 창과 명령줄 빌드 출력의 오류 탭에 위반이 표시되고 빌드가 실패합니다.	잘못된 코드는 빨간색 물결선으로 밑줄이 표시되고 스크롤 막대에 작은 빨간색 상자로 표시됩니다.
경고	warning	위반은 오류 목록 창의 경고 탭과 명령줄 빌드 출력에 표시되지만 빌드가 실패하지는 않습니다.	잘못된 코드는 녹색 물결선으로 밑줄이 그어져 스크롤 막대에 작은 녹색 상자로 표시됩니다.
제안	suggestion	오류 목록 창의 메시지 탭에 위반이 표시되지만 명령줄 빌드 출력에는 표시되지 않습니다.	영향을 받는 코드는 회색 물결선으로 밑줄을 긋고 스크롤 막대에 작은 회색 상자로 표시됩니다.
침묵	silent	사용자에게 표시되지 않습니다.	사용자에게 표시되지 않지만 진단은 IDE 진단 엔진에 보고됩니다.
없음	none	전면적으로 억압되었습니다.	전면적으로 억압되었습니다.
기본값	default	규칙의 기본 심각도에 해당합니다. 규칙의 기본값을 확인하려면 해당 속성 창을 봅니다.	규칙의 기본 심각도에 해당합니다.

규칙 위반 보기

분석기가 분석기 규칙 위반을 발견하면 오류 목록 창과 코드 편집기에서 보고합니다.

다음 스크린샷은 오류 목록 창에 보고된 규칙 위반을 보여 줍니다. 오류 목록에 보고된 분석기 위반은 규칙 의 심각도 수준 설정 과 일치합니다.

또한 분석기 규칙 위반은 코드 편집기에서 잘못된 코드 아래에 물결선으로 표시됩니다. 예를 들어 다음 스크린샷은 오류 1개(빨간색 물결선), 경고 1개(녹색 물결선), 제안 1개(회색 점 3개)의 세 가지 위반을 보여 줍니다.

많은 진단에는 규칙 위반을 수정하기 위해 적용할 수 있는 하나 이상의 연결된 코드 수정 이 있습니다. 코드 수정은 다른 유형의 빠른 작업과 함께 전구 아이콘 메뉴에 표시됩니다. 코드 수정에 대한 자세한 내용은 일반적인 빠른 작업을 참조하세요.

심각도 수준 구성

다음 방법 중 원하는 방법을 사용하여 규칙 심각도를 설정할 수 있습니다.

• EditorConfig
• 전구 메뉴
• 솔루션 탐색기

무음 및 없음 심각도

Silent 기본적으로 사용하도록 설정된 심각도 규칙은 사용 안 함 또는 None 심각도 규칙과 다릅니다.

• 심각도 규칙에 대한 Silent 코드 수정이 등록된 경우 Visual Studio는 숨겨진 진단이 사용자에게 표시되지 않더라도 전구 코드 리팩터링 작업으로 코드 수정을 제공합니다. 심각도 규칙이 None로 비활성화된 경우, 코드 수정이 제공되지 않습니다.
• EditorConfig 파일에서 여러 분석기 규칙의 심각도를 한 번에 설정하는 항목은 심각도 규칙을 대량으로 구성할 Silent 수 있습니다. None 심각도 규칙은 이러한 방식으로 구성할 수 없습니다. 대신 각 규칙 ID에 대한 EditorConfig 파일의 심각도를 설정하는 항목을 통해 구성해야 합니다.

EditorConfig 파일에서 규칙 심각도 설정

EditorConfig 파일은 Visual Studio 2019 버전 16.3 이상에서 사용할 수 있습니다.

EditorConfig 파일에서 규칙의 심각도를 설정하는 것이 규칙 집합 또는 솔루션 탐색기에서 설정된 심각도보다 우선합니다. EditorConfig 파일에서 수동으로 또는 위반 옆에 나타나는 전구를 통해 심각도를 자동으로 구성할 수 있습니다.

EditorConfig 파일에서 규칙 심각도 수동 구성

규칙 심각도를 구성하려면 다음 단계를 수행합니다.

1. 아직 없는 경우 EditorConfig 파일을 프로젝트에 추가합니다.

2. 해당 파일 확장명 아래에서 구성하려는 각 규칙에 대한 항목을 추가합니다.

   예를 들어 CA1822error 의 심각도를 C# 파일로 설정하는 항목은 다음과 같습니다.

   [*.cs]
   dotnet_diagnostic.CA1822.severity = error
   

3. 다음 구문을 사용하여 EditorConfig 파일의 각 진단 규칙 ID에 대한 규칙 심각도를 설정할 수 있습니다.

   dotnet_diagnostic.<rule ID>.severity = <severity>

4. IDE 코드 스타일 분석기의 경우 다른 구문을 사용하여 EditorConfig 파일에서 구성할 수도 있습니다.

   예: dotnet_style_qualification_for_field = false:suggestion. 그러나 구문을 사용하여 심각도를 dotnet_diagnostic 설정하는 경우 우선 순위가 적용됩니다. 자세한 내용은 EditorConfig에 대한 언어 규칙을 참조하세요.

EditorConfig 파일에서 한 번에 여러 분석기 규칙의 심각도 설정

EditorConfig 파일에서 여러 분석기 규칙을 한 번에 설정하는 기능은 Visual Studio 2019 버전 16.5 이상에서 사용할 수 있습니다.

EditorConfig 파일에서 단일 항목을 사용하여 분석기 규칙의 특정 범주 또는 모든 분석기 규칙에 대한 심각도를 설정할 수 있습니다.

• 분석기 규칙 범주에 대한 규칙 심각도를 설정합니다.

  dotnet_analyzer_diagnostic.category-<rule category>.severity = <severity>

• 모든 분석기 규칙에 대한 규칙 심각도를 설정합니다.

  dotnet_analyzer_diagnostic.severity = <severity>

여러 분석기 규칙을 한 번에 구성하는 항목은 기본적으로 사용하도록 설정된 규칙에만 적용됩니다. 분석기 패키지에서 기본적으로 사용하지 않도록 표시된 분석기 규칙은 명시적 dotnet_diagnostic.<rule ID>.severity = <severity> 항목을 통해 사용하도록 설정해야 합니다.

특정 규칙 ID에 적용할 수 있는 여러 항목이 있는 경우 해당 항목의 우선 순위는 다음과 같습니다.

• ID별 개별 규칙에 대한 심각도 항목이 범주의 심각도 항목보다 우선합니다.
• 범주의 심각도 항목이 모든 분석기 규칙의 심각도 항목보다 우선합니다.

CA1822가 성능 규칙인 다음 EditorConfig 예제를 고려합니다.

[*.cs]
dotnet_diagnostic.CA1822.severity = error
dotnet_analyzer_diagnostic.category-performance.severity = warning
dotnet_analyzer_diagnostic.severity = suggestion

이 예제에서 세 항목은 모두 성능 규칙 CA1822에 적용합니다. 그러나 지정된 우선 순위 규칙을 사용하여 첫 번째 규칙 ID 기반 심각도 항목이 다음 항목보다 우선합니다. 이 예제에서 CA1822의 유효 심각도는 error입니다. 나머지 성능 규칙에는 심각도가 warning있습니다. 성능 규칙이 아닌 분석기 규칙에는 심각도가 suggestion있습니다.

전구 메뉴에서 규칙 심각도 설정

Visual Studio는 빠른 작업 전구 메뉴에서 규칙의 심각도를 구성하는 편리한 방법을 제공합니다. 아래 단계를 수행하세요.

1. 위반이 발생한 후 편집기에서 위반 물결선 위로 마우스를 가져가고 잠재적 수정 사항 표시 를 선택하여 전구 메뉴를 엽니다. 또는 커서를 줄에 놓고 Ctrl+ 키를 누릅니다( 마침표).

2. 전구 메뉴에서 변경 미리 보기의 심각도 수준을 마우스로 가리킨 다음 다음 옵션에 따라 심각도를 구성합니다.

   • <규칙 ID> 심각도를 구성합니다. 특정 규칙 의 심각도 를 설정합니다.

   • 모든 <스타일> 분석기의 심각도를 설정하세요. 특정 규칙 범주의 모든 규칙에 대한 심각도를 설정합니다.

   • 모든 분석기의 심각도를 구성합니다. 분석기 규칙의 모든 범주에 대한 심각도를 설정합니다.

     다음 예제에서는 문제를 표시 안 함 또는 구성>을 선택하고 규칙 ID< 심각도>를 구성합니다.

     

3. 심각도 옵션 중 하나를 선택합니다.

   

   Visual Studio는 미리 보기 상자에 표시된 것처럼 EditorConfig 파일에 항목을 추가하여 요청된 심각도 수준에 규칙을 구성합니다.

   프로젝트에 EditorConfig 파일이 아직 없는 경우 Visual Studio에서 해당 파일을 만듭니다.

솔루션 탐색기에서 규칙 심각도 설정

솔루션 탐색기에서 규칙 심각도를 설정하려면 다음 단계를 수행합니다.

1. 솔루션 탐색기에서 참조>분석기 (또는 .NET Core 프로젝트의 종속성>분석기 )를 확장합니다.

2. 심각도를 설정할 규칙이 포함된 어셈블리를 확장합니다.

3. 규칙을 마우스 오른쪽 단추로 클릭하고 심각도 설정을 선택합니다. 상황에 맞는 메뉴에서 심각도 옵션 중 하나를 선택합니다.

   Visual Studio는 EditorConfig 파일에 항목을 추가하여 규칙을 요청된 수준으로 구성합니다. 프로젝트에서 EditorConfig 파일 대신 규칙 집합 파일을 사용하는 경우 심각도 항목이 규칙 집합 파일에 추가됩니다.

   프로젝트에 EditorConfig 파일 또는 규칙 집합 파일이 아직 없는 경우 Visual Studio에서 새 EditorConfig 파일을 만듭니다.

솔루션 탐색기에서 분석기 및 진단 보기

솔루션 탐색기에서 분석기 진단의 사용자 지정을 대부분 수행할 수 있습니다. 분석기를 NuGet 패키지로 설치하면 솔루션 탐색기의 참조 노드(또는 .NET Core 프로젝트의 종속성 노드) 아래에 분석기 노드가 나타납니다. 분석기 및 진단을 보려면 다음 단계를 수행합니다.

1. 솔루션 탐색기에서 프로젝트를 확장하고 참조 또는 종속성을 확장한 다음 분석기를 확장합니다. 분석기 어셈블리 중 하나를 확장하여 어셈블리의 진단을 확인합니다.

   각 진단 옆에 있는 아이콘은 심각도 수준을 나타냅니다.

   • x원에서 오류의 심각도를 나타냅니다.
   • !삼각형에서 경고의 심각도를 나타냅니다.
   • i단색 원에서 제안의 심각도를 나타냅니다.
   • i 점선 원은 무음의 심각도를 나타냅니다.
   • 단색 원의 아래쪽 화살표는 없음의 심각도를 나타냅니다.

   

2. 설명 및 기본 심각도를 포함하여 진단의 속성을 보려면 진단을 마우스 오른쪽 단추로 클릭한 다음 속성을 선택합니다. 또는 진단을 선택한 다음 Alt+ + Enter 키를 누릅니다.

   속성 창이 나타납니다.

   

3. 기본 심각도와 같은 속성 창에서 코드 스타일 규칙(IDE 접두사)의 속성을 보려면 EnforceCodeStyleInBuild 속성을 true.로 설정합니다.

4. 진단에 대한 온라인 설명서의 경우 진단을 마우스 오른쪽 단추로 클릭한 다음 도움말 보기를 선택합니다.

기존 규칙 집합 파일을 EditorConfig 파일로 변환

Visual Studio 2019 버전 16.5 이상에서는 관리 코드에 대한 분석기 구성을 위해 EditorConfig 파일을 위해 규칙 집합 파일이 더 이상 사용되지 않습니다. EditorConfig 파일은 더 유연하며 Visual Studio IDE 코드 스타일 옵션을 포함하여 분석기 규칙 심각도 및 분석기 옵션을 모두 구성할 수 있습니다. 분석기 규칙 심각도 구성용 Visual Studio 도구는 이제 규칙 집합 파일 대신 EditorConfig 파일로 작동하도록 최적화되었으므로 규칙 집합 파일을 계속 사용하는 기존 프로젝트를 변환하는 것이 좋습니다.

기존 규칙 집합 파일을 EditorConfig 파일로 변환하는 경우 리포지토리의 루트 또는 솔루션 폴더에 저장합니다. 이렇게 하면 이 파일의 심각도 설정이 각각 전체 리포지토리 또는 솔루션에 자동으로 적용됩니다.

규칙 집합 편집기 또는 명령줄을 사용하여 기존 규칙 집합 파일을 EditorConfig 파일로 변환할 수 있습니다.

비고

.NET Core 및 .NET 5+ 프로젝트는 솔루션 탐색기에서 규칙 집합에 대한 메뉴 명령(예: 활성 규칙 집합 열기)을 지원하지 않습니다. .NET Core 또는 .NET 5+ 프로젝트에 대한 기본이 아닌 규칙 집합을 지정하려면 프로젝트 파일에 CodeAnalysisRuleSet 속성을 수동으로 추가합니다. 규칙 집합 편집기에서 규칙 집합 내에서 규칙을 구성할 수 있습니다.

규칙 집합 편집기를 사용하려면 다음 단계를 수행합니다. 프로젝트에서 속성 값에 CodeAnalysisRuleSet 특정 규칙 집합 파일을 이미 사용하는 경우 규칙 집합 편집기에서 해당 EditorConfig 파일로 변환할 수 있습니다.

1. 솔루션 탐색기에서 규칙 집합 파일을 두 번 클릭합니다.

   규칙 집합 파일이 위쪽에 클릭 가능한 정보 표시줄 이 있는 규칙 집합 편집기에서 열립니다.

   

2. 정보 표시줄 링크를 선택하여 규칙 집합 편집기 파일을 마이그레이션합니다.

3. 다른 이름으로 저장 대화 상자에서 EditorConfig 파일을 생성할 디렉터리를 선택한 다음 저장을 선택합니다.

   생성된 EditorConfig가 편집기에서 열립니다. 또한 MSBuild 속성 CodeAnalysisRuleSet 은 더 이상 원래 규칙 집합 파일을 참조하지 않도록 프로젝트 파일에서 업데이트됩니다.

   원래 규칙 집합 파일을 프로젝트에서 제거할 수 있습니다.

   비고

   .NET Framework 프로젝트에서는 기본 규칙 집합 파일을 프로젝트에서 마이그레이션하거나 제거할 수 없습니다.

명령줄을 사용하려면 다음 단계를 수행합니다.

1. NuGet 패키지 Microsoft.CodeAnalysis.RulesetToEditorconfigConverter를 설치합니다.

2. 규칙 집합 파일의 경로와 EditorConfig 파일을 명령줄 인수로 사용하여 설치된 패키지에서RulesetToEditorconfigConverter.exe 실행합니다.

   다음은 그 예입니다.

   Usage: RulesetToEditorconfigConverter.exe <%ruleset_file%> [<%path_to_editorconfig%>]
   

다음 예제에서는 EditorConfig 파일로 변환할 규칙 집합 파일을 보여줍니다.

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="Rules for ConsoleApp" Description="Code analysis rules for ConsoleApp.csproj." ToolsVersion="16.0">
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1001" Action="Warning" />
    <Rule Id="CA1821" Action="Warning" />
    <Rule Id="CA2213" Action="Warning" />
    <Rule Id="CA2231" Action="Warning" />
  </Rules>
</RuleSet>

다음 예제에서는 변환 후의 결과 EditorConfig 파일을 보여줍니다.

# NOTE: Requires **VS2019 16.3** or later

# Rules for ConsoleApp
# Description: Code analysis rules for ConsoleApp.csproj.

# Code files
[*.{cs,vb}]

dotnet_diagnostic.CA1001.severity = warning
dotnet_diagnostic.CA1821.severity = warning
dotnet_diagnostic.CA2213.severity = warning
dotnet_diagnostic.CA2231.severity = warning

생성된 코드 구성

분석기는 프로젝트의 원본 파일에서 실행되고 찾은 위반을 보고합니다. 그러나 이러한 위반은 시스템 생성 파일에는 유용하지 않습니다. 예제는 디자이너에서 생성한 코드 파일, 빌드 시스템에서 생성된 임시 소스 파일 등과 같은 생성된 코드 파일입니다. 이러한 유형의 파일의 경우 사용자는 파일을 수동으로 편집할 수 없으며 위반 문제를 해결하는 데 신경 쓰지 않습니다.

따라서 기본적으로 분석기 드라이버는 특정 이름, 파일 확장명 또는 자동 생성된 파일 헤더가 있는 파일만 생성된 코드 파일로 검사합니다. 예를 들어 .designer.cs 또는 .generated.cs 끝나는 파일 이름은 생성된 코드로 간주됩니다. 그러나 이러한 추론은 사용자의 소스 코드에서 생성된 모든 사용자 지정 코드 파일을 식별하지 못할 수 있습니다.

Visual Studio 2019 버전 16.5 이상에서는 최종 사용자가 EditorConfig 파일에서 생성된 코드로 처리되도록 특정 파일 및 폴더를 구성할 수 있습니다.

이러한 구성을 추가하려면 다음 단계를 수행합니다.

1. 프로젝트에 대한 EditorConfig 파일이 아직 없는 경우 추가합니다.

2. generated_code = true | false 특정 파일 및 폴더에 대한 항목을 추가합니다. 예를 들어 이름이 생성된 코드로 .MyGenerated.cs 끝나는 모든 파일을 처리하려면 다음 항목을 사용합니다.

   [*.MyGenerated.cs]
   generated_code = true
   

위반 억제

다양한 방법으로 규칙 위반을 무시할 수 있습니다. 자세한 내용은 코드 분석 위반 억제하기를 참조하세요.

명령줄 사용법

명령줄에서 프로젝트를 빌드할 때 다음 조건이 충족되면 빌드 출력에 규칙 위반이 표시됩니다.

• 분석기는 . VSix 확장이 아닌 .NET SDK 또는 NuGet 패키지로 설치됩니다.

  .NET SDK를 사용하여 설치된 분석기의 경우 분석기를 사용하도록 설정해야 할 수 있습니다. 코드 스타일의 경우 MSBuild 속성을 설정하여 빌드에 코드 스타일을 적용 할 수도 있습니다.

• 프로젝트 코드에서 하나 이상의 규칙이 위반됩니다.

• 위반된 규칙 의 심각도 수준은경고로 설정되며, 이 경우 위반으로 인해 빌드가 실패하지 않거나 오류가 발생하며, 이 경우 위반으로 인해 빌드가 실패합니다.

빌드 출력의 자세한 내용은 규칙 위반이 표시되는지 여부에 영향을 주지 않습니다. 낮은 출력 수준이더라도 규칙 위반이 빌드 출력에 나타납니다.

명령줄에서 FxCopCmd.exe 또는 플래그가 있는 msbuild RunCodeAnalysis 를 통해 레거시 분석을 실행하는 데 익숙한 경우 코드 분석기를 사용하여 대신 수행할 수 있습니다.

msbuild를 사용하여 프로젝트를 빌드할 때 명령줄에서 분석기 위반을 확인하려면 다음과 유사한 명령을 실행합니다.

msbuild myproject.csproj /target:rebuild /verbosity:minimal

다음 스크린샷은 분석기 규칙 위반이 포함된 프로젝트를 빌드할 때의 명령줄 빌드 출력을 보여 줍니다.

종속 프로젝트

.NET Core 프로젝트에서 NuGet 분석기가 있는 프로젝트에 대한 참조를 추가하면 Visual Studio에서 해당 분석기를 종속 프로젝트에 자동으로 추가합니다. 이 동작을 사용하지 않도록 설정하려면(예: 종속 프로젝트가 단위 테스트 프로젝트인 경우) 참조된 프로젝트의 PrivateAssets 또는 .vbproj 파일에서 특성을 설정 하여 NuGet 패키지를 프라이빗으로 표시합니다.

<PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="5.0.0" PrivateAssets="all" />

관련 콘텐츠

• Visual Studio의 코드 분석기 개요
• 코드 분석기 버그 제출
• 규칙 집합 사용
• 코드 분석 위반 억제
• 코드 분석을 위한 구성 옵션