Roslyn çözümleyicisi kurallarını özelleştirme

Her Roslyn çözümleyici kuralının veya tanılamanın, projeniz için özelleştirebileceğiniz varsayılan önem derecesi ve gizleme durumu vardır. Bu makale çözümleyici önem derecelerini ayarlamayı ve çözümleyici ihlallerini engellemeyi kapsar.

Ciddiyet seviyeleri

Çözümleyici kurallarının önem derecesini bir EditorConfig dosyasında ve ampul menüsünden yapılandırabilirsiniz.

Aşağıdaki tabloda, tanılama için yapılandırabileceğiniz farklı önem derecesi seçenekleri gösterilmektedir:

Önem Derecesi (Çözüm Gezgini)	Önem Derecesi (EditorConfig dosyası)	Derleme zamanı davranışı	Düzenleyici davranışı
Hata	error	İhlaller Hata Listesi penceresindeki Hata sekmesinde ve komut satırı derleme çıkışında görünür ve derlemelerin başarısız olmasına neden olur.	Sorunlu kodun altı kırmızı dalgalı çizgiyle çizilir ve kaydırma çubuğunda küçük bir kırmızı kutuyla işaretlenir.
Uyarı	warning	İhlaller Hata Listesi penceresindeki Uyarı sekmesinde ve komut satırı derleme çıkışında görünür, ancak derlemelerin başarısız olmasına neden olmaz.	Sorunlu kod yeşil dalgalı çizgi ile altı çizilir ve kaydırma çubuğunda küçük bir yeşil kutu ile işaretlenir.
Öneri	suggestion	İhlaller Hata Listesipenceresindeki İleti sekmesinde görünür, ancak komut satırı derleme çıkışında görünmez.	Etkilenen kod gri dalgalı bir çizgiyle altı çizilir ve kaydırma çubuğunda küçük gri bir kutuyla işaretlenir.
Sessiz	silent	Kullanıcı tarafından görünmez.	Kullanıcı tarafından görünmez, ancak tanılama IDE tanılama altyapısına bildirilir.
Hiç kimse	none	Tamamen bastırıldı.	Tamamen bastırıldı.
Varsayılan	default	Kuralın varsayılan önem derecesine karşılık gelir. Kuralın varsayılan değerini belirlemek için Özellikler penceresini görüntüleyin.	Kuralın varsayılan önem derecesine karşılık gelir.

Kural ihlallerini görüntüleme

Çözümleyici herhangi bir çözümleyici kuralı ihlali bulursa, bunları Hata Listesi penceresinde ve kod düzenleyicisinde raporlar.

Aşağıdaki ekran görüntüsünde Hata Listesi penceresinde bildirilen kural ihlalleri gösterilmektedir. Hata listesinde bildirilen çözümleyici ihlalleri kuralın önem düzeyi ayarıyla eşleşmektedir:

Çözümleyici kuralı ihlalleri de kod düzenleyicisinde sorunlu kodun altında dalgalı çizgiler olarak görünür. Örneğin, aşağıdaki ekran görüntüsünde üç ihlal gösterilmektedir: bir hata (kırmızı dalgalı çizgi), bir uyarı (yeşil dalgalı çizgi) ve bir öneri (üç gri nokta):

Birçok tanılamada kural ihlalini düzeltmek için uygulayabileceğiniz bir veya daha fazla ilişkili kod düzeltmesi vardır. Kod düzeltmeleri ampul simgesi menüsünde diğer Hızlı İşlem türleriyle birlikte gösterilir. Kod düzeltmeleri hakkında daha fazla bilgi için bkz. Yaygın Hızlı Eylemler.

Önem derecesi düzeylerini yapılandırma

Aşağıdaki yöntemlerden herhangi birini kullanarak kural önem derecesini ayarlayabilirsiniz:

• EditorConfig
• Ampul menüsü
• Çözüm Gezgini

Sessiz ve Hiçbiri önem derecesi karşılaştırması

Silent varsayılan olarak etkinleştirilen önem derecesi kuralları devre dışı veya None önem derecesi kurallarından farklıdır:

