A docs.microsoft.com webhelyen elérhető egységes .NET-referencia bejelentése

A bejegyzést Jeff Sandquist, az Azure Growth and Ecosystem csapatának vezérigazgatója írta.

Majdnem egy éve teszteltük a .NET Core referenciadokumentációját docs.microsoft.com. Ma örömmel jelentjük be egyesített .NET API-referenciafelületünket. Tisztában vagyunk azzal, hogy a fejlesztői hatékonyság kulcsfontosságú – egy hobbifejlesztőtől kezdve egy startupon át egy vállalatig. Ezt szem előtt tartva szorosan együttműködtünk a Xamarin csapatával, hogy egységesítsük a .NET API-k dokumentálása, felderítése és navigálását a Microsoftnál.

Minden .NET-dokumentáció – egy helyen

Korábban, ha meg akarta találni a . A Microsoft által szállított NET-alapú SDK-t a kedvenc keresőmotorjával kellett töltenie, és meg kellett találnia azt a helyet, ahol letöltheti, valamint felderítette a vonatkozó API-dokumentációt.

Előre haladva, azt tervezzük, hogy az összes . A NET-kompatibilis SDK-k egységesek és kereshetők egy helyen: https://docs.microsoft.com/dotnet/api. Itt megtalálja a .NET-keretrendszer, a .NET Core, a .NET Standard és a Xamarin referenciadokumentációját, valamint az Azure NuGet-csomagok dokumentációját. Az elkövetkező hónapokban további SDK-kkal bővítjük ezt a felületet.

Az API Browser bemutatása

A fő célunk, hogy intelliSense-szerű felhasználói élményt nyújtsunk a .NET API-k webböngészőből történő kereséséhez. Névtér, osztály, metódus vagy felület kereséséhez írja be a teljes vagy részleges nevét közvetlenül az API Browser oldalára.

Ha nem tudja biztosan, hogy melyik SDK-hoz tartozik egy adott típus, tag vagy névtér, egyszerűen válassza a Minden API lehetőséget az API-hatókör legördülő listájában, és keressen az összes elérhető referenciadokumentumban. Ha korlátozni szeretné a keresést, kiválaszthat egy adott keretrendszert vagy SDK-t, valamint annak verzióját – például .NET-keretrendszer 4.7-et, és csak az adott API-készleten belül kereshet.

Az API Browser felület a tartalomjegyzék tetején is integrálva van a következőhöz: . NET-alapú API-k, amelyekkel gyorsan megtalálhatja az API-kat, függetlenül attól, hogy hol található a referenciadokumentációban:

Ha egy adott névtérben van, az API Browser csak a csatlakoztatott API-k családjára terjed ki, így a keresés mindig a lehető legjobb eredményeket adja vissza a környezete alapján.

Verziószámozás támogatása

Már nem kell csodálkoznia, hogy egy típusnak vannak-e tagjai a .NET-keretrendszer egy adott verziójában vagy az Azure Storage NuGet-csomagban – mindössze annyit kell tennie, hogy módosítja a verziót az API Browser vezérlőről, és a tartalom ennek megfelelően módosul:

Nyílt forráskódúra épülő

Az API Browser létrehozásához nyílt szabványokat és eszközöket használtunk. Ennek alapjaként a DocFX-et – a nyílt dokumentációgenerálási eszközláncot és a Xamarin mdoc-alkalmazását – használtuk.

Mostantól az összes felügyelt referenciadokumentáció automatikusan létre lesz hozva a NuGeten található bináris fájlokból, vagy a fő keretrendszer-disztribúciók, például a .NET-keretrendszer vagy a .NET Core részét képezik.

Folyamatos integrációs infrastruktúránk lehetővé teszi számunkra, hogy pontos dokumentációt biztosítsunk a legújabb API-król, amelyek mostantól a kiadástól számított órákon belül nyilvánosak lesznek, és megnyílnak a hozzájárulások számára. Az ECMAXML formátumra vonatkozó összes .NET API-dokumentációt is szabványosítottuk, amely egységes és átfogó API-reprezentációt hoz létre a dokumentált SDK-tól függetlenül. Emellett nem kell ismernie a fájlformátum bonyolultságait, mivel az automatikusan létrehozott dokumentumokba ágyazott Markdown-tartalmakat is hozzáadhat. A referenciadokumentációhoz való közösségi hozzájárulások a következő hónapban lesznek engedélyezve.

Fókusz a tartalomra

Az új élmények mellett a referenciatartalmakat is úgy optimalizáltuk, hogy könnyebben felderíthetők és olvashatók legyenek. Frissítettük a tartalomjegyzéket, hogy mindig névtér-központú legyen. Függetlenül attól, hogy egy névtéren, típuson vagy tagon böngészi az adatokat, mindig csak a szülőnévteret jelenítjük meg, amelynek minden gyermektípusa & a megfelelő csoporttagokat:

Ez azt jelenti, hogy a hivatkozási oldalak zsúfoltak, és először a legfontosabb információkat mutatják be, például általános áttekintéseket és példákat – mindezt egy pillantással.

Olyan példákat is láthat, amelyek közvetlenül a kezdetektől fogva relevánsak önnek, szűrve a választott programozási nyelvre – többé nem kell a lap aljára görgetnie, hogy megtalálja azokat.

Visszajelzésalapú

Ez csak a referenciadokumentáció átdolgozásának kezdete. Szeretnénk hallani visszajelzését arról, hogyan tehetjük még vonzóbbá, hasznosabbá és gyorsabbá dokumentációnkat. Lépjen a UserVoice webhelyre , és tudassa velünk, hogyan javíthatjuk az API Browser felhasználói élményét. A gyors frissítésekért bármikor kapcsolatba lép velünk a Twitteren, @docsmsft.