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:

• .NET, which had ~474 commits, and 3,492 changed files on their docs repository and ~96 PRs on their API docs repository
• ASP.NET, which had ~282 commits, and 1,102 changed files on their docs repository
• NuGet, which had ~109 commits, and 45 changed files on their docs repository

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.

Legend

• 📢: 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

• C# 8.0 Updates
• C# 8.0 Spec updates
• ✨101 LINQ samples in your browser. Through the magic of try.net, Blazor, and Roslyn, you can explore LINQ using a dotnet global tool. See the try-samples home page for installation instructions and more samples.

.NET Core

• 💥 Prerequisites for .NET Core on Windows
• 💥 Breaking changes, version 3.0 Preview 9 to 3.0 - .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. ❗

• Blazor for ASP.NET Web Forms Developers

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. ❗

• Architecting Cloud Native .NET Applications for Azure

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. ❗

• ASP.NET Core gRPC for WCF Developers

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:

• .NET Core breaking changes
• Breaking changes, version 2.2 to 3.0 - .NET Core
• Breaking changes, version 3.0 Preview 6 to 3.0 Preview 7 - .NET Core
• Breaking changes, version 3.0 Preview 7 to 3.0 Preview 8 - .NET Core
• Breaking changes, version 3.0 Preview 8 to 3.0 Preview 9 - .NET Core
• Breaking changes, version 3.0 Preview 9 to 3.0 - .NET Core
• CoreFx breaking changes - .NET Core
• Cryptography breaking changes, version 2.2 to 3.0 - .NET Core
• Cryptography breaking changes - .NET Core
• Breaking changes, .NET Framework to .NET Core 3.0 - .NET Core
• Globalization breaking changes - .NET Core
• Visual Basic breaking changes - .NET Core
• Windows Forms breaking changes - .NET Core

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.

• What is Windows Presentation Foundation
• Differences between .NET Framework and .NET Core WPF
• Migrating WPF Apps to .NET Core 3.0
• XAML Overview
• Define XAML resources for WPF
• Styles and templates in WPF
• Create a style for a control in WPF
• Data binding overview

.NET Framework

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

• How to: Build a multifile assembly
• How to: Build a .NET Framework single-file assembly
• How to: Share an assembly with other applications
• How to: Get type and member information by using reflection

.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.

• Assemblies in .NET
• Assembly contents
• How to: Create a public-private key pair
• How to: Create signed friend assemblies
• How to: Create unsigned friend assemblies
• Delay-sign an assembly
• Walkthrough: Embed types from managed assemblies in Visual Studio
• How to: Find an assembly’s fully qualified name
• Friend assemblies
• How to: Determine if a file is an assembly
• How to: Load and unload assemblies
• How to: Reference a strong-named assembly
• How to: Sign an assembly with a strong name

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.

• Tutorial: Analyze sentiment of movie reviews using a pre-trained TensorFlow model
• Load data from files and other sources

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.

• How to serialize JSON - .NET
• JSON serialization in .NET
• DateTime and DateTimeOffset support in System.Text.Json

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 🤖📷.

• ✨ Troubleshoot .NET Core tool usage issues
• ✨ How to: create user-defined exceptions with localized exception messages

ASP.NET Core

• 📢 What’s new in ASP.NET Core 3.0
• 💥 Migrate from ASP.NET Core 2.2 to 3.0

Blazor

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.

• Create and use ASP.NET Core Razor components
• ASP.NET Core Blazor hosting models

Fundamentals

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).

• Detect changes with change tokens in ASP.NET Core
• Dependency injection in ASP.NET Core
• Background tasks with hosted services in ASP.NET Core
• Microsoft.AspNetCore.App metapackage for ASP.NET Core
• Middleware activation with a third-party container in ASP.NET Core
• Factory-based middleware activation in ASP.NET Core
• ASP.NET Core Middleware
• Routing in ASP.NET Core
• Kestrel web server implementation in ASP.NET Core

gRPC

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.

• Introduction to gRPC on .NET Core
• ✨ Call gRPC services with the .NET client
• ✨ gRPC client factory integration in .NET Core
• ✨ Logging and diagnostics in gRPC on .NET

MVC

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

• Test controller logic in ASP.NET Core
• ✨ Link Tag Helper in ASP.NET Core
• ✨ Script Tag Helper in ASP.NET Core

SignalR

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.

• ✨ SignalR client features
• Authentication and authorization in ASP.NET Core SignalR
• Host ASP.NET Core SignalR in background services
• ASP.NET Core SignalR configuration
• Security considerations in ASP.NET Core SignalR
• Use ASP.NET Core SignalR with TypeScript and Webpack

WebAPI

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).

• ✨ Develop ASP.NET Core apps using OpenAPI
• ✨ Handle errors in ASP.NET Core web APIs
• Controller action return types in ASP.NET Core web API
• Format response data in ASP.NET Core Web API
• Create web APIs with ASP.NET Core

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.

• ASP.NET Core Module
• 💥 Host and deploy ASP.NET Core Blazor
• Health checks in ASP.NET Core

Performance

Updated package names and new snippets.

• Distributed caching in ASP.NET Core

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.

• 💥 Introduction to Razor Pages in ASP.NET Core
• Reusable Razor UI in class libraries with ASP.NET Core

Security

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

• Use cookie authentication without ASP.NET Core Identity
• Enable Cross-Origin Requests (CORS) in ASP.NET Core
• Enforce HTTPS in ASP.NET Core

Tests

• Integration tests in ASP.NET Core

NuGet

• 📢 NuGet 5.3 Release Notes
• 💥 Deprecating packages on nuget.org

Reference

• .nuspec File Reference for NuGet
  • deprecating iconUrl, adding icon to replace it.
• NuGet pack and restore as MSBuild targets
  • adding instruction on how to pack an icon within your package