• Bir kod düzeltmesi Silent önem derecesindeki bir kural için kaydedilmişse, Visual Studio gizli teşhis kullanıcı tarafından görülmese bile, kod düzeltmesini ampul simgesiyle kod düzenleme eylemi olarak sunar. Önem derecesi kuralı olarak Nonedevre dışı bırakılırsa kod düzeltmesi sunulmaz.
• Bir EditorConfig dosyasında aynı anda birden çok çözümleyici kuralının önem derecesini ayarlayan girişler, önem derecesi kurallarını toplu olarak yapılandırabilirSilent. None önem derecesi kuralları bu şekilde yapılandırılamaz. Bunun yerine, her kural kimliği için bir EditorConfig dosyasında önem derecesini ayarlayan girdiler aracılığıyla yapılandırılmaları gerekir.

EditorConfig dosyasında kural önem derecesini ayarlama

EditorConfig dosyaları Visual Studio 2019 sürüm 16.3 ve sonraki sürümlerde kullanılabilir.

EditorConfig dosyasında kuralın önem derecesini ayarlamak, bir kural kümesinde veya Çözüm Gezgini'nde ayarlanan önem derecelerine göre önceliklidir. Önem derecesini EditorConfig dosyasında el ile veya bir ihlalin yanında görünen ampul aracılığıyla otomatik olarak yapılandırabilirsiniz.

EditorConfig dosyasında kural önem derecesini el ile yapılandırma

Kural önem derecesini yapılandırmak için şu adımları izleyin:

1. Henüz yoksa projenize bir EditorConfig dosyası ekleyin.

2. İlgili dosya uzantısının altına yapılandırmak istediğiniz her kural için bir girdi ekleyin.

   Örneğin, C# dosyaları için CA1822 önem derecesini error ayarlamak için giriş aşağıdaki gibidir:

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

3. Bir EditorConfig dosyasındaki her tanılama kuralı kimliği için kural önem derecesini aşağıdaki söz dizimiyle ayarlayabilirsiniz:

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

4. IDE kod stili çözümleyiciler için, bunları farklı bir söz dizimi kullanarak bir EditorConfig dosyasında da yapılandırabilirsiniz.

   Örneğin, dotnet_style_qualification_for_field = false:suggestion. Ancak, dotnet_diagnostic söz dizimini kullanarak bir önem derecesi ayarlarsanız, bu öncelikli hale gelir. Daha fazla bilgi için bkz. EditorConfig için dil kuralları.

EditorConfig dosyasında birden çok çözümleyici kuralının önem derecesini aynı anda ayarlama

EditorConfig dosyasında aynı anda birden çok çözümleyici kuralı ayarlama özelliği Visual Studio 2019 sürüm 16.5 ve sonraki sürümlerde kullanılabilir.

Belirli bir çözümleyici kuralları kategorisi için veya EditorConfig dosyasında tek bir giriş içeren tüm çözümleyici kuralları için önem derecesini ayarlayabilirsiniz:

• Çözümleyici kuralları kategorisi için kural önem derecesini ayarlayın:

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

• Tüm çözümleyici kuralları için kural önem derecesini ayarlayın:

  dotnet_analyzer_diagnostic.severity = <severity>

Aynı anda birden çok çözümleyici kuralı yapılandıran girişler yalnızca varsayılan olarak etkinleştirilen kurallar için geçerlidir. Çözümleyici paketinde varsayılan olarak devre dışı olarak işaretlenmiş çözümleyici kuralları, açık dotnet_diagnostic.<rule ID>.severity = <severity> girişler aracılığıyla etkinleştirilmelidir.

Belirli bir kural kimliği için geçerli olan birden çok girdiniz varsa, geçerli giriş için öncelik sırası aşağıdaki gibidir:

• Kimliğine göre tek bir kural için ciddiyet derecesi girdisi, bir kategorinin ciddiyet derecesi girdisinden daha önceliklidir.
• Bir kategori için önem derecesi girdisi, tüm çözümleyici kuralları için yapılan girdiden daha önceliklidir.

CA1822'nin bir performans kuralı olduğu aşağıdaki EditorConfig örneğini göz önünde bulundurun:

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

Bu örnekte, üç girdi de CA1822 performans kuralına uygulanır. Ancak, belirtilen öncelik kurallarını kullanarak, ilk kural kimliği tabanlı önem derecesi girdisi sonraki girdilerden önceliklidir. Bu örnekte, CA1822'nin etkin önem derecesi errorvardır. Kalan performans kurallarının önem derecesi warning ciddiyetindedir. Performans kuralları olmayan çözümleyici kurallarının önem derecesi suggestion'dir.

Ampul menüsünden kural önem derecesini ayarlama

