Enhetliga .NET-referenser på docs.microsoft.com

Det här inlägget har skrivits av Jeff Sandquist, General Manager i teamet Azure Growth and Ecosystem.

För nästan ett år sedan testade vi referensdokumentationen för .NET Core på docs.microsoft.com. Idag är vi glada att kunna presentera vår enhetliga .NET API-referensupplevelse. Vi förstår att utvecklarproduktivitet är mycket viktigt – för alla från hobbyutvecklare, till nystartade företag och större företag. Med det i åtanke inledde vi ett nära samarbete med Xamarin-teamet för att standardisera hur vi dokumenterar, identifierar och navigerar .NET-API:er på Microsoft.

All .NET-dokumentation – på en plats

Om du tidigare ville hitta en .NET-baserad SDK levererad av Microsoft var du tvungen att ägna tid åt att använda din favoritsökmotor och försöka att ta reda på både varifrån du kan hämta den och identifiera den relevanta API-dokumentationen.

Framöver planerar vi att ha alla . NET-kompatibla SDK:er är enhetliga och sökbara på ett ställe: https://docs.microsoft.com/dotnet/api. Där hittar du referensdokumentation för .NET Framework, .NET Core, .NET Standard och Xamarin, samt dokumentation för våra Azure NuGet-paket. Under kommande månader kommer vi att lägga till fler SDK:er.

Introduktion till API-webbläsaren

Vårt huvudsakliga mål är att skapa en IntelliSense-liknande upplevelse som du kan använda för att söka i alla .NET-API:er från en webbläsare. Du kan söka efter en namnrymd, klass, metod eller ett gränssnitt genom att ange dess fullständiga eller ofullständiga namn direkt på sidan för API-webbläsaren.

Om du inte är säker på vilken SDK en specifik typ, medlem eller namnrymd tillhör kan du helt enkelt välja Alla API:er i listrutan API-omfång och söka i alla tillgängliga referensdokument. Om du vill begränsa sökningen kan du också välja ett specifikt ramverk eller SDK samt dess version – till exempel .NET Framework 4.7 och söka endast inom den uppsättningen API:er.

API-webbläsaren finns även överst i innehållsförteckningen för .NET-baserade API: er så att du enkelt kan hitta vilket API som helst oavsett var du befinner dig i referensdokumentationen:

När du är i en specifik namnrymd begränsas API-webbläsaren till endast den grupp av API:er som är sammankopplade, vilket innebär att din sökning alltid returnerar de bästa resultaten baserat på din kontext.

Stöd för versionshantering

Du behöver inte längre fundera över om en typ har medlemmar som är tillgängliga i en specifik version av .NET Framework eller Azure Storage NuGet-paket. Allt du behöver göra är att ändra versionen från kontrollen i API-webbläsaren, så justeras innehållet utifrån detta:

Skapad med öppen källkod i åtanke

För att skapa API-webbläsaren använde vi öppna standarder och verktyg. Som grund använde vi DocFX – den öppna verktygskedjan för dokumentation, tillsammans med Xamarins mdoc-program.

All vår hanterade referensdokumentation genereras nu automatiskt från binärfiler som levereras på NuGet eller är en del av distributioner från huvudramverk som .NET Framework eller .NET Core.

Vår kontinuerliga integrering av infrastruktur gör att vi har korrekt dokumentation för de senaste API:erna som nu kan vara offentlig och öppen för bidrag inom bara några timmar efter att API:erna har publicerats. Vi har även standardiserat all .NET-API-dokumentation enligt ECMAXML-formatet, vilket skapar en konsekvent och omfattande API-representation oavsett vilken SDK dokumentationen handlar om. Dessutom behöver du inte känna till invecklingarna i filformatet, eftersom du kan bidra med innehåll i Markdown, inbäddat i automatiskt genererade dokument. Community-bidrag för referensdokumentation kommer att aktiveras inom nästa månad.

Fokus på innehåll

Förutom implementationen av de tidigare nämnda funktionerna har vi även optimerat referensinnehållet för att göra det mer lättnavigerat och läsbart. Vi har uppdaterat innehållsförteckningen så att den nu alltid fokuserar på namnrymden. Oavsett om du bläddrar igenom information om en namnrymd, typ eller medlem visas alltid endast den överordnade namnrymden med alla dess underordnade typer och deras respektive grupperade medlemmar:

Det här innebär att referenssidorna är mindre röriga och att den viktigaste informationen visas först, till exempel allmänna översikter och exempel – du behöver bara kasta en snabb blick för att förstå.

Du kommer även att se exempel som är relevanta för dig redan från början och som filtrerats efter det programmeringsspråk som du valt. Du behöver inte längre bläddra ned längst ned på sidan för att hitta dem.

Baserat på feedback

Detta är bara början på de förändringar som vi vill göra för referensdokumentationen. Vi vill gärna höra dina synpunkter om hur vi kan göra vår dokumentation mer engagerande och användbar för att hjälpa dig att komma igång så snabbt som möjligt. Gå till UserVoice-webbplatsen och berätta för oss hur vi kan förbättra vår API-webbläsare. Du kan också alltid kontakta oss på Twitter , @docsmsft, för snabba uppdateringar.