.NET-API-Dokumentation von MSDN zu „docs.microsoft.com“ verschoben

  • Artikel

Dieser Beitrag wurde von Den Delimarsky, Program Manager in der Abteilung „Cloud + AI“, verfasst.

Wir freuen uns, die vollständige Migration aller .NET Framework-Dokumentationen in elf Gebietsschemas von MSDN zu docs.microsoft.com ankündigen zu können. Um das Volumen und die Dimension dieser Migration nachvollziehen zu können, muss erwähnt werden, dass der .NET Framework-Inhalt über neun Millionen API-Dokumentationen bzw. 20 Prozent des Volumens der gesamten MSDN-Bibliothek darstellt.

Ziel ist es, eine einheitliche, moderne und konsistente Benutzeroberfläche bereitzustellen, mit der Sie nach allen von Microsoft bereitgestellten .NET-APIs suchen und zu diesen navigieren können. Außerdem soll es möglich sein, eine tiefgreifende Unterstützung für die Versionsverwaltung einzuschließen, API-Codebeispiele zu verwenden und auszuführen, problemlos API-Updates mithilfe von Automatisierung bereitzustellen und Communitybeiträge zu unterstützen.

docs.microsoft.com stellt diese Benutzeroberfläche für die folgenden Komponenten bereit:

  • .NET Framework (Versionen 1.1 bis 4.7.2)
  • .NET Core (Versionen 1.0 bis 2.1)
  • .NET Standard (Versionen 1.0 bis 2.0)
  • Alle .NET-APIs, SDKs und NuGet-Pakete von Microsoft

Durchsuchen aller Microsoft-.NET-APIs an einem Ort mit dem .NET-API-Browser

Waren Sie jemals in einer Situation, in der Sie nach einer API gesucht haben, aber nicht wussten, wie Sie anfangen sollten? Wir haben einen dedizierten API-Suchindex erstellt, mit dem Sie die erforderlichen APIs innerhalb weniger Sekunden mit Produkt- und Versionsfiltern finden können: den .NET-API-Browser.

.NET-API-Browsersuche

Unterstützung der Versionsverwaltung

Sie müssen sich nicht mehr fragen, ob für einen Typ Member in einer bestimmten Version des .NET Framework oder im Azure Storage-NuGet-Paket verfügbar sind. Sie müssen nur die Version des API-Browsersteuerelements ändern, und der Inhalt wird entsprechend angepasst:

Versionsauswahl in .NET-Dokumentationen

Verbesserte Organisation

Im linken Inhaltsverzeichnis wird der Inhalt nach Namespace und Entitätstypen innerhalb dieses Namespace gruppiert. Wenn Sie beispielsweise eine Klasse auswählen, sehen Sie, dass wir Entitäten nach ihrem jeweiligen Typ gruppieren: Eigenschaften, Felder, Methoden und Ereignisse.

Gruppieren von Entitäten

Alternativ können Sie auch mithilfe des .NET-API-Browsers nach Komponenten suchen und sogar nach bestimmten API-Version im Inhaltsverzeichnis filtern, sodass Sie die gesuchte API leicht finden.

Suche über den .NET-API-Browser

Kund*innen haben uns auch mitgeteilt, dass es auf API-Referenzseiten manchmal schwierig sein kann, die Dokumentation zum Download und Setup sowie andere hilfreiche Dokumentationen für eine API zu finden. Wie Sie in der folgenden Abbildung sehen können, kombiniert das .NET SDK von Azure sowohl Artikel als auch Referenzdokumentationen in einem Inhaltsverzeichnis.

Kombinierte Inhaltsverzeichnisse für Azure-APIs

Intuitive URLs

Als wir ursprünglich docs.microsoft.com gestartet haben, bestand eines unserer Ziele darin, klare, konsistente und intuitive hierarchische URLs zu verwenden. Vielleicht erinnern Sie sich, dass bei der Verwendung von MSDN einige .NET-URLs wie folgt strukturiert waren:

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

Dies machte es wirklich schwierig, den Inhalt nur durch Betrachten zu verstehen.

Der obige Link sieht nun wie folgt aus:

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

Im Folgenden finden Sie einige URL-Regeln aus unserem URL-Buch, 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

Methoden

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

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

Beispiele an erster Stelle

Ein Thema, das in Gesprächen mit Kund*innen immer wieder aufgegriffen wurde, ist die Bedeutung von qualitativ hochwertigen, prägnanten und funktionalen Codebeispielen für APIs. In MSDN wurden Beispiele am Ende einer Seite eingefügt, was bedeutet, dass Sie bei einigen Beispielen mehr als 20 Mal nach unten scrollen müssen, um das erste Beispiel für einen Typ anzuzeigen. In der Dokumentation werden zuerst Beispiele angezeigt, wie unten gezeigt:

Vergleich von Beispielen in MSDN und in der Dokumentation

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

Sprachauswahl in der Dokumentation

Interaktives Ausführen von Beispielen im Browser

Wenn Sie mit Code arbeiten, besteht die beste Möglichkeit zum Lernen darin, Code zu schreiben. Wir wollten sicherstellen, dass Sie dies direkt im Browser tun können. Vor einem Jahr haben wir das Feature zum Testen von .NET eingeführt und im Laufe des Jahres in eine Reihe von Artikeln integriert. In Zukunft werden wir diese Funktionalität in noch mehr API-Dokumente integrieren, sodass Sie experimentieren können, ohne die Seite zu verlassen.

Interaktiver .NET-Code im Browser

Unterstützt von Standardtools für die automatische Generierung

Die gesamte API-Dokumentation zu docs.microsoft.com wird automatisch generiert, sodass wir problemlos die gesamte API-Oberfläche dokumentieren und die Zeit und Häufigkeit von Updates von Wochen auf wenige Minuten verkürzen können. Dadurch wird sichergestellt, dass Sie eine hochwertige API-Dokumentation für alle .NET-APIs erhalten.

Zu diesem Zwecke haben wir mit dem Xamarin-Entwicklungsteam für die Entwicklung und Verwendung von mdoc zusammengearbeitet, um die gesamte .NET-Referenzdokumentation zu generieren.

MSDN-Links: Umleiten zu „docs.microsoft.com“

Als wir mit der Migration begonnen haben, wollten wir sicherstellen, dass keine Links fehlerhaft sind. Alle MSDN-Links, die in Produkte, Blogbeiträge und andere Websites integriert werden können, sollten ordnungsgemäß funktionieren und Benutzer*innen mithilfe der HTTP 301-Standardantwort zum neuen Ort weiterleiten.

Weiterleitung von MSDN zu „docs.microsoft.com“

Bereit für Communitybeiträge

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

Mitarbeit an der Dokumentation

Wir freuen uns über Ihr Feedback!

Wir hoffen, dass Ihnen das neue Inhaltsformat gefällt. Sie können uns Ihr Feedback auf GitHub oder Twitter übermitteln.