Documentation sur l’API .NET déplacée de MSDN vers docs.microsoft.com

Ce billet a été écrit par den Delimarsky, responsable de programme dans la Division Cloud + IA.

nous sommes ravis d’annoncer la migration complète de toutes les .NET Framework documentation dans 11 paramètres régionaux de MSDN vers docs.microsoft.com. pour comprendre le volume et l’échelle de cette migration, le contenu .NET Framework représente plus de 9 millions documents d’API ou 20% du volume de l’ensemble de la bibliothèque MSDN.

L’objectif est de fournir une expérience unifiée, moderne et cohérente pour rechercher et parcourir toutes les API .NET fournies par Microsoft, inclure la prise en charge complète du contrôle de version, utiliser et exécuter des exemples de code API, activer facilement les mises à jour d’API à l’aide d’Automation et prendre en charge les contributions de la communauté.

docs.Microsoft.com permet cette expérience pour :

  • .NET Framework (versions 1,1-4.7.2)
  • .NET Core (versions 1,0-2,1)
  • .NET Standard (versions 1,0-2,0)
  • et toutes les api .net, les kits de développement logiciel (sdk) et les packages NuGet fournis par Microsoft

Rechercher toutes les API de Microsoft .NET dans un même emplacement avec le navigateur de l’API .NET

Étiez-vous déjà dans une situation où vous recherchez une API, mais vous ne savez pas par où commencer ? Nous avons créé un index de recherche d’API dédié, qui vous permet de trouver rapidement les API nécessaires en quelques secondes, à l’aide des filtres de produit et de version, le navigateur d’API .net.

Recherche dans le navigateur de l’API .NET

Prise en charge du contrôle de version

vous n’avez plus à vous demander si des membres sont disponibles dans une version spécifique de .NET Framework ou dans le package de NuGet stockage Azure. il vous suffit de modifier la version à partir du contrôle de l’API de l’API et le contenu est ajusté en conséquence :

Sélecteur de version dans les documents .NET

Organisation améliorée

Dans la table des matières de gauche, le contenu est regroupé par espace de noms et les types d’entités au sein de cet espace de noms. Lorsque vous sélectionnez une classe, par exemple, vous verrez que nous regroupons les entités en fonction de leur type respectif : Propriétés, champs, méthodeset événements.

Regroupement d’entités

Vous pouvez également effectuer une recherche avec l’aide du navigateur de l’API .NET et même filtrer une version d’API spécifique, le tout à partir de la table des matières, ce qui facilite la recherche de l’API exacte que vous recherchez.

Recherche en page dans l’Explorateur d’API .NET

Les clients nous ont également indiqué que lorsque vous vous trouvez dans les pages de référence des API, il peut parfois être difficile de trouver le téléchargement, l’installation et d’autres documents utiles pour une API. Comme vous pouvez le voir dans l’image ci-dessous, le Kit de développement logiciel (SDK) Azure .net combine les articles et la documentation de référence, le tout dans une table des matières.

Table des matières fusionnées dans les API Azure

URL intuitives

Lors du lancement de docs.Microsoft.com, l’un de nos objectifs était d’avoir des URL hiérarchiques claires, cohérentes et intuitives. Si vous vous rappelez à l’aide de MSDN, certaines URL .NET étaient structurées comme suit :

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

Il a été très difficile de comprendre ce contenu, en examinant simplement ce contenu.

Le lien ci-dessus devient alors :

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

Voici quelques-unes des règles d’URL de notre livre d’URL pour garantir des URL cohérentes et intuitives pour .net :

Espaces de noms

Modèle:

Example :

Classes

Modèle:

Example :

Méthodes

Modèle:

Example :

Exemples d’abord

L’importance des exemples de code de haute qualité, succincts et fonctionnels pour les API est l’un des atouts que nous avons entendus pour les entretiens avec les clients. Dans MSDN, des exemples étaient inclus à la fin d’une page, ce qui signifie, dans certains exemples, que vous auriez besoin de faire défiler plus de 20 fois pour voir le premier exemple d’un type. Sur docs, les exemples sont d’abord répertoriés ci-dessous :

Comparaison des exemples entre MSDN et docs

comme MSDN, Docs prend en charge tous les langages .net, y compris C#, VB, F # et C++

Sélecteur de langue dans docs

Exécuter des exemples de manière interactive dans le navigateur

Lorsque vous travaillez avec du code, la meilleure façon d’apprendre consiste à écrire du code. nous voulons nous assurer que vous pouvez le faire directement à partir du navigateur. Il y a un an, nous avons déployé la fonctionnalité try .netet, jusqu’à l’année, nous l’avons intégrée dans un certain nombre d’articles. À l’avenir, nous continuerons à intégrer cette fonctionnalité dans encore plus de documents d’API, ce qui vous permettra d’expérimenter sans quitter la page.

Code .NET interactif dans le navigateur

Pris en charge par les outils de génération automatique standard

Toute la documentation de l’API sur docs.Microsoft.com est générée automatiquement, ce qui nous permet de documenter facilement l’intégralité de la surface de l’API et d’améliorer considérablement le temps et la fréquence des mises à jour de quelques semaines à quelques minutes. Cela permet d’obtenir la documentation de l’API de qualité pour toutes les API .NET.

Pour ce faire, nous avons conclu un partenariat avec l’équipe d’ingénierie Xamarin pour développer et utiliser mdoc afin de générer l’ensemble de la documentation de référence .net.

À mesure que nous avons commencé la migration, nous voulons nous assurer qu’aucun lien n’est rompu : tous les liens MSDN qui peuvent être intégrés aux produits, les billets de blog et les autres sites doivent fonctionner correctement et pointer les utilisateurs vers le nouvel emplacement, à l’aide d’une redirection standard 301.

Redirection de MSDN vers docs.microsoft.com

Prêt pour les contributions de la communauté

Tout le contenu migré est maintenant Open source, dans le référentiel dotnet/dotnet-API-docs sur GitHub. Mais vous n’avez pas besoin de rechercher des fichiers pour faire vos contributions. il vous suffit d’accéder à n’importe quelle page de l’API .NET et de cliquer sur modifierpour accéder directement au fichier auquel vous souhaitez apporter des modifications.

Contribuer à la documentation

Vos commentaires nous intéressent

nous espérons que vous appréciez le nouveau format de contenu. veuillez nous envoyer vos commentaires sur GitHub ou Twitter.