다음을 통해 공유

.NET 소스 코드 분석 개요

  • 아티클

.NET Compiler Platform(Roslyn) 분석기는 C# 또는 Visual Basic 코드를 검사하여 코드 품질 및 스타일 문제를 확인합니다. .NET 5부터는 Roslyn 분석기가 .NET SDK에 포함되므로 별도로 설치할 필요가 없습니다. 프로젝트가 .NET 5 이상을 대상으로 하는 경우 기본적으로 코드 분석이 사용하도록 설정되어 있습니다. 프로젝트가 .NET Core, .NET Standard 또는 .NET Framework 같은 다른 .NET 구현을 대상으로 하는 경우 EnableNETAnalyzers 속성을 true로 설정하여 코드 분석을 사용하도록 수동으로 설정해야 합니다.

.NET 5 이상 SDK로 이동하지 않거나, SDK 스타일이 아닌 .NET Framework 프로젝트를 사용하거나, NuGet 패키지 기반 모델을 선호하는 경우 Microsoft.CodeAnalysis.NetAnalyzers NuGet 패키지에서도 분석기를 사용할 수 있습니다. 주문형 버전 업데이트에는 패키지 기반 모델을 사용하는 것이 좋습니다.

참고 항목

.NET 분석기는 대상 프레임워크에 독립적입니다. 즉, 프로젝트에서 특정 .NET 구현을 대상으로 지정하지 않아도 됩니다. 분석기는 .NET 5+를 대상으로 하는 프로젝트뿐 아니라 .NET Core 3.1 및 .NET Framework 4.7.2와 같은 이전 .NET 버전에서도 작동합니다. 그러나 EnableNETAnalyzers 속성을 사용하여 코드 분석을 사용하도록 설정하려면 프로젝트에서 프로젝트 SDK를 참조해야 합니다.

분석기에서 규칙 위반이 발생하는 경우 각 규칙이 구성된 방법에 따라 제안, 경고, 오류로 보고됩니다. 코드 분석 위반은 컴파일러 오류와 구별하기 위해 “CA” 또는 “IDE” 접두사를 사용하여 표시됩니다.

코드 품질 분석

‘코드 품질 분석’(“CAxxxx”) 규칙은 C# 또는 Visual Basic 코드를 검사하여 보안, 성능, 디자인, 기타 문제를 확인합니다. .NET 5 이상을 대상으로 하는 프로젝트의 경우 기본적으로 분석을 사용하도록 설정되어 있습니다. EnableNETAnalyzers 속성을 true로 설정하여 이전 버전의 .NET을 대상으로 하는 프로젝트에서 코드 분석을 사용하도록 설정할 수 있습니다. EnableNETAnalyzers를 false로 설정하여 프로젝트에서 코드 분석을 사용하지 않도록 설정할 수도 있습니다.

팁

Visual Studio를 사용하는 경우 여러 분석기 규칙에는 문제를 해결하는 데 적용할 수 있는 관련 코드 수정 사항이 있습니다. 코드 수정 사항은 전구 아이콘 메뉴에 표시됩니다.

사용 가능한 규칙

다음 규칙은 기본적으로 .NET 9에서 오류 또는 경고로 사용하도록 설정됩니다. 추가 규칙은 제안으로 사용하도록 설정됩니다.

