Oznamujeme jednotné prostředí s referenčními informacemi k .NET na docs.microsoft.com.

Autorem tohoto článku je Jeff Sandquist, šéf týmu Azure pro růst a ekosystémy.

Téměř před rokem jsme pilotovali referenční dokumentaci k .NET Core pro docs.microsoft.com. Dnes s radostí oznamujeme naše jednotné referenční prostředí rozhraní .NET API. Chápeme, že produktivita vývojářů je klíčová – od amatérského vývojáře, od startupu až po podnik. S ohledem na to jsme úzce spolupracovali s týmem Xamarin, abychom standardizovali způsob, jakým v Microsoftu dokumentujeme, zjišťujeme a procházíme rozhraní API .NET.

Všechna dokumentace k .NET – na jednom místě

Pokud jste dříve chtěli najít . Sada SDK založená na net dodávaná Microsoftem, museli jste strávit nějaký čas se svým oblíbeným vyhledávacím webem a snažili se najít místo, kde si ji můžete stáhnout, a také zjistit příslušnou dokumentaci k rozhraní API.

Do budoucna plánujeme mít všechny . Sjednocené a prohledávatelné sady SDK kompatibilní s NET na jednom místě: https://docs.microsoft.com/dotnet/api. Najdete zde referenční dokumentaci k rozhraním .NET Framework, .NET Core, .NET Standard a Xamarin a také dokumentaci k balíčkům NuGet Azure. V následujících měsících přidáme do tohoto prostředí další sady SDK.

Představujeme prohlížeč rozhraní API

Naším hlavním cílem je přinést prostředí podobné Technologii IntelliSense pro vyhledávání všech rozhraní .NET API z webového prohlížeče. Obor názvů, třídu, metodu nebo rozhraní můžete vyhledat zadáním jejich úplného nebo částečného názvu přímo na stránce prohlížeče rozhraní API.

Pokud si nejste jistí, ke které sadě SDK konkrétní typ, člen nebo obor názvů patří, můžete jednoduše vybrat Všechna rozhraní API v rozevíracím seznamu rozsahu rozhraní API a hledat ve všech dostupných referenčních dokumentech. Případně pokud chcete omezit hledání, můžete vybrat konkrétní architekturu nebo sadu SDK a také její verzi – například rozhraní .NET Framework 4.7, a hledat pouze v rámci této sady rozhraní API.

Rozhraní API Browser je také integrované v horní části obsahu pro . Rozhraní API založená na technologii NET, která umožňují rychle najít libovolné rozhraní API bez ohledu na to, kde se nacházíte v referenční dokumentaci:

Jakmile jste v určitém oboru názvů, prohlížeč rozhraní API je vymezen pouze na řadu rozhraní API, která jsou vzájemně propojená, takže hledání vždy vrací nejlepší možné výsledky na základě vašeho kontextu.

Podpora správy verzí

Už se nemusíte zajímat, jestli má typ členy dostupné v konkrétní verzi rozhraní .NET Framework nebo balíčku NuGet služby Azure Storage – stačí změnit verzi z ovládacího prvku API Browser a obsah se odpovídajícím způsobem upraví:

Vytvořeno s ohledem na Open Source

K vytvoření prohlížeče rozhraní API jsme použili otevřené standardy a nástroje. V podstatě jsme využili DocFX – sadu nástrojů pro generování otevřené dokumentace a aplikaci Mdoc od Xamarinu.

Veškerá naše spravovaná referenční dokumentace se teď automaticky generuje z binárních souborů, které jsou dodávány na NuGet nebo jsou součástí hlavních distribucí architektury, jako je .NET Framework nebo .NET Core.

Naše infrastruktura kontinuální integrace nám umožňuje mít přesnou dokumentaci k nejnovějším rozhraním API, která teď můžou být veřejná během několika hodin od vydání a mohou být otevřená pro příspěvky. Také jsme standardizovali veškerou dokumentaci k rozhraní .NET API ve formátu ECMAXML, který vytváří konzistentní a komplexní reprezentaci rozhraní API bez ohledu na zdokumentovanou sadu SDK. Navíc nepotřebujete znát složitosti formátu souboru, protože můžete přispívat obsahem v Markdownu, který je vložen do automaticky generovaných dokumentů. Příspěvky komunity pro referenční dokumentaci budou povoleny během následujícího měsíce.

Zaměření na obsah

Kromě nových prostředí jsme také optimalizovali referenční obsah tak, aby byl zjistitelnější a čitelnější. Aktualizovali jsme obsah tak, aby se vždy zaměřoval na obor názvů. Ať už procházíte informace o oboru názvů, typu nebo členovi, vždy vám ukážeme jenom nadřazený obor názvů se všemi jeho podřízenými typy & příslušných seskupených členů:

To znamená, že referenční stránky jsou odstupňované a zobrazují nejdůležitější informace, jako jsou obecné přehledy a příklady – vše na první pohled.

Uvidíte také příklady, které jsou pro vás relevantní hned od začátku, filtrované podle vámi zvoleného programovacího jazyka – už se nemusíte posouvat do dolní části stránky, abyste je našli.

Na základě zpětné vazby

Toto je jen začátek, kdy přepracováváme prostředí referenční dokumentace. Rádi bychom slyšeli vaše názory na to, jak můžeme naši dokumentaci udělat poutavější a užitečnější a jak vás co nejrychleji dostat na cestu. Přejděte na náš web UserVoice a dejte nám vědět, jak můžeme vylepšit naše rozhraní API Browser. Pro rychlé aktualizace nás můžete kdykoli kontaktovat na Twitteru , @docsmsft.