.NET kaynak kodu analizine genel bakış

  • Makale

.NET derleyici platformu (Roslyn) çözümleyicileri C# veya Visual Basic kodunuzu kod kalitesi ve stil sorunları açısından inceler. .NET 5'den başlayarak, bu çözümleyiciler .NET SDK'sına eklenir ve bunları ayrı olarak yüklemeniz gerekmez. Projeniz .NET 5 veya üzerini hedeflediyse, kod analizi varsayılan olarak etkinleştirilir. Projeniz .NET Core, .NET Standard veya .NET Framework gibi farklı bir .NET uygulamasını hedef alıyorsa, EnableNETAnalyzers özelliğini olarak ayarlayarak kod analizini trueel ile etkinleştirmeniz gerekir.

.NET 5+ SDK'ya geçmek istemiyorsanız, SDK stilinde olmayan bir .NET Framework projeniz varsa veya NuGet paket tabanlı bir model tercih ediyorsanız çözümleyiciler Microsoft.CodeAnalysis.NetAnalyzers NuGet paketinde de kullanılabilir. İsteğe bağlı sürüm güncelleştirmeleri için paket tabanlı bir model tercih edebilirsiniz.

Not

.NET çözümleyicileri target-framework agnostic'tir. Başka bir ifadeyle, projenizin belirli bir .NET uygulamasını hedeflemesi gerekmez. Çözümleyiciler. .NET 5+ ve .NET Core 3.1 ve .NET Framework 4.7.2 gibi önceki .NET sürümlerini hedefleyen projeler için çalışır. Ancak EnableNETAnalyzers özelliğini kullanarak kod analizini etkinleştirmek için projenizin bir proje SDK'sına başvurması gerekir.

Kural ihlalleri bir çözümleyici tarafından bulunursa, her kuralın nasıl yapılandırıldığına bağlı olarak öneri, uyarı veya hata olarak bildirilir. Kod çözümleme ihlalleri, derleyici hatalarından ayırt etmek için "CA" veya "IDE" ön ekiyle birlikte görünür.

Kod kalitesi analizi

Kod kalitesi analizi ("CAxxxx") kuralları C# veya Visual Basic kodunuzu güvenlik, performans, tasarım ve diğer sorunlar açısından inceler. Analiz, .NET 5 veya üzerini hedefleyen projeler için varsayılan olarak etkindir. EnableNETAnalyzers özelliğini olarak ayarlayarak önceki .NET sürümlerini hedefleyen projelerde kod analizini trueetkinleştirebilirsiniz. olarak ayarlayarak EnableNETAnalyzers projeniz için kod analizini falsede devre dışı bırakabilirsiniz.

İpucu

Visual Studio kullanıyorsanız, birçok çözümleyici kuralının sorunu düzeltmek için uygulayabileceğiniz ilişkili kod düzeltmeleri vardır. Ampul simgesi menüsünde kod düzeltmeleri gösterilir.

Etkin kurallar

Aşağıdaki kurallar varsayılan olarak .NET 8'de hata veya uyarı olarak etkinleştirilir. Ek kurallar öneri olarak etkinleştirilir.

Tanılama Kimliği Kategori Önem Sürüm eklendi Açıklama
CA1416 Birlikte çalışabilirlik Uyarı .NET 5 Platform uyumluluğunu doğrula
CA1417 Birlikte çalışabilirlik Uyarı .NET 5 P/Invokes için dize parametrelerinde kullanmayın OutAttribute
CA1418 Birlikte çalışabilirlik Uyarı .NET 6 Geçerli platform dizesini kullanma
CA1420 Birlikte çalışabilirlik Uyarı .NET 7 Devre dışı bırakıldığında çalışma zamanı hazırlama gerektiren özelliklerin kullanılması çalışma zamanı özel durumlarına neden olur
CA1422 Birlikte çalışabilirlik Uyarı .NET 7 Platform uyumluluğunu doğrula
CA1831 Performans Uyarı .NET 5 Uygun olduğunda dize için aralık tabanlı dizin oluşturucular yerine kullanın AsSpan
CA1856 Performans Hata .NET 8 Yanlış öznitelik kullanımı ConstantExpected
CA1857 Performans Uyarı .NET 8 parametresi için bir sabit bekleniyor
CA2013 Güvenilirlik Uyarı .NET 5 Değer türleriyle kullanmayın ReferenceEquals
CA2014 Güvenilirlik Uyarı .NET 5 Döngüler içinde kullanmayın stackalloc
CA2015 Güvenilirlik Uyarı .NET 5 Türetilen türler için sonlandırıcıları tanımlama MemoryManager<T>
CA2017 Güvenilirlik Uyarı .NET 6 Parametre sayısı uyuşmazlığı
CA2018 Güvenilirlik Uyarı .NET 6 öğesinin countBuffer.BlockCopy bağımsız değişkeni, kopyalanacak bayt sayısını belirtmelidir
CA2021 Güvenilirlik Uyarı .NET 8 Uyumlu olmayan türleri çağırmayın Enumerable.Cast<T> veya Enumerable.OfType<T>
CA2200 Kullanım Uyarı .NET 5 Yığın ayrıntılarını korumak için yeniden fırlatın
CA2247 Kullanım Uyarı .NET 5 Oluşturucuya TaskCompletionSource geçirilen bağımsız değişken, yerine sabit listesi olmalıdır TaskCreationOptionsTaskContinuationOptions
CA2252 Kullanım Hata .NET 6 Önizleme özelliklerini kabul etme
CA2255 Kullanım Uyarı .NET 6 ModuleInitializer Öznitelik kitaplıklarda kullanılmamalıdır
CA2256 Kullanım Uyarı .NET 6 Üst arabirimlerde bildirilen tüm üyelerin -attributed arabiriminde bir DynamicInterfaceCastableImplementationuygulaması olmalıdır
CA2257 Kullanım Uyarı .NET 6 ile DynamicInterfaceCastableImplementationAttribute bir arabirimde tanımlanan üyeler static
CA2258 Kullanım Uyarı .NET 6 Visual Basic'te arabirim DynamicInterfaceCastableImplementation sağlama desteklenmiyor
CA2259 Kullanım Uyarı .NET 7 ThreadStatic yalnızca statik alanları etkiler
CA2260 Kullanım Uyarı .NET 7 Doğru tür parametresini kullanma
CA2261 Kullanım Uyarı .NET 8 ile kullanmayın ConfigureAwaitOptions.SuppressThrowingTask<TResult>

