Microsoft.DotNet.ApiCompat.Tool genel aracı

Makale
12/05/2023

Microsoft.DotNet.ApiCompat.Tool aracı, MSBuild dışında API uyumluluk denetimleri gerçekleştirmenizi sağlar. Aracın iki modu vardır:

Bir paketi temel paketle karşılaştırın.
Bir derlemeyi temel derlemeyle karşılaştırın.

Yükleme

Aracı yüklemek için aşağıdaki komutu çalıştırın.

dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool

Genel araçları yükleme hakkında daha fazla bilgi için bkz . Genel araç yükleme.

Kullanım

Microsoft.DotNet.ApiCompat.Tool [command] [options]

-veya-

apicompat [command] [options]

Komutlar

package | --package <PACKAGE_FILE>

Paket varlıklarının uyumluluğunu doğrular. Belirtilmezse, araç derlemeleri karşılaştırır. <PACKAGE_FILE> paket dosyasının yolunu belirtir.

Seçenekler

Bazı seçenekler hem derleme hem de paket doğrulaması için geçerlidir. Diğerleri yalnızca derlemelere veya yalnızca paketlere uygulanır.

Genel seçenekler

--version

Sürüm bilgilerini gösterir.
--generate-suppression-file

Uyumluluk gizleme dosyası oluşturur.
--preserve-unnecessary-suppressions

Gizleme dosyasını yeniden oluştururken gereksiz gizlemeleri korur.

Mevcut bir gizleme dosyası yeniden oluşturulduğunda, içeriği okunur, seri durumdan çıkarılır ve ardından bir listede depolanır. Uyumsuzluk düzeltildiyse bazı gizlemeler artık gerekli olmayabilir. Gizlemeler diske geri seri hale getirildiğinde, bu seçeneği belirterek tüm mevcut (seri durumdan çıkarılmış) ifadeleri korumayı seçebilirsiniz.
--permit-unnecessary-suppressions

Gizleme dosyasında gereksiz gizlemelere izin verir.
--suppression-file <FILE>

Okunacak bir veya daha fazla gizleme dosyasının yolunu belirtir.
--suppression-output-file <FILE>

Belirtildiğinde --generate-suppression-file yazılması gereken bir gizleme dosyasının yolunu belirtir. Belirtilmezse, ilk --suppression-file yol kullanılır.
--noWarn <NOWARN_STRING>

Gizlenecek tanılama kimliklerini belirtir. Örneğin, "$(NoWarn);PKV0001".
--respect-internals

Hem public hem de internal API'leri denetler.
--roslyn-assemblies-path <FILE>

Kullanmak istediğiniz Microsoft.CodeAnalysis derlemelerini içeren dizinin yolunu belirtir. Bu özelliği yalnızca SDK'dakinden daha yeni bir derleyiciyle test etmek istiyorsanız ayarlamanız gerekir.
-v, --verbosity [high|low|normal]

Günlük düzeyi ayrıntı düzeyini denetler. İzin verilebilen değerler , normalve lowdeğerleridirhigh. Varsayılan değer: normal.
--enable-rule-cannot-change-parameter-name

Ortak yöntemlerde parametre adlarının değişip değişmediğini denetleen kuralı etkinleştirir.
--enable-rule-attributes-must-match

Özniteliklerin eşleşip eşleşmediğini denetleen kuralı etkinleştirir.
--exclude-attributes-file <FILE>

DocId biçiminde dışlanması gereken öznitelikler içeren bir veya daha fazla dosyanın yolunu belirtir.

Derlemeye özgü seçenekler

Bu seçenekler yalnızca derlemeler karşılaştırıldığında geçerlidir.

-l, --left, --left-assembly <PATH>

Karşılaştırmak için sol taraf görevi görecek bir veya daha fazla derlemenin yolunu belirtir. Derlemeler karşılaştırılırken bu seçenek gereklidir.
-r, --right, --right-assembly <PATH>

Karşılaştırmak için sağ taraf görevi görecek bir veya daha fazla derlemenin yolunu belirtir. Derlemeler karşılaştırılırken bu seçenek gereklidir.
--strict-mode

API uyumluluk denetimlerini katı modda gerçekleştirir.

Pakete özgü seçenekler

Bu seçenekler yalnızca paketler karşılaştırıldığında geçerlidir.

--baseline-package

Geçerli paketin doğrulanması için temel paketin yolunu belirtir.
--enable-strict-mode-for-compatible-tfms

Tüm uyumlu hedef çerçeveler için sözleşme ve uygulama derlemeleri için katı modda API uyumluluğunu doğrular. Varsayılan değer: true.
--enable-strict-mode-for-compatible-frameworks-in-package

Api uyumluluğunu , hedef çerçevelerine göre uyumlu derlemeler için katı modda doğrular.
--enable-strict-mode-for-baseline-validation

Paket temeli denetimleri için api uyumluluğunu katı modda doğrular.
--package-assembly-references

Paketteki belirli bir hedef çerçeve için derleme başvurularının veya bunların temel dizinlerinin yollarını belirtir. Birden çok değeri virgülle ayırın.
--baseline-package-assembly-references

Temel paketteki belirli bir hedef çerçeve için derleme başvurularının veya bunların temel dizinlerinin yollarını belirtir. Birden çok değeri virgülle ayırın.
--baseline-package-frameworks-to-ignore

Temel paketten yoksaymak için hedef çerçeve kümesini belirtir. Çerçeve dizesinin taban çizgisi paketindeki klasör adıyla tam olarak eşleşmesi gerekir.

Örnekler

Aşağıdaki komut, derlemenin geçerli ve temel sürümlerini karşılaştırır.

apicompat --left bin\Release\net8.0\LibApp5.dll --right bin\Release\net8.0\LibApp5-baseline.dll

Aşağıdaki komut, bir paketin geçerli ve temel sürümlerini karşılaştırır.

apicompat package "bin\Release\LibApp5.1.0.0.nupkg" --baseline-package "bin\Release\LibApp5.2.0.0.nupkg"

Aşağıdaki örnekte, parametre adı değişikliklerini denetleme de dahil olmak üzere bir derlemenin geçerli ve temel sürümlerini karşılaştırmak için komutu gösterilmektedir. Örnek ayrıca bir parametre adı değiştiyse çıkışın nasıl görünebileceğini de gösterir.

>apicompat -l LibApp5-baseline.dll -r LibApp5.dll --enable-rule-cannot-change-parameter-name
API compatibility errors between 'LibApp5-baseline.dll' (left) and 'LibApp5.dll' (right):
CP0017: Parameter name on member 'KitchenHelpers.ToastBreadAsync(int, int)'
changed from 'slices' to 'numSlices'.
API breaking changes found. If those are intentional, the APICompat
suppression file can be updated by specifying the '--generate-suppression-file' parameter.

Aracılığıyla paylaş