September 2019 .NET/ASP.NET Documentation Update

TLDR; This is a status update on the .NET documentation. If you want me to do more of those (once a month), please let me know in the comments!

Comment: If you have suggestions, please let me know in the comments. Any product feedback will be forwarded to the proper product team.

Hi everyone!

This is the fourth month where I post a summary of all .NET-related documentation that was significantly updated. This month covers all changes from September 1st to September 27th.

My name is Maxime Rouiller and I’m a Cloud Advocate with Microsoft. For this month, I’m covering three major products:

For this month, I’ll be trying something new. I will not be leaving a comment beside each article and will instead use a Legend with emojis (I know, it’s Reddit. What am I doing!?). Thing is, it’s easier to show you what’s what than explain it. Where relevant, I will leave notes.


  • 📢: Major/Main article that everyone will want to read
  • 💥: Important/Must read.
  • ✨: Brand new page

Note: It’s not because a page doesn’t have an icon that it is not important. Everything here is either brand new or significantly modified.

Themes this month

.NET Core 3.0

  • What’s new for Preview 9 and GA release
  • JSON serialization
  • CLI updates

Managed Languages

.NET Core

E-book - Blazor for Web Forms Developers (Preview) ✨

Are you a Web Forms developer? This book is brand new and will help you bridge your knowledge between Web Forms and Blazor.

More content should be coming in the next few months.

❗ Don’t forget that you can download all e-books with the Download PDF button in the bottom left of your screen (desktop) or through the Content menu if you are on mobile. ❗

E-book - Architecting Cloud Native .NET Applications for Azure (Preview)

Are you a developer, a lead or even an architect? Do you want to know how to build an application that is made for the cloud?

This is the book for you.

❗ Don’t forget that you can download all e-books with the Download PDF button in the bottom left of your screen (desktop) or through the Content menu if you are on mobile. ❗

E-book - ASP.NET Core gRPC for WCF Developers (Preview) 💥✨

Lots of you have asked me last month about how to handle gRPC coming from a WCF point of view. Well, this month is your time to shine. There’s a literal book being currently written about it. The whole thing is brand new and is aimed at developers that were, surprise surprise, using WCF before.

This book takes you from migration, load balancing, Kubernetes, error handling, security, and to why even use it. It’s a must-read.

❗ Don’t forget that you can download all e-books with the Download PDF button in the bottom left of your screen (desktop) or through the Content menu if you are on mobile. ❗

Compatibility 💥

When you’re upgrading your app from one version of .NET Core to another, you might be interested to know if there were any compatibility changes introduced that could impact your app. The list is not final yet so there will be more breaking changes added in the next few months. You have the option to look at them by version or feature area:

Desktop Guide for Windows Presentation Foundation (WPF) 💥✨

We’re revamping the WPF content and giving it a new home called “Desktop Guide”. This guide will cover WPF for both .NET Core and .NET Framework, with an emphasis on .NET Core. This guide will continue to grow over time as the team modernizes and bring more relevant content into it.

Whether you like XAML or not, it’s a good thing to remember as there are tons of WPF applications in the wild and your chances of encountering one is mostly guaranteed.

This guide may save you some time in the future.

.NET Framework

Updates to the actual .NET Framework content. Not Core related.

.NET Guide - Assemblies in .NET

Everything you ever wanted or didn’t want to know about assemblies in .NET. To sign or not to sign isn’t the question. Did you know? That is the question.

The assemblies content used to be in the .NET Framework guide and was now moved to where our .NET Fundamentals content live. It’s now applicable to both .NET Framework and .NET Core.

Tooling, tutorial, serialization, exceptions, and others

Machine learning tutorial? Yes. We haven’t gotten enough of them that’s for sure. Machine learning is becoming omnipresent and starting with a tutorial sure is a good way to learn.

The JSON serializer is brand new. Have you tried it? Those articles are your perfect start to understanding how it works. Including the most fun data type to serialize, DateTime and DateTimeOffset.

With the new tooling and .NET being used on the daily, you’re bound to run into issues. The first article handles the possible issues you might run into. The second shows you how to make localized exception messages. Neat 🤖📷.





If you are now reading this, it’s because you are a fan of WebAssembly(aka WASM). Enjoy this small update.

Server-side Blazor has hit GA while the client-side is still in Preview.


Lots of fundamental articles have been updated to the 3.0 release.

You will find here updated articles, samples, and general tidying of articles (typos, more snippets, clarifications).


So you’re not the book kind of developer. You’d rather jump in the code and try right away. I get that. After you get up to date as to what is gRPC on .NET Core, we’re getting right into how to integrate with gRPC services. Straight to the code.


Updated article about testing controller logic. Finally, there were some docs missing about Tag Helpers. This is now a solved problem. See below.


We were missing a page about what feature each of our client supports. Check out the brand new page below. Then, since SignalR has dropped UseSignalR() everywhere and you now need to use UseEndpoints(...), all of our docs now accurately represent how to set this up.


After releasing the Microsoft.dotnet-openapi global tool, it is important to have documentation for it. That’s in the first article. A new article on customizing your error handling with ASP.NET Core Web API is definitely a must-read as well.

For the rest, you will find here updated samples, and general tidying of articles (typos, more snippets, clarifications).

Host and Deploy

Tons of updates on hosting with the new release of 3.0 in GA. With the release of Blazor Server-Side, this documentation also needed major updates. If you are using Blazor today, make sure to read this to avoid problems in the future. Health checks now get wrapped under UseEndpoints which required its documentation to be changed as well.


Updated package names and new snippets.

Razor Pages

The introduction has been completely rewritten with new code snippets for 3.0. Worth taking the time to refresh your knowledge on Razor Pages.


Updated for UseEndpoints() as well as including new API updates for 3.0. Updated documentation troubleshoot certification update.