Bu kuralları devre dışı bırakmak veya hatalara yükseltmek için önem derecesini değiştirebilirsiniz. Ayrıca daha fazla kuralı etkinleştirebilirsiniz.

Ek kuralları etkinleştirme

Çözümleme modu , hiçbir kuralın, bazılarının veya tüm kuralların etkinleştirilmediği önceden tanımlanmış bir kod analizi yapılandırmasına başvurur. Varsayılan çözümleme modunda (Default ), derleme uyarısı olarak yalnızca az sayıda kural etkinleştirilir. Proje dosyasında özelliğini ayarlayarak <AnalysisMode> projenizin çözümleme modunu değiştirebilirsiniz. İzin verilebilen değerler şunlardır:

Value Açıklama
None Tüm kurallar devre dışı bırakılır. Kuralları etkinleştirmek için tek tek kuralları seçmeli olarak kabul edebilirsiniz.
Default Belirli kuralların derleme uyarıları olarak etkinleştirildiği, visual studio IDE önerileri olarak belirli kuralların etkinleştirildiği ve kalanların devre dışı bırakıldığı varsayılan mod.
Minimum Moddan daha Default agresif mod. Derleme zorlaması için kesinlikle önerilen bazı öneriler, derleme uyarıları olarak etkinleştirilir. Bunun hangi kuralları içerdiğini görmek için %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_minimum.editorconfig dosyasını inceleyin.
Recommended Derleme uyarıları olarak daha fazla kuralın etkinleştirildiği moddan daha Minimum agresif mod. Bunun hangi kuralları içerdiğini görmek için %ProgramFiles%/dotnet/sdk/[version]/Sdks/Microsoft.NET.Sdk/analyzers/build/config/analysislevel_[level]_recommended.editorconfig dosyasını inceleyin.
All Tüm kurallar derleme uyarıları* olarak etkinleştirilir. Kuralları devre dışı bırakmak için tek tek kuralları seçmeli olarak geri çevirebilirsiniz.

* Şu kurallar şu şekilde ayarlanarak veya ayarlanarak AllAnalysisModeAnalysisLevellatest-alletkinleştirilmez: CA1017, CA1045, CA1005, CA1014, CA1060, CA1021 ve kod ölçümleri çözümleyicisi kuralları (CA1501, CA1502, CA1505, CA1506 ve CA1509). Bu eski kurallar gelecekteki bir sürümde kullanım dışı bırakılmış olabilir. Ancak, yine de bir dotnet_diagnostic.CAxxxx.severity = <severity> giriş kullanarak bunları tek tek etkinleştirebilirsiniz.

.NET 6'dan başlayarak, özelliği için <AnalysisLevel> bileşik değer yerine atlayabilirsiniz<AnalysisMode>. Örneğin, aşağıdaki değer en son sürüm için önerilen kural kümesini etkinleştirir: <AnalysisLevel>latest-Recommended</AnalysisLevel>. Daha fazla bilgi için bkz. AnalysisLevel.

Kullanılabilir her kuralın varsayılan önem derecesini ve kuralın analiz modunda etkinleştirilip etkinleştirilmediğini Default bulmak için kuralların tam listesine bakın.

Uyarıları hata olarak değerlendirin

Projelerinizi oluştururken bayrağını -warnaserror kullanırsanız, tüm kod analizi uyarıları da hata olarak değerlendirilir. Kod kalitesi uyarılarının (CAxxxx) varlığında -warnaserrorhata olarak değerlendirilmesini istemiyorsanız, proje dosyanızda MSBuild özelliğini olarak false ayarlayabilirsinizCodeAnalysisTreatWarningsAsErrors.

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

Kod analizi uyarılarını görmeye devam edersiniz, ancak bunlar derlemenizi bozmaz.