진단 ID 범주 심각도 추가된 버전 설명
CA1416 상호 운용성 Warning .NET 5 플랫폼 호환성 유효성 검사
CA1417 상호 운용성 Warning .NET 5 P/Invokes에 대한 문자열 매개 변수에서 OutAttribute를 사용하지 않음
CA1418 상호 운용성 Warning .NET 6 유효한 플랫폼 문자열 사용
CA1420 상호 운용성 Warning .NET 7 사용하지 않도록 설정한 상태로 런타임 마샬링이 필요한 기능을 사용하면 런타임 예외가 발생합니다.
CA1422 상호 운용성 Warning .NET 7 플랫폼 호환성 유효성 검사
CA1831 성능 Warning .NET 5 해당하는 경우 문자열에 범위 기반 인덱서 대신 AsSpan 사용
CA1856 성능 오류 .NET 8 특성의 ConstantExpected 잘못된 사용
CA1857 성능 Warning .NET 8 매개 변수에 상수가 필요함
CA2013 안정성 Warning .NET 5 값 형식에 ReferenceEquals를 사용하지 않음
CA2014 안정성 Warning .NET 5 루프에서 stackalloc을 사용하지 않음
CA2015 안정성 Warning .NET 5 MemoryManager<T>에서 파생된 형식에 대해 종료자를 정의하지 않음
CA2017 안정성 Warning .NET 6 매개 변수 개수가 일치하지 않음
CA2018 안정성 Warning .NET 6 Buffer.BlockCopy에 대한 count 인수는 복사할 바이트 수를 지정해야 함
CA2021 안정성 Warning .NET 8 호환되지 않는 형식의 Enumerable.Cast<T> 또는 Enumerable.OfType<T>를 호출 안 함
CA2022 안정성 Warning .NET 9 을 사용하여 읽지 않도록 방지합니다. Stream.Read
CA2200 사용 Warning .NET 5 스택 정보를 유지하도록 다시 throw하십시오.
CA2247 사용 Warning .NET 5 TaskCompletionSource 생성자에 전달된 인수는 TaskContinuationOptions가 아니라 TaskCreationOptions 열거형이어야 함
CA2252 사용 오류 .NET 6 미리 보기 기능 옵트인
CA2255 사용 Warning .NET 6 ModuleInitializer 특성을 라이브러리에서 사용해서는 안 됨
CA2256 사용 Warning .NET 6 부모 인터페이스에 선언된 모든 멤버는 DynamicInterfaceCastableImplementation 특성 인터페이스에서 구현해야 함
CA2257 사용 Warning .NET 6 DynamicInterfaceCastableImplementationAttribute를 사용하여 인터페이스에 정의된 멤버는 static이어야 함
CA2258 사용 Warning .NET 6 Visual Basic에서 DynamicInterfaceCastableImplementation 인터페이스 제공은 지원되지 않음
CA2259 사용 Warning .NET 7 ThreadStatic은 정적 필드에만 영향을 줌
CA2260 사용 Warning .NET 7 올바른 형식 매개 변수 사용
CA2261 사용 Warning .NET 8 ConfigureAwaitOptions.SuppressThrowing을 Task<TResult>와 함께 사용 안 함
CA2264 사용 Warning .NET 9 nullable이 아닌 값을 다음으로 전달하지 마세요. ArgumentNullException.ThrowIfNull
CA2265 사용 Warning .NET 9 비교 Span<T> 안 함 null 또는 default

이러한 규칙의 심각도를 변경하여 사용하지 않도록 설정하거나 오류로 수준을 올릴 수 있습니다. 더 많은 규칙을 사용하도록 설정할 수도 있습니다.

추가 규칙 사용

‘분석 모드’는 사용하도록 설정된 규칙이 없거나 일부 또는 모든 규칙이 사용하도록 설정된 미리 정의된 코드 분석 구성을 나타냅니다. 기본 분석 모드(Default)에서는 적은 수의 규칙만 빌드 경고로 사용하도록 설정됩니다. 프로젝트 파일에서 <AnalysisMode> 속성을 설정하여 프로젝트의 분석 모드를 변경할 수 있습니다. 허용되는 값은 다음과 같습니다.

값 설명
None 모든 규칙이 사용하지 않도록 설정됩니다. 개별 규칙을 선택적으로 옵트인하여 사용하도록 설정할 수 있습니다.
Default 특정 규칙이 빌드 경고로 사용되고, 다른 특정 규칙이 Visual Studio IDE 추천으로 사용되며, 나머지는 사용하지 않도록 설정되는 기본 모드입니다.
Minimum Default 모드보다 더 공격적인 모드입니다. 빌드 적용에 강력하게 권장되는 특정 제안은 빌드 경고로 사용하도록 설정됩니다. 여기에 포함된 규칙을 확인하려면 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig 파일을 검사합니다.
Recommended Minimum 모드보다 더 적극적인 모드로, 더 많은 규칙이 빌드 경고로 사용하도록 설정됩니다. 여기에 포함된 규칙을 확인하려면 %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig 파일을 검사합니다.
All 모든 규칙이 빌드 경고로 사용하도록 설정됩니다*. 개별 규칙을 선택적으로 옵트아웃하여 사용하지 않도록 설정할 수 있습니다.

