Roslyn 분석기 규칙 사용자 지정

각 Roslyn 분석기 규칙 또는 진단에는 프로젝트에 맞게 사용자 지정할 수 있는 기본 심각도 및 비표시 상태가 있습니다. 이 문서에서는 분석기 심각도 설정 및 분석기 위반 비표시를 설명합니다.

심각도 수준

Visual Studio 2019 버전 16.3 이상에서는 EditorConfig 파일, 전구 메뉴 및 오류 목록 창에서 분석기 규칙의 심각도를 구성할 수 있습니다.

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

심각도(솔루션 탐색기)	심각도(EditorConfig 파일)	빌드 시간 동작	편집기 동작
Error	error	위반은 오류 목록 창의 오류 탭과 명령줄 빌드 출력에 표시되며 빌드가 실패하게 됩니다.	위반 코드는 빨간색 물결선이 밑줄로 표시되고 스크롤 막대에 작은 빨간색 상자가 표시됩니다.
Warning	warning	위반은 오류 목록 창의 오류 탭과 명령줄 빌드 출력에 표시되지만 빌드가 실패하지 않습니다.	위반 코드는 녹색 물결선이 밑줄로 표시되고 스크롤 막대에 작은 녹색 상자가 표시됩니다.
제안 해결 방법	suggestion	위반은 오류 목록 창의 메시지 탭에 표시되지만 명령줄 빌드 출력에는 표시되지 않습니다.	위반 코드는 회색 물결선이 밑줄로 표시되고 스크롤 막대에 작은 회색 상자가 표시됩니다.
침묵	silent	사용자에게 표시되지 않습니다.	사용자에게 표시되지 않지만 진단은 IDE 진단 엔진에 보고됩니다.
None	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. 구성하려는 규칙마다 해당 파일 확장명으로 항목을 추가합니다.

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

   [*.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별 개별 규칙의 심각도 항목이 범주의 심각도 항목보다 우선합니다.
• 범주의 심각도 항목이 모든 분석기 규칙의 심각도 항목보다 우선합니다.

다음 EditorConfig 예를 살펴보면 여기서 CA1822에는 성능 규칙입니다.

[*.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가 자동으로 해당 파일을 만듭니다.

오류 목록 창에서 규칙 심각도 설정

Visual Studio에는 오류 목록 상황에 맞는 메뉴에서 규칙의 심각도를 구성하는 편리한 방법이 있습니다. 다음 단계를 수행합니다.

1. 위반이 발생한 후 오류 목록에서 진단 항목을 마우스 오른쪽 단추로 클릭합니다.

2. 컨텍스트 메뉴에서 심각도 설정을 선택한 다음 심각도 옵션 중 하나를 선택합니다.

   

   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 Tools는 이제 규칙 집합 파일 대신 EditorConfig 파일로 작동하도록 최적화되었으므로 규칙 집합 파일을 계속 사용하는 기존 프로젝트를 변환하는 것이 좋습니다.

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

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

참고 항목

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

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

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

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

   

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

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

   생성된 EditorConfig가 편집기에서 열립니다. 또한 MSBuild 속성 CodeAnalysisRuleSet는 프로젝트 파일에서 업데이트되므로 기존의 규칙 집합 파일을 더 이상 참조하지 않습니다.

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

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
   

위반 표시 안 함

다양한 메서드를 사용하여 규칙 위반을 표시하지 않을 수 있습니다. 자세한 내용은 코드 분석 위반 표시 안 함을 참조하세요.

명령줄 사용법

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

• 분석기는 .NET SDK를 사용하여 설치되거나 .vsix 확장이 아닌 NuGet 패키지로 설치됩니다.

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

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

• 위반된 규칙의 심각도 수준은 경고(이 경우 위반으로 인해 빌드가 실패하지 않음) 또는 오류(이 경우 위반으로 인해 빌드가 실패함)로 설정됩니다.

그러나 이러한 휴리스틱은 사용자 소스 코드에서 사용자 지정 생성 코드 파일을 모두 식별하지 못할 수도 있습니다. 최소 자세한 정도를 사용하더라도 규칙 위반이 빌드 출력에 표시됩니다.

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

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

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

다음 스크린샷에서는 분석기 규칙 위반을 포함하는 프로젝트 빌드의 명령줄 빌드 출력을 보여줍니다.

종속 프로젝트

.NET Core 프로젝트에서 NuGet 분석기가 있는 프로젝트에 참조를 추가하면 해당 분석기가 종속 프로젝트에도 자동으로 추가됩니다. 이 동작을 비활성화하려면(예: 종속 프로젝트가 단위 테스트 프로젝트인 경우) 참조된 프로젝트의 .csproj 또는 .vbproj 파일에서 PrivateAssets 특성을 설정하여 NuGet 패키지를 비공개로 표시합니다.

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

관련 콘텐츠

• Visual Studio의 코드 분석기 개요
• 코드 분석기 버그 제출
• 규칙 집합 사용
• 코드 분석 위반 표시 안 함
• 코드 분석에 대한 구성 옵션