En son güncelleştirmeler

Varsayılan olarak, .NET SDK'nın daha yeni sürümlerine yükselttikçe en son kod analizi kurallarını ve varsayılan kural önem derecelerini alırsınız. Örneğin, bu davranışı istemiyorsanız, yeni kuralların etkinleştirilmediğinden veya devre dışı bırakılmadığından emin olmak istiyorsanız, bunu aşağıdaki yollardan biriyle geçersiz kılabilirsiniz:

  • Uyarıları bu AnalysisLevel kümeye kilitlemek için MSBuild özelliğini belirli bir değere ayarlayın. Daha yeni bir SDK'ya yükselttiğiniz zaman, bu uyarılar için hata düzeltmeleri almaya devam edersiniz, ancak yeni uyarı etkinleştirilmez ve mevcut uyarılar devre dışı bırakılmaz. Örneğin, kural kümesini .NET SDK'sının 5.0 sürümüyle birlikte gelenlere kilitlemek için proje dosyanıza aşağıdaki girdiyi ekleyin.

    <PropertyGroup>
  <AnalysisLevel>5.0</AnalysisLevel>
</PropertyGroup>

    İpucu

    özelliğinin AnalysisLevel varsayılan değeri olur. latestBu, .NET SDK'sının daha yeni sürümlerine geçiş sırasında her zaman en son kod çözümleme kurallarını almanız anlamına gelir.

    Daha fazla bilgi edinmek ve olası değerlerin listesini görmek için bkz . AnalysisLevel.

  • Kural güncelleştirmelerini .NET SDK güncelleştirmelerinden ayrıştırmak için Microsoft.CodeAnalysis.NetAnalyzers NuGet paketini yükleyin. .NET 5+ hedeflenen projeler için paketin yüklenmesi yerleşik SDK çözümleyicilerini kapatır. SDK, NuGet paketinden daha yeni bir çözümleyici derleme sürümü içeriyorsa bir derleme uyarısı alırsınız. Uyarıyı devre dışı bırakmak için özelliğini olarak trueayarlayın_SkipUpgradeNetAnalyzersNuGetWarning.

    Not

    Microsoft.CodeAnalysis.NetAnalyzers NuGet paketini yüklerseniz, EnableNETAnalyzers özelliğini proje dosyanıza veya Bir Directory.Build.props dosyasına eklememelisiniz. NuGet paketi yüklendiğinde ve EnableNETAnalyzers özelliği olarak trueayarlandığında bir derleme uyarısı oluşturulur.

Kod stili çözümleme

Kod stili analizi ("IDExxxx") kuralları, kod tabanınızda tutarlı kod stili tanımlamanızı ve korumanızı sağlar. Varsayılan etkinleştirme ayarları şunlardır:

Kod stili çözümleme kurallarının tam listesi için bkz . Kod stili kuralları.

Derlemede etkinleştir

.NET 5 SDK ve sonraki sürümleriyle, komut satırından ve Visual Studio'da derleme yaparken kod stili analizi etkinleştirebilirsiniz. (Ancak, performans nedenleriyle, birkaç kod stili kuralı yalnızca Visual Studio IDE'de geçerli olmaya devam eder.)

Derlemede kod stili analizini etkinleştirmek için şu adımları izleyin:

  1. MSBuild özelliğini EnforceCodeStyleInBuild olarak trueayarlayın.

  2. Bir .editorconfig dosyasında, derlemede bir uyarı veya hata olarak çalıştırmak istediğiniz her "IDE" kod stili kuralını yapılandırın . Örneğin:

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

    İpucu

    .NET 9'dan başlayarak, bir önem derecesi belirtmek ve derleme zamanında dikkate alınması için seçenek biçimini de kullanabilirsiniz. Örneğin:

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

    Alternatif olarak, bir kategorinin tamamını varsayılan olarak bir uyarı veya hata olarak yapılandırabilir ve sonra bu kategorideki derlemede çalıştırmak istemediğiniz kuralları seçmeli olarak kapatabilirsiniz. Örneğin:

    [*.{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

Uyarıyı gizleme

Kural ihlalini gizlemenin bir yolu, bir EditorConfig dosyasında bu kural kimliği none için önem derecesi seçeneğini ayarlamaktır. Örneğin:

dotnet_diagnostic.CA1822.severity = none

Daha fazla bilgi ve uyarıları gizlemenin diğer yolları için bkz . Kod analizi uyarılarını gizleme.

GitHub Eylemi olarak kod analizi çalıştırma

dotnet/code-analysis GitHub Action, sürekli tümleştirmenin (CI) bir parçası olarak .NET kod çözümleyicilerini çevrimdışı modda çalıştırmanıza olanak tanır. Daha fazla bilgi için bkz . .NET kod analizi GitHub Eylemi.

Üçüncü taraf çözümleyiciler

Resmi .NET çözümleyicilerine ek olarak StyleCop, Roslynator, XUnit Analyzers ve Sonar Analyzer gibi üçüncü taraf çözümleyicileri de yükleyebilirsiniz.

Ayrıca bkz.