.NET API-dokumentationen har flyttats från MSDN till docs.microsoft.com

Det här inlägget skrevs av Den Delimarsky, Program Manager i Cloud + AI Division.

Vi är glada över att kunna meddela den slutförda migreringen av all .NET Framework dokumentation på 11 språk från MSDN till docs.microsoft.com. För att förstå volymen och skalan för den här migreringen representerar det .NET Framework innehållet över 9 miljoner API-dokument eller 20 % av volymen i hela MSDN-biblioteket.

Målet är att ge en enhetlig, modern och konsekvent upplevelse för att hitta och navigera i alla .NET-API:er som levereras av Microsoft, inkludera djup support för versionshantering, använda och köra API-kodexempel, enkelt aktivera API-uppdateringar med automatisering och stödja community-bidrag.

docs.microsoft.com aktiverar den här upplevelsen för:

  • .NET Framework (version 1.1 – 4.7.2)
  • .NET Core (version 1.0 - 2.1)
  • .NET Standard (version 1.0 – 2.0)
  • Och alla .NET-API:er, SDK:er och NuGet-paket som levereras av Microsoft

Sök igenom alla Microsoft .NET-API:er på ett ställe med .NET API Browser

Var du någonsin i en situation där du letar efter ett API, men du bara inte vet var du ska börja? Vi har skapat ett dedikerat API-sökindex så att du snabbt kan hitta nödvändiga API:er inom några sekunder med produkt- och versionsfilter – .NET API Browser.

Sökning i .NET API Browser

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:

Versionsväljare i .NET-dokument

Förbättrad organisation

I den vänstra innehållsförteckningen grupperas innehållet efter namnområde och typer av entiteter i namnområdet. När du väljer en klass ser du till exempel att vi grupperar entiteter efter deras respektive typ: Egenskaper, Fält, Metoder och Händelser.

Gruppering av entiteter

Du kan också söka med hjälp av .NET API Browser och även filtrera en specifik API-version, allt från innehållsförteckningen, vilket gör det enkelt att hitta exakt det API du letar efter.

Sökning i .NET API Browser på sidan

Kunder har också berättat för oss att när du befinner dig på API-referenssidor kan det ibland vara svårt att hitta nedladdning, installation och annan användbar dokumentation för ett API. Som du ser i bilden nedan kombinerar Azure .NET SDK både artiklar och referensdokumentation, allt i en innehållsförteckning!

Fusion TOC i Azure-API:er

Intuitiva URL:er

När vi ursprungligen lanserade docs.microsoft.com var ett av våra mål att ha tydliga, konsekventa och intuitiva hierarkiska URL:er. Om du minns att du använde MSDN var vissa .NET-URL:er strukturerade så här:

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

Det gjorde det verkligen svårt att förstå vad det här innehållet är, bara genom att titta på det.

Länken ovan blir nu följande:

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

Här är bara några av URL-reglerna från vår url-bok för att säkerställa konsekventa och intuitiva URL:er för .NET:

Namnrymder

Mönster: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}

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

Klasser

Mönster: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}

Exempel: https://docs.microsoft.com/dotnet/api/system.flagsattribute

Metoder

Mönster: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}

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

Exempel först

En konsekvent sak som vi har hört från intervjuer med kunder är vikten av högkvalitativa, kortfattade och funktionella kodexempel för API:er. I MSDN inkluderades exempel i slutet av en sida, vilket innebär att du i vissa exempel skulle behöva rulla ned 20+ gånger för att se det första exemplet för en typ. I Docs är exemplen först enligt nedan:

Jämförelse av exempel mellan MSDN och dokument

Precis som MSDN stöder Docs alla .NET-språk, inklusive C#, VB, F#och C++

Språkväljare i dokument

Köra exempel interaktivt i webbläsaren

När du arbetar med kod är det bästa sättet att lära dig att faktiskt skriva kod – vi ville se till att du kan göra det direkt från webbläsaren. För ett år sedan distribuerade vi try .NET-funktionen och under året har vi integrerat den i ett antal artiklar. Vi fortsätter att integrera den här funktionen i ännu fler API-dokument, så att du kan experimentera utan att lämna sidan.

Interaktiv .NET-kod i webbläsaren

Stöds av standardverktyg för automatisk generering

All API-dokumentation om docs.microsoft.com genereras automatiskt, vilket gör att vi enkelt kan dokumentera hela API-ytan och dramatiskt förbättra tiden och frekvensen för uppdateringar från veckor till minuter. Detta säkerställer att du får dokumentation om API-kvalitet för alla .NET-API:er.

För att göra detta samarbetade vi med Xamarin-teknikteamet för att utveckla och använda mdoc för att generera all .NET-referensdokumentation.

När vi startade migreringen ville vi se till att inga länkar bryts – alla de MSDN-länkar som kan vara integrerade i produkter, blogginlägg och andra webbplatser bör fungera korrekt och peka användare till den nya platsen, med hjälp av en standard 301-omdirigering.

Omdirigering från MSDN till docs.microsoft.com

Redo för community-bidrag

Allt migrerat innehåll är nu öppen källkod på lagringsplatsen dotnet/dotnet-api-docs på GitHub. Men du behöver inte söka efter filer för att göra dina bidrag – gå bara till någon av .NET API-sidorna och klicka på Redigera, så kommer du direkt till filen som du vill göra ändringar i.

Bidra till dokumentationen

Vi vill ha din feedback

Vi hoppas att du gillar det nya innehållsformatet – skicka feedback till oss på GitHub eller Twitter.