Documentación de la API de .NET que se ha movido de MSDN a docs.microsoft.com

Esta publicación fue escrita por Den Delimarsky, Administrador de programas en la división de nube e inteligencia artificial.

Nos complace anunciar la migración completa 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 documentos de api de o 20% del volumen de toda MSDN Library.

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)
• Además, todas las API de .NET, los SDK y los paquetes NuGet enviados por Microsoft

Buscar en todas las API de Microsoft .NET en un solo lugar con el explorador de API de .NET

¿Alguna vez estaba en una situación en la que está buscando una API, pero no sabe 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 con 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: todo lo que necesita hacer es cambiar la versión del control explorador de API y el contenido se ajustará en consecuencia:

selector de versión de

Organización mejorada

En la tabla de contenido 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étodosy 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 encontrar la API exacta que busca.

de búsqueda en la página del explorador de API de .NET

Los clientes también nos han dicho que, cuando se encuentra en páginas de referencia de 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, la SDK de Azure .NET combina tanto artículos como documentación de referencia, todo en una tabla de contenido.

Direcciones URL intuitivas

Cuando inicialmente lanzamos docs.microsoft.com, uno de nuestros objetivos era tener direcciones URL jerárquicas claras, coherentes e intuitivas. Si recuerda usar MSDN, algunas direcciones URL de .NET se estructuraron de la siguiente manera:

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

Hizo realmente difícil entender lo que es este contenido, simplemente mirandolo.

El vínculo anterior ahora se convierte en esto:

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

Estas son solo algunas de las reglas de dirección URL de nuestro libro de direcciones URL de para garantizar direcciones URL coherentes e intuitivas para .NET:

Espacios de nombres

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

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

Clases

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

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

Métodos

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

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

Ejemplos primero

Una cosa coherente que escuchamos de las entrevistas con los clientes es la importancia de los ejemplos de código funcional, concisa y de alta calidad para las API. En MSDN, se incluyeron ejemplos al final de una página, lo que significa que en algunos ejemplos tendría que desplazarse hacia abajo 20 veces más para ver el primer ejemplo de un tipo. En Docs, los ejemplos son los primeros como se muestra a continuación:

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

selector de idioma de

Ejecutar ejemplos de forma interactiva en el explorador

Al trabajar con código, la mejor manera de aprender es escribir código en realidad: queríamos asegurarnos de que puede hacerlo directamente desde el explorador. Hace un año, hemos implementado el prueba de características de .NETy, a lo largo del año, lo hemos integrado en varios artículos. Al avanzar, continuaremos integrando esta funcionalidad en aún más documentos de API, lo que le permite experimentar sin salir de la página.

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

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

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

Vínculos de MSDN: redireccionamiento a docs.microsoft.com

Al iniciar la migración, queríamos asegurarnos de que no hay vínculos rotos: todos esos vínculos de MSDN que podrían integrarse en productos, entradas de blog y otros sitios deben funcionar correctamente y apuntar a los usuarios a la nueva ubicación, con la ayuda de un redireccionamiento estándar 301.

Listo para las contribuciones de la comunidad

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

Queremos sus comentarios

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