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 na docs.microsoft.com. Dnes jsme rádi, že oznamujeme naše jednotné referenční prostředí rozhraní .NET API. Chápeme, že produktivita vývojářů je klíčová – od nadšeného vývojáře až po startup až po podnik. S ohledem na to jsme úzce spolupracovali s týmem Xamarin, abychom standardizovali, jak dokumentujeme, zjišťujeme a procházíme rozhraní API .NET v Microsoftu.

Dokumentace k .NET – na jednom místě

Pokud jste chtěli najít . Sadu SDK založenou na netu od Microsoftu jste museli trávit nějakou dobu s vaším oblíbeným vyhledávacím webem a snažit se najít místo, kde si ji můžete stáhnout, a také zjistit příslušnou dokumentaci k rozhraní API.

V budoucnu plánujeme mít vše . Sady SDK kompatibilní s technologií NET sjednocené a prohledávatelné na jednom místě: https://docs.microsoft.com/dotnet/api Tady najdete referenční dokumentaci k rozhraní .NET Framework, .NET Core, .NET Standard a Xamarinu a dokumentaci k balíčkům Azure NuGet. V následujících měsících přidáme do tohoto prostředí další sady SDK.

Představení prohlížeče rozhraní API

Naším hlavním cílem je přenést prostředí IntelliSense, které umožňuje prohledávat všechna rozhraní API .NET z webového prohlížeče. Obor názvů, třídu, metodu nebo rozhraní můžete vyhledat zadáním jeho úplného nebo částečného názvu přímo na stránce prohlížeče rozhraní API.

API Browser

Pokud si nejste jistí, ke kterému typu, členovi nebo oboru názvů patří sada SDK, můžete jednoduše vybrat všechna rozhraní API v rozevíracím seznamu oboru rozhraní API a hledat ve všech dostupných referenčních dokumentech. Případně pokud chcete omezit vyhledává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 této sadě rozhraní API.

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

API Browser in-page

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

Podpora správy verzí

Už nemusíte přemýšlet o tom, jestli typ obsahuje č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í:

Reference TOC

Integrované s ohledem na open source

K vytvoření prohlížeče rozhraní API jsme použili otevřené standardy a nástroje. V jeho jádru jsme využili DocFX – open documentation generation toolchain spolu s aplikací Mdoc Xamarinu.

Veškerá naše spravovaná referenční dokumentace se teď automaticky generuje z binárních souborů, které se dodávají na NuGetu 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í, 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 nemusíte znát složitost formátu souboru, protože můžete přispívat obsahem v Markdownu, který je vložený do automaticky vygenerovaný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 lépe zjistitelný a čitelný. Aktualizovali jsme obsah tak, aby byl vždy zaměřený na obor názvů. Bez ohledu na to, jestli procházíte informace o oboru názvů, typu nebo členu, 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ů:

Reference TOC

To znamená, že referenční stránky jsou zpřehledněny a zobrazují vám nejdůležitější informace jako první, například 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 zvoleného programovacího jazyka – už se nemusíte posouvat na úplně dolní část stránky, abyste je našli.

Zpětnou vazbu řízenou

Toto je jen začátek dokumentace k úpravě referenční dokumentace. Chceme slyšet vaši zpětnou vazbu ohledně toho, jak můžeme naši dokumentaci usnadnit, užitečnější a co nejrychleji vás dostat. Přejděte na náš web UserVoice a dejte nám vědět, jak můžeme vylepšit naše prostředí prohlížeče rozhraní API. Rychlé aktualizace nám můžete kdykoliv kontaktovat na Twitteru, @docsmsft.