API uyumluluk araçları

  • Makale

Platformlar arası uyumluluk, .NET kitaplığı yazarları için temel bir gereksinim haline gelmiştir. Ancak, derlemeleri ve paketleri doğrulamak için araçlar olmadan, bunlar yanlışlıkla hataya neden olan değişiklikler içerebilir. Kitaplık yazarı olarak, çok hedefli derlemelerin uyumlu olduğundan emin olmanız gerekir. Örneğin, .NET 6 ve .NET Standard 2.0 için birden çok hedef içeren bir paket için. .NET Standard 2.0 ikili dosyasıyla derlenen kodun .NET 6 ikilisinde çalıştırılabilmesini sağlamanız gerekir.

Kaynak tüketen bu değişikliğin değişiklik olmadan derlenmesine devam ederse, değişikliğin güvenli ve uyumlu olduğunu düşünebilirsiniz. Ancak, tüketici yeniden derlenmediyse değişiklikler çalışma zamanında sorunlara neden olabilir. Örneğin, bir yönteme isteğe bağlı parametre eklemek veya bir sabitin değerini değiştirmek bu tür uyumluluk sorunlarına neden olabilir.

.NET SDK'sı, farklı hedef çerçeveler için oluşturulmuş sürümleri karşılaştırmak için çeşitli yollar sağlar. Hataya neden olan hiçbir değişiklik yapılmadığından emin olmak için temel sürüme göre daha yeni bir sürümü de doğrulayabilirsiniz. Derleme zamanında derlemelerinizi veya paketlediğinizde paketlerinizi doğrulamak için MSBuild görevlerini etkinleştirin. Veya MSBuild dışından doğrulamak için Microsoft.DotNet.ApiCompat.Tool genel aracını kullanın.

Paket doğrulama hakkında daha fazla bilgi için bkz . Paket doğrulama. Uygulamanız paketlenebilir olmadığında derleme doğrulaması kullanılmalıdır. Derleme doğrulaması hakkında daha fazla bilgi için bkz . Derleme doğrulaması.

Not

Derleme doğrulamayı MSBuild görevi olarak çalıştırmak için Microsoft.DotNet.ApiCompat.Task'a bir paket başvurusu eklemeniz gerekir. Benzer şekilde, henüz .NET SDK'da bulunmayan daha yeni özellikleri test etmek istediğinizde de bu pakete başvuru ekleyebilirsiniz. Örneğin, .NET 8 SDK'sını kullanırken Microsoft.DotNet.ApiCompat.Task paketinin 9.0.100-preview sürümüne başvurabilirsiniz.

Katı mod

Varsayılan olarak, doğrulama uyumluluk denetimleri gerçekleştirir. Ancak, katı modu da kabul edebilirsiniz. Katı modda doğrulama, eşitlik denetimleri gerçekleştirir. Eşitlik, uyumlu olanlar bile olmak üzere HIÇBIR API eklemesi veya derleme değişikliği yapılmamış olduğu anlamına gelir.

Katı mod kullanım örnekleri şunlardır:

  • API eklemelerinin genellikle yasak olduğu hizmet verme.
  • API değişikliklerini izlemek için. ApiCompatGenerateSuppressionFile truedeğerini olarak ayarlarsanız, API uyumluluk işlevi gizleme dosyasındaki tüm uyumluluk farklarını kaydeder.

Komut satırı aracında katı modu etkinleştirmek için seçeneği veya seçeneklerden --enable-strict* birini belirtin--strict-mode. MSBuild görevleri için katı modu etkinleştirmek için proje dosyanıza aşağıdaki MSBuild özelliklerinden birini veya daha fazlasını ekleyin: