MSDN'den docs.microsoft.com taşınan .NET API belgeleri

Bu gönderi, Bulut + AI Bölümü Program Yöneticisi Den Delimarsky tarafından yazılmıştır.

MSDN'den docs.microsoft.com 11 yerel ayardaki tüm .NET Framework belgelerinin tamamlandığını duyurmaktan heyecan duyuyoruz. Bu geçişin hacmini ve ölçeğini anlamak için .NET Framework içeriği 9 milyondan fazla API belgesini veya MSDN Kitaplığı'nın tamamının hacminin %20'sini temsil eder.

Amaç, Microsoft tarafından gönderilen tüm .NET API'lerini bulmak ve gezinmek için birleşik, modern ve tutarlı bir deneyim sağlamak, sürüm oluşturma için ayrıntılı destek sağlamak, API kodu örneklerini kullanmak ve çalıştırmak, otomasyon kullanarak API güncelleştirmelerini kolayca etkinleştirmek ve topluluk katkılarını desteklemektir.

docs.microsoft.com aşağıdakiler için bu deneyimi etkinleştirir:

• .NET Framework (sürüm 1.1 - 4.7.2)
• .NET Core (sürüm 1.0 - 2.1)
• .NET Standard (sürüm 1.0 - 2.0)
• Microsoft tarafından gönderilen tüm .NET API'leri, SDK'ları ve NuGet paketlerini de

.NET API Browser ile tüm Microsoft .NET API'lerini tek bir yerde arama

API aradığınız ama nereden başlayacağınızı bilmediğiniz bir durumda mıydınız? Ürün ve sürüm filtreleri ( .NET API Tarayıcısı) ile gerekli API'leri saniyeler içinde hızlı bir şekilde bulmanızı sağlayan ayrılmış bir API arama dizini derledik.

Sürüm Oluşturma Desteği

Artık bir türün .NET Framework veya Azure Depolama NuGet paketinin belirli bir sürümünde kullanılabilir üyeleri olup olmadığını merak etmeniz gerekmez. Tek yapmanız gereken API Browser denetiminden sürümü değiştirmektir ve içerik buna göre ayarlanır:

Geliştirilmiş düzenleme

Soldaki içindekiler tablosunda içerik, ad alanına ve bu ad alanındaki varlık türlerine göre gruplandırılır. Örneğin bir sınıf seçtiğinizde varlıkları ilgili türe göre gruplandırtığımızı görürsünüz: Özellikler, Alanlar, Yöntemler ve Olaylar.

Alternatif olarak, .NET API Browser'ın yardımıyla arama yapabilir ve hatta içindekiler tablosundan belirli bir API sürümünü filtreleyebilir ve aradığınız TAM API'yi bulmayı kolaylaştırabilirsiniz.

Müşteriler ayrıca API başvuru sayfaları içinde olduğunuzda, bazen BIR API için indirme, kurulum ve diğer yararlı belgeleri bulmanın zor olabileceğini söyledi. Aşağıdaki görüntüde de görebileceğiniz gibi Azure .NET SDK'sı hem makaleleri hem de başvuru belgelerini tek bir içindekiler tablosunda birleştirir!

Sezgisel URL'ler

başlangıçta docs.microsoft.com başlattığımızda, hedeflerimizden biri net, tutarlı ve sezgisel hiyerarşik URL'lere sahip olmaktı. MSDN'yi kullandığınızı anımsarsanız, bazı .NET URL'leri şöyle yapılandırılmıştı:

https://msdn.microsoft.com/library/8kszeddc(v=vs.110).aspx

Yalnızca bakarak bu içeriğin ne olduğunu anlamanın gerçekten zor olmasını sağladı.

Yukarıdaki bağlantı artık şu şekildedir:

https://docs.microsoft.com/dotnet/api/system.array.sort

.NET için tutarlı ve sezgisel URL'ler sağlamak için URL'ler Kitabımızda yer alan URL kurallarından yalnızca bazıları şunlardır:

Ad alanları

Desen: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}

Örnek: https://docs.microsoft.com/dotnet/api/system.collections.generic/

Sınıflar

Desen: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}

Örnek: https://docs.microsoft.com/dotnet/api/system.flagsattribute

Yöntemler

Desen: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}

Örnek: https://docs.microsoft.com/dotnet/api/system.decimal.add

Önce örnekler

Müşterilerle yaptığımız görüşmelerden aldığımız tutarlı bir şey, API'ler için yüksek kaliteli, kısa ve işlevsel kod örneklerinin önemidir. MSDN'de, bir sayfanın sonuna örnekler eklenmiştir; diğer bir deyişle bazı örneklerde, bir türün ilk örneğini görmek için 20'nin üzeri kez aşağı kaydırmanız gerekir. Docs'ta örnekler aşağıda gösterildiği gibi önce verilmiştir:

MSDN gibi Docs da C#, VB, F# ve C++ dahil olmak üzere tüm .NET dillerini destekler

Örnekleri tarayıcıda etkileşimli olarak çalıştırma

Kodla çalışırken öğrenmenin en iyi yolu aslında kod yazmaktır. Bunu doğrudan tarayıcıdan yapabileceğinizden emin olmak istedik. Bir yıl önce Try .NET özelliğini kullanıma aldık ve yıl boyunca bunu birkaç makaleyle tümleştirdik. Bundan sonra bu işlevi daha da fazla API belgesiyle tümleştirmeye devam edeceğiz ve bu sayede sayfadan çıkmadan denemeler yapabilirsiniz.

Standart otomatik oluşturma araçları tarafından desteklenir

docs.microsoft.com üzerindeki tüm API belgeleri otomatik olarak oluşturulur ve API yüzeyinin tamamını kolayca belgelememize olanak sağlar ve güncelleştirmelerin haftalardan dakikalara kadar olan süresini ve sıklığını önemli ölçüde geliştirir. Bu, tüm .NET API'leri için kaliteli API belgeleri edinmenizi sağlar.

Bunu yapmak için Xamarin mühendislik ekibiyle işbirliği yaptık ve tüm .NET Başvuru belgelerini oluşturmak için mdoc'u geliştirdik ve kullandık.

MSDN bağlantıları - docs.microsoft.com'e yeniden yönlendirme

Geçişe başlarken hiçbir bağlantının kopmadığından emin olmak istedik. Standart bir 301 yeniden yönlendirmesinin yardımıyla ürünlerle, blog gönderileriyle ve diğer sitelerle tümleştirilebilen tüm MSDN bağlantıları düzgün çalışmalı ve kullanıcıları yeni konuma yönlendirmelidir.

Topluluk katkıları için hazır

Geçirilen tüm içerik artık GitHub'daki dotnet/dotnet-api-docs deposunda açık kaynak. Ancak, katkılarınızı yapmak için dosya aramanız gerekmez. .NET API sayfalarından herhangi birine gidip Düzenle'ye tıklamanız yeterlidir; değişiklik yapmak istediğiniz dosyaya doğrudan yönlendirilirsiniz.

Geri bildirimlerinizi bekliyoruz

Yeni içerik biçiminin keyfini çıkarabileceğinizi umuyoruz. Lütfen bize GitHub veya Twitter'dan geri bildirim gönderin.