Visual Studio, Hızlı Eylemler ampul menüsünden kuralın önem derecesini yapılandırmak için kullanışlı bir yol sağlar. Şu adımları izleyin:

1. Bir ihlal oluştuktan sonra, düzenleyicideki ihlal işaretli dalgalı çizginin üzerine gelin ve bekleyin, ardından Ampul menüsünü açmak için Olası düzeltmeleri göster'i seçin. Alternatif olarak, imlecinizi çizginin üzerine getirin ve Ctrl tuşuna+ (nokta) basın.

2. Ampul menüsünde, değişikliğin önizlemesi için önem derecesi düzeyinin üzerine gelin ve ardından önem derecesini aşağıdaki seçeneklere göre yapılandırın:

   • < Kural kimliği> önem derecesini yapılandırın. Belirli bir kural için önem derecesini ayarlayın.

   • Tüm <stil> çözümleyicileri için önem derecesini yapılandırın. Belirli bir kural kategorisindeki tüm kuralların önem derecesini ayarlayın.

   • Tüm çözümleyiciler için önem derecesini yapılandırın. Çözümleyici kurallarının tüm kategorileri için önem derecesini ayarlayın.

     Aşağıdaki örnekte, Sorunları gizle veya yapılandır>< seçin.

     

3. Önem derecesi seçeneklerinden birini seçin.

   

   Visual Studio, önizleme kutusunda gösterildiği gibi kuralı istenen önem düzeyine yapılandırmak için EditorConfig dosyasına bir girdi ekler.

   Projede henüz bir EditorConfig dosyanız yoksa Visual Studio sizin için bir tane oluşturur.

Çözüm Gezgini'nden kural önem derecesini ayarlama

Çözüm Gezgini'nden kural önem derecesini ayarlamak için şu adımları izleyin:

1. Çözüm Gezgini'nde Başvurular>Çözümleyiciler (veya .NET Core projeleri için Bağımlılıklar>Çözümleyiciler) genişletin.

2. Önem derecesini ayarlamak istediğiniz kuralı içeren derlemeyi genişletin.

3. Kurala sağ tıklayın ve Önem derecesini ayarla'yı seçin. Bağlam menüsünde önem derecesi seçeneklerinden birini seçin.

   Visual Studio, kuralı istenen düzeye yapılandırmak için EditorConfig dosyasına bir girdi ekler. Projeniz EditorConfig dosyası yerine kural kümesi dosyası kullanıyorsa, önem derecesi girdisi kural kümesi dosyasına eklenir.

   Projede henüz bir EditorConfig dosyanız veya kural kümesi dosyanız yoksa Visual Studio sizin için yeni bir EditorConfig dosyası oluşturur.

Çözüm Gezgini'nden çözümleyicileri ve tanılamaları görüntüleme

Çözüm Gezgini'nden çözümleyici tanılamalarının büyük bir kısmını özelleştirebilirsiniz. NuGet paketi olarak bir çözümleyici yüklerseniz Çözüm Gezgini'ndeki Başvurular düğümü (veya .NET Core projeleri için Bağımlılıklar düğümü) altında bir Çözümleyiciler düğümü görüntülenir. Çözümleyicileri ve tanılamaları görüntülemek için şu adımları izleyin:

1. Çözüm Gezgini'nde projenizi genişletin, Başvurular veya Bağımlılıklar'ı genişletin ve çözümleyiciler'i genişletin. Derlemedeki tanılamaları görmek için çözümleyici derlemelerinden birini genişletin.

   Her tanılamanın yanındaki simge önem derecesini gösterir:

   • xdaire içinde hatanın önem derecesini gösterir
   • ! içindeki üçgen, Uyarı seviyesini gösterir.
   • idüz bir daire içinde önerinin önem derecesini gösterir
   • Noktalı bir daire içindeki i, Sessiz önem derecesini gösterir.
   • Düz daire içinde aşağı doğru işaret eden ok Yok'un önem derecesini gösterir

   

2. Tanılamanın açıklaması ve varsayılan önem derecesi dahil olmak üzere özelliklerini görüntülemek için tanılamaya sağ tıklayın ve özellikler'i seçin. Alternatif olarak, tanılamayı seçin ve ardından Alt+Enter tuşuna basın.

   Özellikleri penceresi görüntülenir.

   

