.NET API documentation moved from MSDN to docs.microsoft.com

This post was written by Den Delimarsky, Program Manager in the Cloud + AI Division.

We're excited to announce the completed migration of all .NET Framework documentation in 11 locales from MSDN to docs.microsoft.com. To understand the volume and scale of this migration, the .NET Framework content represents over 9 million API docs or 20% of the volume of the entire MSDN Library.

The goal is to provide a unified, modern, and consistent experience to find and navigate all .NET APIs shipped by Microsoft, include deep support for versioning, use and run API code samples, easily enable API updates using automation, and support community contributions.

docs.microsoft.com enables this experience for:

• .NET Framework (versions 1.1 - 4.7.2)
• .NET Core (versions 1.0 - 2.1)
• .NET Standard (versions 1.0 - 2.0)
• And all .NET APIs, SDKs, and NuGet packages shipped by Microsoft

Search all Microsoft .NET APIs in one place with the .NET API Browser

Were you ever in a situation where you are looking for an API, but you just don't know where to start? We have built a dedicated API search index, enabling you to quickly find the necessary APIs within seconds, with product and version filters - the .NET API Browser.

Versioning Support

You no longer have to wonder whether a type has members available in a specific version of .NET Framework or the Azure Storage NuGet package - all you need to do is change the version from the API Browser control, and the content will adjust accordingly:

Improved organization

In the left table of contents, content is grouped by namespace and types of entities within that namespace. When you select a class, for example, you will see that we group entities by their respective type: Properties, Fields, Methods, and Events.

Alternatively, you can also search with the help of the .NET API Browser and even filter a specific API version, all from the table of contents, making it easy to find the exact API you are looking for.

Customers have also told us that when you are within API reference pages, it can sometimes be difficult to find download, setup, and other helpful documentation for an API. As you can see in the image below, the Azure .NET SDK combines both articles and reference documentation, all in one table of contents!

Intuitive URLs

When we originally launched docs.microsoft.com, one of our goals was to have clear, consistent, and intuitive hierarchical URLs. If you recall using MSDN, some .NET URLs were structured like this:

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

It made it really hard to understand what this content is, just by looking at it.

The link above now becomes this:

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

Here are just some of the URL rules from our Book of URLs to ensure consistent and intuitive URLs for .NET:

Namespaces

Pattern: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}

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

Classes

Pattern: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}

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

Methods

Pattern: https://docs.microsoft.com/{locale}/dotnet/api/{namespace}.{class}.{method}

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

Examples first

One consistent thing we heard from interviews with customers is the importance of high quality, succinct, and functional code examples for APIs. In MSDN, examples were included at the end of a page, meaning in some examples you would need to scroll down 20+ times to see the first example for a type. On Docs, examples are first as shown below:

Like MSDN, Docs supports all .NET languages including C#, VB, F#, and C++

Run examples interactively in the browser

When working with code, the best way to learn is to actually write code - we wanted to make sure that you can do that right from the browser. A year ago, we rolled out the Try .NET feature, and through the year we've integrated it in a number of articles. Moving forward, we will continue integrating this functionality in even more API documents, allowing you to experiment without leaving the page.

Supported by standard auto-generation tooling

All API documentation on docs.microsoft.com is automatically generated, allowing us to easily document the entire API surface, and dramatically improving the time and frequency of updates from weeks to minutes. This ensures that you get quality API documentation for all .NET APIs.

To do this, we partnered with the Xamarin engineering team to develop and use mdoc to generate all .NET Reference documentation.

MSDN links - redirecting to docs.microsoft.com

As we started the migration, we wanted to ensure that no links are broken - all those MSDN links that might be integrated in products, blog posts and other sites should work properly and point users to the new location, with the help of a standard 301 redirect.

Ready for community contributions

All migrated content is now open source, in the dotnet/dotnet-api-docs repository on GitHub. But you don't have to search for files to make your contributions - simply go to any of the .NET API pages and click Edit, and you'll be taken directly to the file to which you'd like to make changes.

We want your feedback

We hope you enjoy the new content format - please send us your feedback on GitHub or Twitter.