La documentación de la API de .NET se ha trasladado de MSDN a docs.microsoft.com.

El autor de esta publicación es Den Delimarsky, administrador de programas en la división Cloud + AI.

Nos complace anunciar la finalización de la migración de toda la documentación de .NET Framework en 11 configuraciones regionales de MSDN a docs.microsoft.com. Para comprender el volumen y la escala de esta migración, el contenido de .NET Framework representa más de 9 millones de documentación de API o el 20 % del volumen de toda la biblioteca de MSDN.

El objetivo es proporcionar una experiencia unificada, moderna y coherente para buscar y navegar por todas las API de .NET enviadas por Microsoft, incluir compatibilidad profunda con el control de versiones, usar y ejecutar ejemplos de código de API, habilitar fácilmente las actualizaciones de API mediante automatización y admitir contribuciones de la comunidad.

docs.microsoft.com habilita esta experiencia para:

• .NET Framework (versiones 1.1 - 4.7.2)
• .NET Core (versiones 1.0 - 2.1)
• .NET Standard (versiones 1.0 - 2.0)
• Y todas las API de .NET, los SDK y los paquetes NuGet enviados por Microsoft.

Búsqueda de todas las API de Microsoft .NET en un solo lugar con el Explorador de API de .NET

¿Se ha encontrado alguna vez en una situación en la que busca una API, pero no sabe por dónde empezar? Hemos creado un índice de búsqueda de API dedicado, lo que le permite encontrar rápidamente las API necesarias en cuestión de segundos, con filtros de producto y versión: el Explorador de API de .NET.

Compatibilidad de versiones

Ya no tiene que preguntarse si un tipo tiene miembros disponibles en una versión específica de .NET Framework o el paquete NuGet de Azure Storage; lo único que debe hacer es cambiar la versión desde el control Explorador de API y el contenido se ajustará en consecuencia:

Organización mejorada

En la tabla de contenido de la izquierda, el contenido se agrupa por espacio de nombres y tipos de entidades dentro de ese espacio de nombres. Al seleccionar una clase, por ejemplo, verá que agrupamos entidades por su tipo respectivo: Propiedades, Campos, Métodos y Eventos.

Como alternativa, también puede buscar con la ayuda del Explorador de API de .NET e incluso filtrar una versión de API específica, todo desde la tabla de contenido, lo que facilita la búsqueda de la API exacta que está buscando.

Los clientes también nos han dicho que, cuando se encuentran dentro de las páginas de referencia de la API, a veces puede ser difícil encontrar la descarga, la configuración y otra documentación útil para una API. Como puede ver en la imagen siguiente, el SDK de .NET de Azure combina artículos y documentación de referencia, todo en una tabla de contenido.

Direcciones URL intuitivas

Cuando pusimos en marcha originalmente docs.microsoft.com, uno de nuestros objetivos era tener direcciones URL jerárquicas claras, coherentes e intuitivas. Si recuerda el uso de MSDN, algunas direcciones URL de .NET estaban estructuradas así:

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

Resultaba muy difícil reconocer un contenido con solo mirarlo.

El vínculo anterior pasa a ser ahora el siguiente:

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

Estas son algunas de las reglas de direcciones URL de nuestro Libro de direcciones URL para garantizar unas direcciones URL coherentes e intuitivas para .NET:

Espacios de nombres

Patrón: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}

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

Clases

Patrón: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}

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

Métodos

Patrón: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}

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

Ejemplos en primer lugar

Una de las cosas que hemos escuchado repetidamente en las entrevistas con los clientes es la importancia de contar con ejemplos de código de alta calidad, concisos y funcionales para las API. En MSDN, los ejemplos se incluían al final de la página, lo que significaba que en algunos ejemplos había que desplazarse hacia abajo más de 20 veces para ver el primer ejemplo de un tipo. En Docs, los ejemplos se muestran primero como se muestra a continuación:

Al igual que MSDN, Docs admite todos los lenguajes .NET, incluidos C#, VB, F# y C++.

Ejecución interactiva de ejemplos en el explorador

Cuando se trabaja con código, la mejor manera de aprender es escribirlo realmente; queríamos asegurarnos de que se pudiera hacer directamente desde el navegador. Hace un año, lanzamos la característica Probar .NET, y a lo largo del año la hemos integrado en varios artículos. En el futuro, seguiremos integrando esta funcionalidad en más documentos de API, lo que le permitirá experimentar sin salir de la página.

Compatible con las herramientas de generación automática estándar

Toda la documentación de API en docs.microsoft.com se genera automáticamente, lo que nos permite documentar fácilmente toda la superficie de la API y mejorar drásticamente el tiempo y la frecuencia de las actualizaciones de semanas a minutos. De este modo, se garantiza la obtención de una documentación de API de calidad para todas las API de .NET.

Para ello, nos hemos asociado con el equipo de ingeniería de Xamarin para desarrollar y utilizar mdoc para generar toda la documentación de referencia de .NET.

Vínculos de MSDN: redirección a docs.microsoft.com

Al iniciar la migración, queríamos asegurarnos de que no se rompiera ningún vínculo: todos los vínculos de MSDN que pudieran estar integrados en productos, entradas de blog y otros sitios deberían funcionar correctamente y dirigir a los usuarios a la nueva ubicación, con la ayuda de una redirección 301 estándar.

Listo para las contribuciones de la comunidad

Todo el contenido migrado es ahora de código abierto, en el repositorio dotnet/dotnet-api-docs en GitHub. Pero no tiene que buscar los archivos para hacer sus contribuciones: simplemente vaya a cualquiera de las páginas de la API de .NET y haga clic en Editar, y se le llevará directamente al archivo en el que desea hacer cambios.

Queremos su opinión

Esperamos que disfrute del nuevo formato de contenido: envíenos sus comentarios en GitHub o Twitter.