* 다음 규칙은 AnalysisMode를 All로 설정하거나 AnalysisLevel을 latest-all로 설정하면 사용하도록 설정되지 않습니다: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 및 코드 메트릭 분석기 규칙(CA1501, CA1502, CA1505, CA1506 및 CA1509). 이러한 레거시 규칙은 향후 버전에서 더 이상 사용되지 않을 수 있습니다. 그러나 dotnet_diagnostic.CAxxxx.severity = <severity> 항목을 사용하여 개별적으로 사용하도록 설정할 수 있습니다.

속성에 대한 <AnalysisLevel> 복합 값을 생략할 수도 <AnalysisMode> 있습니다. 예를 들어 <AnalysisLevel>latest-Recommended</AnalysisLevel> 값은 최신 릴리스에 대해 권장되는 규칙 집합을 사용하도록 설정합니다. 자세한 내용은 AnalysisLevel를 참조하세요.

사용할 수 있는 각 규칙의 기본 심각도와 Default 분석 모드에서 규칙을 사용할 수 있는지를 확인하려면 규칙 전체 목록을 참조하세요.

경고를 오류로 처리

프로젝트를 빌드할 때 -warnaserror 플래그를 사용하면 모든 코드 분석 경고도 오류로 처리됩니다. -warnaserror가 있을 경우 코드 품질 경고(CAxxxx)가 오류로 처리되지 않도록 하려면 프로젝트 파일에서 CodeAnalysisTreatWarningsAsErrors MSBuild 속성을 false로 설정할 수 있습니다.

<PropertyGroup>
  <CodeAnalysisTreatWarningsAsErrors>false</CodeAnalysisTreatWarningsAsErrors>
</PropertyGroup>

코드 분석 경고는 계속 표시되지만 빌드를 중단하지는 않습니다.

최신 업데이트

기본적으로 최신 버전의 .NET SDK로 업그레이드하면 최신 코드 분석 규칙 및 기본 규칙 심각도가 제공됩니다. 새 규칙을 사용하거나 사용하지 않도록 설정하지 않으려는 경우처럼 이 동작을 원하지 않는 경우 다음 방법 중 하나를 사용하여 재정의할 수 있습니다.

  • AnalysisLevel MSBuild 속성을 특정 값으로 설정하여 해당 집합에 대한 경고를 잠급니다. 최신 SDK로 업그레이드하는 경우 해당 경고에 대한 버그 수정이 계속 표시되지만 새 경고는 사용하도록 설정되지 않고 기존 경고는 사용하지 않도록 설정되지 않습니다. 예를 들어 .NET SDK 버전 8.0과 함께 제공되는 규칙 집합을 잠그려면 프로젝트 파일에 다음 항목을 추가합니다.

    <PropertyGroup>
  <AnalysisLevel>8.0</AnalysisLevel>
