.NET API-documentatie verplaatst van MSDN naar docs.microsoft.com

Dit bericht is geschreven door Den Delimarsky, Program Manager in de Divisie Cloud + AI.

Met trots kondigen we de migratie aan van alle .NET Framework documentatie in 11 landinstellingen van MSDN naar docs.microsoft.com. Om inzicht te krijgen in het volume en de schaal van deze migratie, vertegenwoordigt de .NET Framework inhoud meer dan 9 miljoen API-documenten of 20% van het volume van de hele MSDN-bibliotheek.

Het doel is om een uniforme, moderne en consistente ervaring te bieden voor het vinden en navigeren van alle .NET API's die door Microsoft worden geleverd, uitgebreide ondersteuning bieden voor versiebeheer, het gebruik en het uitvoeren van API-codevoorbeelden, het eenvoudig inschakelen van API-updates met behulp van automatisering en het ondersteunen van bijdragen van de community.

docs.microsoft.com maakt deze ervaring mogelijk voor:

• .NET Framework (versies 1.1 - 4.7.2)
• .NET Core (versies 1.0 - 2.1)
• .NET Standard (versies 1.0 - 2.0)
• En alle .NET API's, SDK's en NuGet-pakketten die door Microsoft zijn verzonden

Zoeken in alle Microsoft .NET API's op één plek met de .NET API Browser

Bent u ooit in een situatie geweest waarin u op zoek bent naar een API, maar u niet weet waar u moet beginnen? We hebben een speciale API-zoekindex gemaakt, zodat u binnen enkele seconden snel de benodigde API's kunt vinden, met product- en versiefilters: de .NET API-browser.

Ondersteuning voor versiebeheer

U hoeft zich niet meer af te vragen of voor een type leden beschikbaar zijn in een specifieke versie van .NET Framework of het Azure Storage NuGet-pakket. U hoeft alleen maar de versie van het API-browserbesturingselement te wijzigen en de inhoud wordt dienovereenkomstig aangepast:

Betere indeling

In de linkerinhoudsopgave wordt inhoud gegroepeerd op naamruimte en typen entiteiten binnen die naamruimte. Wanneer u bijvoorbeeld een klasse selecteert, ziet u dat we entiteiten groeperen op hun respectieve type: Eigenschappen, Velden, Methoden en Gebeurtenissen.

U kunt ook zoeken met behulp van de .NET API-browser en zelfs een specifieke API-versie filteren, allemaal vanuit de inhoudsopgave, zodat u gemakkelijk de exacte API kunt vinden die u zoekt.

Klanten hebben ons ook verteld dat wanneer u zich op API-referentiepagina's bevindt, het soms moeilijk kan zijn om downloaden, instellen en andere nuttige documentatie voor een API te vinden. Zoals u in de onderstaande afbeelding kunt zien, combineert de Azure .NET SDK zowel artikelen als referentiedocumentatie, allemaal in één inhoudsopgave.

Intuïtieve URL's

Toen we oorspronkelijk docs.microsoft.com lanceerden, was een van onze doelen om duidelijke, consistente en intuïtieve hiërarchische URL's te hebben. Als u zich het gebruik van MSDN herinnert, zijn sommige .NET-URL's als volgt gestructureerd:

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

Het maakte het heel moeilijk om te begrijpen wat deze inhoud is, gewoon door ernaar te kijken.

De bovenstaande koppeling wordt nu deze:

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

Hier volgen slechts enkele URL-regels uit ons URL-boek om consistente en intuïtieve URL's voor .NET te garanderen:

Naamruimten

Patroon: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}

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

Klassen

Patroon: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}

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

Methoden

Patroon: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}

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

Voorbeelden eerst

Een consistent ding dat we uit gesprekken met klanten hebben gehoord, is het belang van hoogwaardige, beknopte en functionele codevoorbeelden voor API's. In MSDN zijn voorbeelden aan het einde van een pagina opgenomen, wat betekent dat u in sommige voorbeelden meer dan 20 keer omlaag moet schuiven om het eerste voorbeeld voor een type te zien. In Docs worden de voorbeelden eerst weergegeven, zoals hieronder wordt weergegeven:

Net als MSDN ondersteunt Docs alle .NET-talen, waaronder C#, VB, F# en C++

Voorbeelden interactief uitvoeren in de browser

Wanneer u met code werkt, kunt u het beste leren door daadwerkelijk code te schrijven. We wilden ervoor zorgen dat u dit rechtstreeks vanuit de browser kunt doen. Een jaar geleden hebben we de functie Try .NET geïmplementeerd en dit jaar hebben we deze geïntegreerd in een aantal artikelen. In de toekomst blijven we deze functionaliteit integreren in nog meer API-documenten, zodat u kunt experimenteren zonder de pagina te verlaten.

Ondersteund door standaardprogramma's voor automatisch genereren

Alle API-documentatie over docs.microsoft.com wordt automatisch gegenereerd, zodat we eenvoudig het hele API-oppervlak kunnen documenteert en de tijd en frequentie van updates aanzienlijk kunnen worden verbeterd, van weken tot minuten. Dit zorgt ervoor dat u API-documentatie van hoge kwaliteit krijgt voor alle .NET-API's.

Hiervoor werkten we samen met het technische team van Xamarin om mdoc te ontwikkelen en te gebruiken om alle .NET-referentiedocumentatie te genereren.

MSDN-koppelingen - omleiden naar docs.microsoft.com

Toen we de migratie begonnen, wilden we ervoor zorgen dat er geen koppelingen worden verbroken. Al die MSDN-koppelingen die mogelijk zijn geïntegreerd in producten, blogberichten en andere sites, moeten goed werken en gebruikers naar de nieuwe locatie verwijzen, met behulp van een standaard 301-omleiding.

Klaar voor communitybijdragen

Alle gemigreerde inhoud wordt nu open source in de opslagplaats dotnet/dotnet-api-docs op GitHub. U hoeft echter niet te zoeken naar bestanden om uw bijdragen te leveren. Ga naar een van de .NET API-pagina's en klik op Bewerken. U wordt dan rechtstreeks naar het bestand gebracht waarin u wijzigingen wilt aanbrengen.

Geef ons uw feedback

We hopen dat u veel plezier hebt van de nieuwe inhoudsindeling. Stuur ons uw feedback op GitHub of Twitter.