Aankondiging van uniforme .NET-documentatie op docs.microsoft.com

Deze blogpost is geschreven door Jeff Sandquist, General Manager van het Azure Growth and Ecosystem-team.

Bijna een jaar geleden hebben we de .NET Core-referentiedocumentatie op docs.microsoft.com. Vandaag kondigen we onze uniforme .NET API-referentie-ervaring aan. We begrijpen dat productiviteit van ontwikkelaars essentieel is, van een hobbyistische ontwikkelaar tot een startup tot een onderneming. Met dat in gedachten werkten we nauw samen met het Xamarin-team om te standaardiseren hoe we .NET API's bij Microsoft documenteren, ontdekken en navigeren.

Alle .NET-documentatie - op één plek

Als u eerder een wilde vinden. Op NET gebaseerde SDK die door Microsoft is geleverd, moest u enige tijd doorbrengen met uw favoriete zoekmachine, om te zoeken naar de plaats waar u deze kunt downloaden en om de relevante API-documentatie te ontdekken.

In de toekomst zijn we van plan om alles te hebben. NET-compatibele SDK's zijn geïntegreerd en doorzoekbaar op één plek: https://docs.microsoft.com/dotnet/api. Daar vindt u referentiedocumentatie voor .NET Framework, .NET Core, .NET Standard en Xamarin, evenals documentatie voor onze Azure NuGet-pakketten. In de komende maanden voegen we meer SDK's toe aan deze ervaring.

Inleiding tot de API-browser

Ons belangrijkste doel is om een IntelliSense-achtige ervaring te bieden voor het doorzoeken van alle .NET-API's vanuit een webbrowser. U kunt zoeken naar een naamruimte, klasse, methode of interface door de volledige of gedeeltelijke naam rechtstreeks op de pagina API-browser te typen.

Als u niet zeker weet tot welke SDK een specifiek type, lid of naamruimte behoort, kunt u gewoon Alle API's selecteren in de vervolgkeuzelijst API-bereik en zoeken in alle beschikbare referentiedocumenten. Als u uw zoekopdracht wilt beperken, kunt u ook een specifiek framework of SDK en de bijbehorende versie selecteren, bijvoorbeeld .NET Framework 4.7, en alleen binnen die set API's zoeken.

De API Browser-ervaring is ook geïntegreerd boven aan de inhoudsopgave voor . OP NET gebaseerde API's, zodat u snel api's kunt vinden, ongeacht waar u zich bevindt in de referentiedocumentatie:

Zodra u zich in een specifieke naamruimte bevindt, is de API-browser alleen gericht op de api-familie die met elkaar zijn verbonden, zodat uw zoekopdracht altijd de best mogelijke resultaten retourneert op basis van uw context.

Ondersteuning voor versiebeheer

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

Gebouwd met open source in gedachten

Voor het bouwen van de API-browser hebben we open standaarden en hulpprogramma's gebruikt. In de kern maakten we gebruik van DocFX , de open documentatie-hulpprogrammaketen, samen met de mdoc-toepassing van Xamarin.

Al onze beheerde referentiedocumentatie wordt nu automatisch gegenereerd op basis van binaire bestanden die worden verzonden op NuGet of deel uitmaken van de hoofdframeworkdistributies, zoals .NET Framework of .NET Core.

Onze infrastructuur voor continue integratie stelt ons in staat om nauwkeurige documentatie te hebben voor de nieuwste API's die nu binnen enkele uren na de release openbaar kunnen zijn en open kunnen staan voor bijdragen. We hebben ook alle .NET API-documentatie gestandaardiseerd op basis van de ECMAXML-indeling, waardoor een consistente en uitgebreide API-weergave wordt gemaakt, ongeacht de SDK die wordt gedocumenteerd. Bovendien hoeft u de complexiteit van de bestandsindeling niet te kennen, omdat u inhoud kunt bijdragen in Markdown, ingesloten in automatisch gegenereerde documenten. Communitybijdragen voor referentiedocumentatie worden binnen de volgende maand ingeschakeld.

Focus op inhoud

Naast de nieuwe ervaringen hebben we ook de referentie-inhoud geoptimaliseerd om beter vindbaar en leesbaar te zijn. We hebben de inhoudsopgave bijgewerkt zodat deze altijd naamruimtegericht is. Of u nu bladert in een naamruimte, type of lid, we laten u altijd alleen de bovenliggende naamruimte zien met alle onderliggende typen & hun respectieve gegroepeerde leden:

Dit betekent dat referentiepagina's overzichtelijk zijn en u eerst de belangrijkste informatie laten zien, zoals algemene overzichten en voorbeelden - allemaal in één oogopslag.

U ziet ook voorbeelden die vanaf het begin relevant voor u zijn, gefilterd op de programmeertaal van uw keuze - u hoeft niet langer naar de onderkant van de pagina te schuiven om deze te vinden.

Feedbackgestuurd

Dit is nog maar het begin van het vernieuwen van de referentiedocumentatie-ervaring. We horen graag uw feedback over hoe we onze documentatie aantrekkelijker en nuttiger kunnen maken en u zo snel mogelijk op weg kunnen helpen. Ga naar onze UserVoice-site en laat ons weten hoe we onze api-browserervaring kunnen verbeteren. U kunt ook altijd contact met ons opnemen via Twitter , @docsmsft, voor snelle updates.