3. Özellikler penceresinde varsayılan önem derecesi gibi kod stili kurallarının (IDE öneki) özelliklerini görüntülemek için EnforceCodeStyleInBuild özelliğini olarak trueayarlayın.

4. Bir tanılama için çevrimiçi belgeleri görüntülemek üzere tanılama üzerine sağ tıklayın ve ardından Yardımı Görüntüle'yi seçin.

Mevcut bir kural kümesi dosyasını EditorConfig dosyasına dönüştürme

Visual Studio 2019 sürüm 16.5 ve sonraki sürümlerinde kural kümesi dosyaları, yönetilen kod için çözümleyici yapılandırması için EditorConfig dosyaları yerine kullanım dışı bırakılmıştır. EditorConfig dosyaları daha esnek olup Visual Studio IDE kod stili seçenekleri de dahil olmak üzere hem çözümleyici kuralı önem derecelerini hem de çözümleyici seçeneklerini yapılandırmanıza olanak sağlar. Çözümleyici kuralları önem derecesi yapılandırması için Visual Studio araçları artık kural kümesi dosyaları yerine EditorConfig dosyalarıyla çalışacak şekilde iyileştirildiğinden, kural kümesi dosyalarını kullanmaya devam eden mevcut projeleri dönüştürmeniz tavsiye edilir.

Mevcut kural kümesi dosyanızı editorconfig dosyasına dönüştürdüğünüzde, deponuzun köküne veya çözüm klasörüne kaydedin. Bunun yapılması, bu dosyadaki önem derecesi ayarlarının sırasıyla deponun veya çözümün tamamına otomatik olarak uygulanmasını sağlar.

Kural kümesi düzenleyicisini veya komut satırını kullanarak mevcut bir kural kümesi dosyasını EditorConfig dosyasına dönüştürebilirsiniz.

Uyarı

.NET Core ve .NET 5+ projeleri, Çözüm Gezgini'ndeki kural kümeleri için menü komutlarını desteklemez; örneğin , Etkin Kural Kümesini Aç. .NET Core veya .NET 5+ projesi için varsayılan olmayan bir kural kümesi belirtmek için CodeAnalysisRuleSet özelliğini proje dosyasına el ile ekleyin. Kural kümesi düzenleyicisinde kural kümesi içindeki kuralları yapılandırmaya devam edebilirsiniz.

Kural kümesi düzenleyicisini kullanmak için şu adımları izleyin. Projeniz özellik değeri için CodeAnalysisRuleSet zaten belirli bir kural kümesi dosyası kullanıyorsa, kural kümesi düzenleyicisinden eşdeğer bir EditorConfig dosyasına dönüştürebilirsiniz:

1. Çözüm Gezgini'nde kural kümesi dosyasına çift tıklayın.

   Kural kümesi dosyası, üst kısmında tıklanabilir bir bilgi çubuğu bulunan kural kümesi düzenleyicisinde açılır.

   

2. Kural kümesi düzenleyici dosyasını geçirmek için bilgi çubuğu bağlantısını seçin.

3. Farklı Kaydet iletişim kutusunda EditorConfig dosyasını oluşturmak istediğiniz dizini seçin ve ardından Kaydet'i seçin.

   Oluşturulan EditorConfig düzenleyicide açılır. Ayrıca, MSBuild özelliği CodeAnalysisRuleSet artık özgün kural kümesi dosyasına başvurmaması için proje dosyasında güncelleştirilir.

   Özgün kural kümesi dosyası projeden kaldırılabilir.

   Uyarı

   .NET Framework projesinde, varsayılan kural kümesi dosyası projeden geçirilemiyor veya kaldırılamıyor.

Komut satırını kullanmak için şu adımları izleyin:

1. Microsoft.CodeAnalysis.RulesetToEditorconfigConverter NuGet paketini yükleyin.

2. RulesetToEditorconfigConverter.exe yüklenmiş paketten yürütülerek, kural kümesi dosyasına ve EditorConfig dosyasına giden yolları komut satırı bağımsız değişkenleri olarak kullanır.

   Örneğin:

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

Aşağıdaki örnekte EditorConfig dosyasına dönüştürülecek bir kural kümesi dosyası gösterilmektedir:

<?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>

Aşağıdaki örnekte, dönüştürmeden sonra elde edilen EditorConfig dosyası gösterilmektedir:

# 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

Oluşturulan kodu yapılandırma