</PropertyGroup>

    팁

    AnalysisLevel 속성의 기본값은 latest입니다. 즉, 최신 버전의 .NET SDK로 이동하면 항상 최신 코드 분석 규칙이 제공된다는 의미입니다.

    자세한 내용 및 가능한 값 목록은 AnalysisLevel을 참조하세요.

  • Microsoft.CodeAnalysis.NetAnalyzers NuGet 패키지를 설치하여 .NET SDK 업데이트에서 규칙 업데이트를 분리합니다. .NET 5 이상을 대상으로 하는 프로젝트에서는 패키지를 설치하면 기본 제공 SDK 분석기가 꺼집니다. SDK에 NuGet 패키지 버전보다 최신인 분석기 어셈블리 버전이 포함되어 있으면 빌드 경고가 표시됩니다. 이 경고를 사용하지 않도록 설정하려면 _SkipUpgradeNetAnalyzersNuGetWarning 속성을 true로 설정합니다.

    참고 항목

    Microsoft.CodeAnalysis.NetAnalyzers NuGet 패키지를 설치하는 경우 EnableNETAnalyzers 속성을 프로젝트 파일이나 Directory.Build.props 파일에 추가하면 안 됩니다. NuGet 패키지를 설치하고 EnableNETAnalyzers 속성을 true로 설정하면 빌드 경고가 생성됩니다.

코드 스타일 분석

‘코드 스타일 분석’(“IDExxxx”) 규칙을 사용하면 코드베이스에서 일관된 코드 스타일을 정의하고 유지 관리할 수 있습니다. 기본 사용 설정은 다음과 같습니다.

  • 명령줄 빌드: 코드 스타일 분석은 기본적으로 명령줄 빌드의 모든 .NET 프로젝트에 대해 사용하지 않도록 설정됩니다.

    명령줄과 Visual Studio 내부에서 빌드 시 코드 스타일 분석을 사용하도록 설정할 수 있습니다. 코드 스타일 위반은 “IDE” 접두사를 사용하는 경고 또는 오류로 표시됩니다. 이렇게 하면 빌드 시 일관된 코드 스타일을 적용할 수 있습니다.

  • Visual Studio: 코드 스타일 분석은 빠른 작업을 리팩터링하는 코드로 Visual Studio 내의 모든 .NET 프로젝트에 대해 기본적으로 사용하도록 설정됩니다.

코드 스타일 분석 규칙의 전체 목록은 코드 스타일 규칙을 참조하세요.

빌드 시 사용

명령줄 및 Visual Studio에서 빌드할 때 코드 스타일 분석을 사용하도록 설정할 수 있습니다. 그러나 성능상의 이유로 몇 가지 코드 스타일 규칙은 Visual Studio IDE에서만 적용됩니다.

빌드 시 코드 스타일 분석을 사용하도록 설정하려면 다음 단계를 수행하세요.

  1. MSBuild 속성 EnforceCodeStyleInBuild를 true로 설정합니다.

  2. .editorconfig 파일에서 빌드 시 실행하려는 각 “IDE” 코드 스타일 규칙을 경고 또는 오류로 구성합니다. 예시:

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_diagnostic.IDE0040.severity = warning

    팁

    .NET 9부터는 옵션 형식을 사용하여 심각도를 지정하고 빌드 시 이를 준수하도록 할 수도 있습니다. 예시:

    [*.{cs,vb}]
# IDE0040: Accessibility modifiers required (escalated to a build warning)
dotnet_style_require_accessibility_modifiers = always:warning

    또는 기본적으로 전체 범주를 경고 또는 오류로 구성한 다음, 해당 범주에서 빌드 시 실행하지 않으려는 규칙을 선택적으로 해제할 수 있습니다. 예시:

    [*.{cs,vb}]

# Default severity for analyzer diagnostics with category 'Style' (escalated to build warnings)
dotnet_analyzer_diagnostic.category-Style.severity = warning

# IDE0040: Accessibility modifiers required (disabled on build)
dotnet_diagnostic.IDE0040.severity = silent

경고 표시 안 함

규칙 위반을 표시하지 않는 한 가지 방법은 EditorConfig 파일에서 해당 규칙 ID에 대한 심각도 옵션을 none으로 설정하는 것입니다. 예시:

dotnet_diagnostic.CA1822.severity = none

경고를 표시하지 않는 다른 방법 및 자세한 내용은 코드 분석 경고를 표시하지 않는 방법을 참조하세요.

타사 분석기

공식 .NET 분석기 외에 StyleCop, Roslynator, XUnit Analyzers, Sonar Analyzer 등의 타사 분석기도 설치할 수 있습니다.

참고 항목