.NET-API-Dokumentation von MSDN zu docs.microsoft.com

Dieser Beitrag wurde von Den Delimarsky, Program Manager in der Cloud + AI Division geschrieben.

Wir freuen uns, die vollständige Migration aller .NET Framework-Dokumentationen in 11 Gebietsschemas von MSDN zu docs.microsoft.combekannt zu geben. Um das Volumen und die Skalierung dieser Migration zu verstehen, stellt der .NET Framework-Inhalt über 9 Millionen API-Dokumente oder 20% des Volumens der gesamten MSDN Library dar.

Ziel ist es, eine einheitliche, moderne und konsistente Oberfläche bereitzustellen, um alle von Microsoft ausgelieferten .NET-APIs zu finden und zu navigieren, umfassende Unterstützung für Versionsverwaltung, Verwendung und Ausführung von API-Codebeispielen, einfache Aktivierung von API-Updates mithilfe von Automatisierung und Unterstützung von Communitybeiträgen.

docs.microsoft.com ermöglicht diese Erfahrung für:

• .NET Framework (Version 1.1 - 4.7.2)
• .NET Core (Version 1.0 - 2.1)
• .NET Standard (Version 1.0 - 2.0)
• Und alle .NET-APIs, SDKs und NuGet-Pakete, die von Microsoft ausgeliefert werden

Durchsuchen aller Microsoft .NET-APIs an einer zentralen Stelle mit dem .NET-API-Browser

Waren Sie jemals in einer Situation, in der Sie nach einer API suchen, aber Sie wissen nicht, wo Sie beginnen sollen? Wir haben einen dedizierten API-Suchindex erstellt, mit dem Sie die erforderlichen APIs innerhalb von Sekunden schnell finden können, mit Produkt- und Versionsfiltern – dem .NET-API-Browser.

Versionsverwaltungsunterstützung

Sie müssen sich nicht mehr fragen, ob ein Typ Mitglieder in einer bestimmten Version von .NET Framework oder dem Azure Storage NuGet-Paket verfügbar hat . Alles, was Sie tun müssen, ist, die Version aus dem API-Browser-Steuerelement zu ändern, und der Inhalt wird entsprechend angepasst:

Verbesserte Organisation

Im linken Inhaltsverzeichnis werden Inhalte nach Namespace und Entitätstypen innerhalb dieses Namespaces gruppiert. Wenn Sie beispielsweise eine Klasse auswählen, werden wir Entitäten nach ihrem jeweiligen Typ gruppieren: Eigenschaften, Felder, Methodenund Ereignisse.

Alternativ können Sie auch mit Hilfe des .NET-API-Browsers suchen und sogar eine bestimmte API-Version filtern, die alle aus dem Inhaltsverzeichnis stammt und die genaue API, nach der Sie suchen, leicht zu finden.

Kunden haben uns auch mitgeteilt, dass es manchmal schwierig sein kann, Download, Setup und andere hilfreiche Dokumentationen für eine API zu finden, wenn Sie sich auf API-Referenzseiten befinden. Wie Sie in der abbildung unten sehen können, kombiniert das Azure .NET SDK sowohl Artikel als auch Referenzdokumentation, alles in einem Inhaltsverzeichnis!

Intuitive URLs

Als wir ursprünglich docs.microsoft.comgestartet haben, war eines unserer Ziele, klare, konsistente und intuitive hierarchische URLs zu haben. Wenn Sie die Verwendung von MSDN zurückrufen, wurden einige .NET-URLs wie folgt strukturiert:

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

Es hat es wirklich schwer gemacht, zu verstehen, was dieser Inhalt ist, nur durch einen Blick darauf.

Der obige Link wird nun wie folgt:

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

Hier sind nur einige der URL-Regeln aus unserem Book of URLs, um konsistente und intuitive URLs für .NET sicherzustellen:

Namespaces

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

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

Klassen

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

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

Methodik

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

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

Beispiele zuerst

Eine einheitliche Sache, die wir von Interviews mit Kunden gehört haben, ist die Bedeutung von qualitativ hochwertigen, prägnanten und funktionalen Codebeispielen für APIs. In MSDN wurden Beispiele am Ende einer Seite eingeschlossen, d. h. in einigen Beispielen müssten Sie 20 Mal nach unten scrollen, um das erste Beispiel für einen Typ anzuzeigen. Beispiele für Dokumente sind zuerst wie unten dargestellt:

Wie MSDN unterstützt Docs alle .NET-Sprachen, einschließlich C#, VB, F# und C++

Interaktives Ausführen von Beispielen im Browser

Beim Arbeiten mit Code ist die beste Möglichkeit, Code zu schreiben – wir wollten sicherstellen, dass Sie dies direkt über den Browser erledigen können. Vor einem Jahr haben wir das feature Try .NET featureeingeführt, und im Laufe des Jahres haben wir es in eine Reihe von Artikeln integriert. In Zukunft werden wir diese Funktionalität weiterhin in noch mehr API-Dokumente integrieren, sodass Sie experimentieren können, ohne die Seite verlassen zu müssen.

Unterstützt durch standardmäßige Tools für die automatische Generierung

Alle API-Dokumentationen zu docs.microsoft.com werden automatisch generiert, sodass wir ganz einfach die gesamte API-Oberfläche dokumentieren und die Zeit und Häufigkeit von Updates von Wochen zu Minuten erheblich verbessern können. Dadurch wird sichergestellt, dass Sie die Qualitäts-API-Dokumentation für alle .NET-APIs erhalten.

Dazu haben wir uns mit dem Xamarin Engineering-Team zusammengetan, um mdoc- zu entwickeln und zu verwenden, um alle .NET-Referenzdokumentationen zu generieren.

MSDN-Links – Umleitung zu docs.microsoft.com

Als wir mit der Migration begonnen haben, wollten wir sicherstellen, dass keine Links unterbrochen werden – alle MSDN-Links, die möglicherweise in Produkte, Blogbeiträge und andere Websites integriert werden, sollten ordnungsgemäß funktionieren und Benutzer auf den neuen Speicherort verweisen, mit Hilfe einer Standard-301-Umleitung.

Bereit für Communitybeiträge

Alle migrierten Inhalte sind jetzt Open Source, im dotnet/dotnet-api-docs Repository auf GitHub. Sie müssen jedoch nicht nach Dateien suchen, um Ihre Beiträge zu leisten . Wechseln Sie einfach zu einer der .NET-API-Seiten, und klicken Sie auf Bearbeiten, und Sie werden direkt zu der Datei weitergeleitet, zu der Sie Änderungen vornehmen möchten.

Wir möchten Ihr Feedback

Wir hoffen, dass Sie das neue Inhaltsformat genießen - senden Sie uns bitte Ihr Feedback zu GitHub- oder Twitter-.