Çözümleyiciler bir projedeki kaynak dosyalarda çalışır ve buldukları ihlalleri bildirir. Ancak, bu ihlaller sistem tarafından oluşturulan dosyalar için kullanışlı değildir. Örnek olarak tasarımcı tarafından oluşturulan kod dosyaları, derleme sistemi tarafından oluşturulan geçici kaynak dosyalar gibi kod dosyaları verilebilir. Bu tür dosyalar için kullanıcılar dosyaları el ile düzenleyemez ve ihlalleri düzeltme konusunda endişelenmez.

Bu nedenle, çözümleyici sürücüsü varsayılan olarak yalnızca belirli adlara, dosya uzantılarına veya otomatik olarak oluşturulan dosya üst bilgilerine sahip dosyaları oluşturulan kod dosyaları olarak inceler. Örneğin, .designer.cs veya .generated.cs ile biten bir dosya adı oluşturulan kod olarak kabul edilir. Ancak, bu buluşsal yöntemler kullanıcının kaynak kodunda özel olarak oluşturulan tüm kod dosyalarını tanımlayamayabilir.

Visual Studio 2019 sürüm 16.5 ve sonraki sürümlerinde, son kullanıcılar belirli dosya ve klasörleri bir EditorConfig dosyasında oluşturulan kod olarak işlenecek şekilde yapılandırabilir.

Böyle bir yapılandırma eklemek için şu adımları izleyin:

1. Projeniz için henüz bir EditorConfig dosyanız yoksa bir tane ekleyin.

2. generated_code = true | false Belirli dosya ve klasörler için girdiyi ekleyin. Örneğin, adı oluşturulan kod olarak biten .MyGenerated.cs tüm dosyaları işlemek için şu girişi kullanın:

   [*.MyGenerated.cs]
   generated_code = true
   

İhlalleri önleme

Çeşitli yöntemleri kullanarak kural ihlallerini gizleyebilirsiniz. Bilgi için bkz . Kod analizi ihlallerini engelleme.

Komut satırı kullanımı

Projenizi komut satırında oluşturduğunuzda, aşağıdaki koşullar karşılanırsa derleme çıkışında kural ihlalleri görüntülenir:

• Çözümleyiciler .NET SDK'sı veya NuGet paketi olarak yüklenir ve .vsix uzantısı olarak yüklenmez.

  .NET SDK kullanılarak yüklenen çözümleyiciler için çözümleyicileri etkinleştirmeniz gerekebilir. Kod stilleri için, bir MSBuild özelliği ayarlayarak derlemelerde kod stillerini de zorunlu kılabilirsiniz .

• Projenin kodunda bir veya daha fazla kural ihlal edilir.

• İhlal edilen kuralın önem düzeyi uyarı olarak ayarlanır; bu durumda ihlaller derlemenin başarısız olmasına veya hataya neden olmaz ve bu durumda ihlaller derlemenin başarısız olmasına neden olur.

Derleme çıktısının ayrıntılı olması, kural ihlallerinin gösterilmesini etkilemez. Düşük ayrıntı düzeyi ile çalışılsa bile, kural ihlalleri derleme çıktısında görünür.

Alışkınsanız, komut satırından ya FxCopCmd.exe kullanarak ya da RunCodeAnalysis bayrağıyla msbuild aracılığıyla eski analizleri çalıştırmaya, bunun yerine kod çözümleyicileriyle yapabilirsiniz.

msbuild kullanarak projenizi oluştururken komut satırında çözümleyici ihlallerini görmek için şuna benzer bir komut çalıştırın:

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

Aşağıdaki ekran görüntüsünde, çözümleyici kuralı ihlali içeren bir proje oluşturma işleminin komut satırı derleme çıkışı gösterilmektedir:

Bağımlı projeler

.NET Core projesinde, NuGet çözümleyicileri olan bir projeye başvuru eklerseniz, Visual Studio bu çözümleyicileri bağımlı projeye otomatik olarak ekler. Bu davranışı devre dışı bırakmak için (örneğin, bağımlı proje bir birim testi projesiyse), başvuruda bulunılan projenin PrivateAssets veya .vbproj dosyasında özniteliğini ayarlayarak NuGet paketini özel olarak işaretleyin:

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

İlgili içerik

• Visual Studio'da kod çözümleyicilerine genel bakış
• Kod çözümleyici hatası gönderme
• Kural kümelerini kullanma
• Kod analizi ihlallerini gizleme
• Kod analizi için yapılandırma seçenekleri