Ankündigung einer vereinheitlichten .NET-Referenzdokumentation auf docs.microsoft.com

Dieser Beitrag wurde vom Geschäftsführer des Teams „Azure Growth and Ecosystem“, Jeff Sandquist, verfasst.

Vor fast einem Jahr haben wir mit einem Pilotversuch mit der .NET Core-Referenzdokumentation auf „docs.microsoft.com“ begonnen. Heute geben wir die vereinheitlichte .NET-API-Referenz bekannt. Wir wissen, dass die Entwicklerproduktivität von entscheidender Bedeutung ist – egal ob bei Hobbyentwickler*innen, Startups oder Unternehmen. Angesichts dessen arbeiteten wir eng mit dem Xamarin-Team zusammen, um die Dokumentierung, Erkundung und Navigation im Zusammenhang mit .NET-APIs bei Microsoft zu standardisieren.

Alle .NET-Dokumentationen an einem Ort

Wenn Sie zuvor ein .NET-basiertes SDK von Microsoft gesucht haben, mussten Sie einige Zeit mit der Suche in Ihrem bevorzugten Suchmodul verbringen, um sowohl die relevante API-Dokumentation als auch den Ort zu finden, an dem Sie das SDK herunterladen können.

In Zukunft planen wir, alle .NET-konformen SDKs vereinheitlicht und durchsuchbar unter https://docs.microsoft.com/dotnet/api bereitzustellen. Dort finden Sie die Referenzdokumentation für das .NET Framework, .NET Core, .NET Standard und Xamarin sowie die Dokumentation für unsere Azure-NuGet-Pakete. In den kommenden Monaten werden wir dort weitere SDKs hinzufügen.

Einführung in den API-Browser

Unser Hauptziel ist es, eine IntelliSense-ähnliche Funktion bereitzustellen, um alle .NET-APIs über einen Webbrowser zu durchsuchen. Sie können nach einem Namespace, einer Klasse, einer Methode oder einer Schnittstelle suchen, indem Sie den vollständigen oder partiellen Namen direkt auf der API-Browserseite eingeben.

Wenn Sie nicht sicher sind, zu welchem SDK ein bestimmter Typ, Member oder Namespace gehört, können Sie in der Dropdownliste für den API-Bereich einfach Alle APIs auswählen und alle verfügbaren Referenzdokumenten durchsuchen. Wenn Sie Ihre Suche einschränken möchten, können Sie alternativ ein bestimmtes Framework oder SDK sowie dessen Version auswählen (z. B. .NET Framework 4.7) und nur innerhalb dieser Gruppe von APIs suchen.

Die API-Browserfunktion ist auch am Anfang des Inhaltsverzeichnisses für .NET-basierte APIs integriert, sodass Sie schnell alle APIs finden, unabhängig davon, an welcher Stelle Sie sich in der Referenzdokumentation befinden:

Sobald Sie sich in einem bestimmten Namespace befinden, ist der API-Browser nur auf die Familie von APIs festgelegt, die miteinander verbunden sind, sodass Ihre Suche immer die bestmöglichen Ergebnisse basierend auf Ihrem Kontext zurückgibt.

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:

Erstellung unter Berücksichtigung des Open-Source-Ansatzes

Zum Erstellen des API-Browsers haben wir offene Standards und Tools verwendet. Im Kern haben wir DocFX, also die offene Toolkette für die Dokumentationsgenerierung, zusammen mit der mdoc-Anwendung von Xamarin verwendet.

Alle unsere verwalteten Referenzdokumentationen werden jetzt automatisch aus Binärdateien generiert, die in NuGet enthalten sind oder Teil der Hauptframeworkdistributionen sind (z. B. das .NET Framework oder .NET Core).

Unsere Continuous-Integration-Infrastruktur ermöglicht es uns, eine genaue Dokumentation für die neuesten APIs bereitzustellen, die jetzt innerhalb weniger Stunden nach der Veröffentlichung für Beiträge öffentlich zugänglich sein können. Wir haben auch die gesamte .NET-API-Dokumentation im ECMAXML-Format standardisiert, wodurch unabhängig vom dokumentierten SDK eine konsistente und umfassende API-Darstellung ermöglicht wird. Darüber hinaus müssen Sie die Feinheiten des Dateiformats nicht kennen, da Sie Inhalte in Markdown beitragen können, eingebettet in automatisch generierte Dokumente. Communitybeiträge zur Referenzdokumentation werden innerhalb des nächsten Monats aktiviert.

Fokus auf Inhalte

Zusätzlich zu den neuen Funktionen haben wir auch den Referenzinhalt optimiert, damit er besser erkennbar und leichter lesbar ist. Wir haben das Inhaltsverzeichnis aktualisiert, damit es immer namespaceorientiert ist. Unabhängig davon, ob Sie Informationen zu einem Namespace, Typ oder Member durchsuchen, zeigen wir Ihnen immer nur den übergeordneten Namespace mit allen untergeordneten Typen & der jeweiligen gruppierten Mitglieder an:

Dies bedeutet, dass Referenzseiten aufgeräumter sind und Ihnen zuerst die wichtigsten Informationen auf einen Blick anzeigen (z. B. allgemeine Übersichten und Beispiele).

Ihnen werden auch gleich am Anfang Beispiele angezeigt, die für Sie relevant und nach der Programmiersprache Ihrer Wahl gefiltert sind. Sie müssen nicht mehr nach ganz unten auf der Seite scrollen, um diese zu finden.

Berücksichtigung von Feedback

Dies ist erst der Anfang der Überarbeitung der Referenzdokumentation. Übermitteln Sie uns Ihr Feedback, wie wir unsere Dokumentation ansprechender und nützlicher gestalten können, damit Sie die gewünschten Elemente schnellstmöglich finden. Besuchen Sie unsere UserVoice-Website, und teilen Sie uns mit, wie wir unsere API-Browserfunktion verbessern können. Sie können sich auch jederzeit auf Twitter an uns wenden (@docsmsft), um schnell Informationen zu erhalten.