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

Ce billet a été écrit par Den Delimarsky, responsable de programme au sein de la division Cloud + AI.

Nous sommes ravis de vous annoncer que la migration de la documentation .NET Framework de MSDN vers docs.microsoft.com pour 11 paramètres régionaux est entièrement terminée. Pour comprendre le volume et l’importance de cette migration, sachez que le contenu .NET Framework représente plus de 9 millions de documents sur les API, soit 20 % de l’ensemble de la bibliothèque MSDN.

Les objectifs sont multiples : fournir une expérience unifiée, moderne et cohérente pour localiser et parcourir toutes les API .NET fournies par Microsoft, inclure une prise en charge complète de la gestion de versions, utiliser et exécuter des exemples de code d’API, activer facilement les mises à jour d’API grâce à l’automatisation et prendre en charge les contributions de la communauté.

Sur docs.microsoft.com, cette expérience est possible pour :

• .NET Framework (versions 1.1 à 4.7.2)
• .NET Core (versions 1.0 à 2.1)
• .NET Standard (versions 1.0 à 2.0)
• Ainsi que l’ensemble des API .NET, kits SDK et packages NuGet fournis par Microsoft

Explorer toutes les API Microsoft .NET au même endroit avec le navigateur d’API .NET

Avez-vous déjà tenté de rechercher une API sans vraiment savoir par où commencer ? Nous avons créé un index de recherche des API dédié, appelé navigateur d’API .NET, pour vous permettre de trouver rapidement les API dont vous avez besoin en quelques secondes, avec des filtres par produit et par version.

Prise en charge de la gestion de versions

Vous n’avez plus à vous demander si un type a des membres disponibles dans une version spécifique du .NET Framework ou du package NuGet Stockage Azure. Il vous suffit de changer la version dans le contrôle du navigateur d’API pour que le contenu soit ajusté en conséquence :

Organisation améliorée

Dans la table des matières de gauche, le contenu est regroupé par espace de noms et types d’entités au sein de cet espace de noms. Par exemple, quand vous sélectionnez une classe, les entités sont regroupées en fonction de leur type respectif : Propriétés, Champs, Méthodes et Événements.

Pour trouver facilement l’API qui vous intéresse, vous pouvez également lancer une recherche avec le navigateur d’API .NET et filtrer sur une version d’API spécifique, le tout à partir de la table des matières.

Les clients nous ont également indiqué qu’il est parfois difficile de trouver le téléchargement, l’installation et d’autres documents utiles pour une API lorsqu’ils se trouvent dans les pages de référence des API. Comme vous pouvez le voir dans l’image ci-dessous, le SDK Azure .NET combine les articles et la documentation de référence dans une seule table des matières.

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. Dans MSDN, si vous vous en souvenez, certaines URL .NET étaient structurées comme ceci :

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

Il était très difficile de comprendre le contenu du lien simplement en examinant l’URL.

Le lien ci-dessus se présente maintenant comme ceci :

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

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

Espaces de noms

Modèle : https://docs.microsoft.com/{locale}/dotnet/api/{namespace}

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

Classes

Modèle : https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}

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

Méthodes

Modèle : https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}

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

Exemples en premier

Une chose qui ressort souvent de nos entretiens avec nos clients est l’importance d’avoir des exemples de code de qualité, succincts et fonctionnels pour chaque API. Dans MSDN, les exemples se trouvaient en bas de page, ce qui vous obligeait dans certains cas à faire défiler l’écran plus de 20 fois pour accéder au premier exemple. Sur docs, les exemples sont listés en premier, comme vous pouvez le voir ici :

Comme MSDN, docs prend en charge tous les langages .NET, notamment C#, VB, F# et C++.

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

En programmation, la meilleure façon d’apprendre est d’écrire du code. C’est pourquoi nous tenions à ce que vous puissiez le faire directement dans le navigateur. Il y a un an, nous avons déployé la fonctionnalité Essayer .NET, puis nous l’avons intégrée à un certain nombre d’articles tout au long de l’année. À l’avenir, nous continuerons à intégrer cette fonctionnalité à d’autres documents d’API afin de vous permettre de faire des expériences sans quitter la page où vous vous trouvez.

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

Toute la documentation sur les API sur docs.microsoft.com est générée automatiquement, ce qui nous permet de documenter facilement l’ensemble de la surface des API et de réduire le temps et la fréquence des mises à jour de quelques semaines à quelques minutes. De cette façon, vous bénéficiez d’une documentation de qualité pour toutes les API .NET.

Pour ce faire, nous travaillons en partenariat avec l’équipe d’ingénierie de Xamarin au développement de mdoc afin de générer l’ensemble de la documentation de référence .NET.

Redirection des liens MSDN vers docs.microsoft.com

Quand nous avons commencé la migration, nous voulions nous assurer qu’aucun lien n’était rompu. Tous les liens MSDN intégrés à des produits, billets de blog et autres sites devaient fonctionner correctement et pointer les utilisateurs vers le nouvel emplacement avec un code 301 redirect standard.

Contenu prêt à recevoir les contributions de la communauté

Tout le contenu migré est désormais open source, dans le dépôt dotnet/dotnet-api-docs sur GitHub. Mais vous n’avez pas besoin de rechercher des fichiers pour apporter vos contributions. Accédez simplement à l’une des pages d’API .NET et cliquez sur Modifier pour accéder directement au fichier que vous souhaitez modifier.

Vos commentaires nous intéressent

Nous espérons que vous apprécierez le nouveau format de contenu. Faites-nous part de vos commentaires sur GitHub ou Twitter.