First, we will review the route to this point and why it is important to understand the past.

.NET Core 2.0 and later's support for a minimum of .NET Standard 2.0 is important because it provides many of the APIs that were missing from the first version of .NET Core. The 15 years' worth of libraries and applications that .NET Framework developers had available to them that are relevant for modern development have now been migrated to .NET and can run cross-platform on macOS and Linux variants, as well as on Windows.

.NET Standard 2.1 added about 3,000 new APIs. Some of those APIs need runtime changes that would break backward compatibility, so .NET Framework 4.8 only implements .NET Standard 2.0. .NET Core 3.0, Xamarin, Mono, and Unity implement .NET Standard 2.1.

.NET 6 removes the need for .NET Standard if all your projects can use .NET 6. Since you might still need to create class libraries for legacy .NET Framework projects or legacy Xamarin mobile apps, there is still a need to create .NET Standard 2.0 and 2.1 class libraries. In March 2021, I surveyed professional developers, and half still needed to create .NET Standard 2.0 compliant class libraries.

To summarize the progress that .NET has made over the past five years, I have compared the major .NET Core and modern .NET versions with the equivalent .NET Framework versions in the following list:

.NET Core 1.0

.NET Core 1.1

.NET Core 2.0

The third edition of this book was published in November 2017, so it covered up to .NET Core 2.0 and .NET Core for Universal Windows Platform (UWP) apps.

.NET Core 2.1

.NET Core 2.2

.NET Core 3.0

The fourth edition of this book was published in October 2019, so it covered some of the new APIs added in later versions up to .NET Core 3.0.

.NET Core 3.1

.NET 5.0

.NET 6.0

Improving performance from .NET Core 2.0 to .NET 5

dotnet sdk check

You will then see results, including the status of available updates, as shown in the following partial output:

.NET SDKs:
Version                         Status
-----------------------------------------------------------------------------
3.1.412                         Up to date.
5.0.202                         Patch 5.0.206 is available.
...

Understanding .NET components

Understanding assemblies, NuGet packages, and namespaces

In .NET, the IActionFilter interface of the System.Web.Mvc namespace is different from the IActionFilter interface of the System.Web.Http.Filters namespace.

Understanding dependent assemblies

Any assembly can reference one or more class library assemblies as dependencies, but you cannot have circular references. So, assembly B cannot reference assembly A if assembly A already references assembly B. The compiler will warn you if you attempt to add a dependency reference that would cause a circular reference. Circular references are often a warning sign of poor code design. If you are sure that you need a circular reference, then use an interface to solve it.

Understanding the Microsoft .NET project SDKs

When using .NET, you reference the dependency assemblies, NuGet packages, and platforms that your application needs in a project file.

Let's explore the relationship between assemblies and namespaces:

1. Use your preferred code editor to create a new solution/workspace named Chapter07.
2. Add a console app project, as defined in the following list:
   1. Project template: Console Application / console
   2. Workspace/solution file and folder: Chapter07
   3. Project file and folder: AssembliesAndNamespaces
3. Open AssembliesAndNamespaces.csproj and note that it is a typical project file for a .NET 6 application, as shown in the following markup:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <OutputType>Exe</OutputType>
       <TargetFramework>net6.0</TargetFramework>
       <Nullable>enable</Nullable>
       <ImplicitUsings>enable</ImplicitUsings>
     </PropertyGroup>
   </Project>
   

Understanding namespaces and types in assemblies

Understanding NuGet packages

• Packages can be easily distributed on public feeds.
• Packages can be reused.
• Packages can ship on their own schedule.
• Packages can be tested independently of other packages.
• Packages can support different OSes and CPUs by including multiple versions of the same assembly built for different OSes and CPUs.
• Packages can have dependencies specific to only one library.
• Apps are smaller because unreferenced packages aren't part of the distribution. The following table lists some of the more important packages and their important types:

Understanding frameworks

.NET packages each support a set of frameworks. For example, the System.IO.FileSystem package version 4.3.0 supports the following frameworks:

1. In the AssembliesAndNamespaces project, in Program.cs, enter the following code:

   XDocument doc = new();
   

2. Build the project and note the compiler error message, as shown in the following output:

   The type or namespace name 'XDocument' could not be found (are you missing a using directive or an assembly reference?)
   

   The XDocument type is not recognized because we have not told the compiler what the namespace of the type is. Although this project already has a reference to the assembly that contains the type, we also need to either prefix the type name with its namespace or import the namespace.

3. Click inside the XDocument class name. Your code editor displays a light bulb, showing that it recognizes the type and can automatically fix the problem for you.
4. Click the light bulb, and select using System.Xml.Linq; from the menu.

This will import the namespace by adding a using statement to the top of the file. Once a namespace is imported at the top of a code file, then all the types within the namespace are available for use in that code file by just typing their name without the type name needing to be fully qualified by prefixing it with its namespace.

Sometimes I like to add a comment with a type name after importing a namespace to remind me why I need to import that namespace, as shown in the following code:

using System.Xml.Linq; // XDocument

Relating C# keywords to .NET types

One of the common questions I get from new C# programmers is, "What is the difference between string with a lowercase s and String with an uppercase S?"

Let's see this in action with some code:

Mapping C# aliases to .NET types

Understanding native-sized integers

In a 64-bit process, the following code:

WriteLine($"int.MaxValue = {int.MaxValue:N0}");
WriteLine($"nint.MaxValue = {nint.MaxValue:N0}");

produces this output:

int.MaxValue = 2,147,483,647
nint.MaxValue = 9,223,372,036,854,775,807

Revealing the location of a type

1. Right-click inside XDocument and choose Go to Definition.
2. Navigate to the top of the code file and note the assembly filename is System.Xml.XDocument.dll, but the class is in the System.Xml.Linq namespace, as shown in Figure 7.1:

   

   Figure 7.1: Assembly and namespace that contains the XDocument type

3. Close the XDocument [from metadata] tab.
4. Right-click inside string or String and choose Go to Definition.
5. Navigate to the top of the code file and note the assembly filename is System.Runtime.dll but the class is in the System namespace.

What it does contain are type-forwarders. These are special types that appear to exist in an assembly but actually are implemented elsewhere. In this case, they are implemented deep inside the .NET runtime using highly optimized code.

Sharing code with legacy platforms using .NET Standard

Microsoft realized that this is unsustainable, so they created .NET Standard—a single API that all future .NET platforms would support. There are older versions of .NET Standard, but .NET Standard 2.0 was an attempt to unify all important recent .NET platforms. .NET Standard 2.1 was released in late 2019 but only .NET Core 3.0 and that year's version of Xamarin support its new features. For the rest of this book, I will use the term .NET Standard to mean .NET Standard 2.0.

.NET Standard is similar to HTML5 in that they are both standards that a platform should support. Just as Google's Chrome browser and Microsoft's Edge browser implement the HTML5 standard, .NET Core, .NET Framework, and Xamarin all implement .NET Standard. If you want to create a library of types that will work across variants of legacy .NET, you can do so most easily with .NET Standard.

Understanding defaults for class libraries with different SDKs

Of course, just because a class library targets a specific version of .NET by default does not mean you cannot change it after creating a class library project using the default template.

You can manually set the target framework to a value that supports the projects that need to reference that library, as shown in the following table:

Creating a .NET Standard 2.0 class library

1. Use your preferred code editor to add a new class library named SharedLibrary to the Chapter07 solution/workspace.
2. If you use Visual Studio 2022, when prompted for the Target Framework, select .NET Standard 2.0, and then set the startup project for the solution to the current selection.
3. If you use Visual Studio Code, include a switch to target .NET Standard 2.0, as shown in the following command:

   dotnet new classlib -f netstandard2.0
   

4. If you use Visual Studio Code, select SharedLibrary as the active OmniSharp project.

For example, one reader of the fourth edition wanted their experience to match the book steps that use the .NET Core 3.1 SDK. But they had installed the .NET 5.0 SDK as well and that was being used by default. As described in the previous section, the behavior when creating new class libraries changed to target .NET 5.0 instead of .NET Standard 2.0, and that confused the reader.

You can control the .NET SDK used by default by using a global.json file. The dotnet command searches the current folder and ancestor folders for a global.json file.

There are three ways to publish and deploy a .NET application. They are:

1. Framework-dependent deployment (FDD).
2. Framework-dependent executables (FDEs).
3. Self-contained.

Sometimes, you want to be able to give someone a USB stick containing your application and know that it can execute on their computer. You want to perform a self-contained deployment. While the size of the deployment files will be larger, you'll know that it will work.

Creating a console application to publish

Understanding dotnet commands

Creating new projects

1. On Windows, start Command Prompt or Windows Terminal. On macOS, start Terminal. If you are using Visual Studio Code, then you can use the integrated terminal.
2. Enter the dotnet new --list or dotnet new -l command to list your currently installed templates, as shown in Figure 7.2:

   

Figure 7.2: A list of installed dotnet new project templates

Getting information about .NET and its environment

dotnet --info

Note the results, as shown in the following partial output:

.NET SDK (reflecting any global.json):
 Version:   6.0.100
 Commit:    22d70b47bc
Runtime Environment:
 OS Name:     Windows
 OS Version:  10.0.19043
 OS Platform: Windows
 RID:         win10-x64
 Base Path:   C:\Program Files\dotnet\sdk\6.0.100\
Host (useful for support):
  Version: 6.0.0
  Commit:  91ba01788d
.NET SDKs installed:
  3.1.412 [C:\Program Files\dotnet\sdk]
  5.0.400 [C:\Program Files\dotnet\sdk]
  6.0.100 [C:\Program Files\dotnet\sdk]
.NET runtimes installed:
  Microsoft.AspNetCore.All 2.1.29 [...\dotnet\shared\Microsoft.AspNetCore.All]
...

Managing projects

Publishing a self-contained app

Now that you have seen some example dotnet tool commands, we can publish our cross-platform console app:

If you copy any of those publish folders to the appropriate operating system, the console application will run; this is because it is a self-contained deployable .NET application. For example, on macOS with Intel, as shown in the following output:

I can run everywhere!
OS Version is Unix 11.2.3
I am macOS.
Press ENTER to stop me.

Publishing a single-file app

If you can assume that .NET 6 is already installed on the computer on which you want to run your app, then you can use the extra flags when you publish your app for release to say that it does not need to be self-contained and that you want to publish it as a single file (if possible), as shown in the following command (that must be entered on a single line):

dotnet publish -r win10-x64 -c Release --self-contained=false
/p:PublishSingleFile=true

If you prefer the .pdb file to be embedded in the .exe file, then add a <DebugType> element to the <PropertyGroup> element in your .csproj file and set it to embedded, as shown highlighted in the following markup:

<PropertyGroup>
  <OutputType>Exe</OutputType>
  <TargetFramework>net6.0</TargetFramework>
  <Nullable>enable</Nullable>
  <ImplicitUsings>enable</ImplicitUsings>
  <RuntimeIdentifiers>
    win10-x64;osx-x64;osx.11.0-arm64;linux-x64;linux-arm64
  </RuntimeIdentifiers>
  <DebugType>embedded</DebugType>
</PropertyGroup>

If you cannot assume that .NET 6 is already installed on a computer, then although Linux also only generates the two files, expect the following additional files for Windows: coreclr.dll, clrjit.dll, clrcompression.dll, and mscordaccore.dll.

1. At the command line, enter the command to build the release version of the console application for Windows 10, as shown in the following command:

   dotnet publish -c Release -r win10-x64 /p:PublishSingleFile=true
   

2. Navigate to the DotNetEverywhere\bin\Release\net6.0\win10-x64\publish folder, select the DotNetEverywhere executable file, and note the executable is now 58.3 MB, and there is also a .pdb file that is 10 KB. The sizes on your system will vary.

Reducing the size of apps using app trimming

One of the problems with deploying a .NET app as a self-contained app is that the .NET libraries take up a lot of space. One of the biggest needs for reduced size is Blazor WebAssembly components because all the .NET libraries need to be downloaded to the browser.

With .NET 5, the trimming went further by removing individual types, and even members like methods from within an assembly if they are not used. For example, with a Hello World console app, the System.Console.dll assembly is trimmed from 61.5 KB to 31.5 KB. For .NET 5, this is an experimental feature so it is disabled by default.

The catch is how well the trimming identifies unused assemblies, types, and members. If your code is dynamic, perhaps using reflection, then it might not work correctly, so Microsoft also allows manual control.

Enabling assembly-level trimming

There are two ways to enable assembly-level trimming.

<PublishTrimmed>true</PublishTrimmed>

The second way is to add a flag when publishing, as shown highlighted in the following command:

dotnet publish ... -p:PublishTrimmed=True

Enabling type-level and member-level trimming

<PublishTrimmed>true</PublishTrimmed>
<TrimMode>Link</TrimMode>

The second way is to add two flags when publishing, as shown highlighted in the following command:

dotnet publish ... -p:PublishTrimmed=True -p:TrimMode=Link

For .NET 6, link trim mode is the default, so you only need to specify the switch if you want to set an alternative trim mode like copyused, which means assembly-level trimming.

Decompiling .NET assemblies

Decompiling using the ILSpy extension for Visual Studio 2022

Decompiling using the ILSpy extension for Visual Studio Code

No, you cannot technically prevent decompilation

All compiled applications contain instructions to the platform, operating system, and hardware on which it runs. Those instructions have to be functionally the same as the original source code but are just harder for a human to read. Those instructions must be readable to execute your code; they therefore must be readable to be decompiled. If you protect your code from decompilation using some custom technique, then you would also prevent your code from running!

Virtual machines simulate hardware and so can capture all interaction between your running application and the software and hardware that it thinks it is running on.

If you could protect your code, then you would also prevent attaching to it with a debugger and stepping through it. If the compiled application has a pdb file, then you can attach a debugger and step through the statements line-by-line. Even without the pdb file, you can still attach a debugger and get some idea of how the code works.

This is true for all programming languages. Not just .NET languages like C#, Visual Basic, and F#, but also C, C++, Delphi, assembly language: all can be attached to for debugging or to be disassembled or decompiled. Some tools used by professionals are shown in the following table:

Packaging your libraries for NuGet distribution

Referencing a NuGet package

1. In the AssembliesAndNamespaces project, add a reference to the Newtonsoft.Json NuGet package, either using the GUI for Visual Studio 2022 or the dotnet add package command for Visual Studio Code.
2. Open the AssembliesAndNamespaces.csproj file and note that a package reference has been added, as shown in the following markup:

   <ItemGroup>
     <PackageReference Include="newtonsoft.json" Version="13.0.1" />
   </ItemGroup>
   

If you have a more recent version of the newtonsoft.json package, then it has been updated since this chapter was written.

Fixing dependencies

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference
      Include="Microsoft.EntityFrameworkCore.Sqlite" 
      Version="6.0.0" />
  </ItemGroup>
</Project>

To fix dependencies, every package should have a single version with no additional qualifiers. Additional qualifiers include betas (beta1), release candidates (rc4), and wildcards (*).

This can be worth the risk while writing a book where new preview versions are released every month and you do not want to keep updating the package references, as I did during 2021, and as shown in the following markup:

<PackageReference
  Include="Microsoft.EntityFrameworkCore.Sqlite" 
  Version="6.0.0-preview.*" />

If you use the dotnet add package command, or Visual Studio's Manage NuGet Packages, then it will by default use the latest specific version of a package. But if you copy and paste configuration from a blog article or manually add a reference yourself, you might include wildcard qualifiers.

The following dependencies are examples of NuGet package references that are not fixed and therefore should be avoided unless you know the implications:

<PackageReference Include="System.Net.Http" Version="4.1.0-*" />
<PackageReference Include="Newtonsoft.Json" Version="12.0.3-beta1" />

Packaging a library for NuGet

Testing your class library package

Porting from .NET Framework to modern .NET

For example, you might have a complex website project that runs on .NET Framework 4.8 but is only visited by a small number of users. If it works and handles the visitor traffic on minimal hardware, then potentially spending months porting it to .NET 6 could be a waste of time. But if the website currently requires many expensive Windows servers, then the cost of porting could eventually pay off if you can migrate to fewer, less costly Linux servers.

Could you port?

• ASP.NET Core MVC websites.
• ASP.NET Core Web API web services (REST/HTTP).
• ASP.NET Core SignalR services.
• Console application command-line interfaces.

Modern .NET has decent support for the following types of applications on Windows, so they are potential candidates for porting:

• Windows Forms applications.
• Windows Presentation Foundation (WPF) applications.

Modern .NET has good support for the following types of applications on cross-platform desktop and mobile devices:

• Xamarin apps for mobile iOS and Android.
• .NET MAUI for desktop Windows and macOS, or mobile iOS and Android.

Modern .NET does not support the following types of legacy Microsoft projects:

• ASP.NET Web Forms websites. These might be best reimplemented using ASP.NET Core Razor Pages or Blazor.
• Windows Communication Foundation (WCF) services (but there is an open-source project named CoreWCF that you might be able to use depending on requirements). WCF services might be better reimplemented using ASP.NET Core gRPC services.
• Silverlight applications. These might be best reimplemented using .NET MAUI.

Silverlight and ASP.NET Web Forms applications will never be able to be ported to modern .NET, but existing Windows Forms and WPF applications could be ported to .NET on Windows in order to benefit from the new APIs and faster performance.

Legacy ASP.NET MVC web applications and ASP.NET Web API web services currently on .NET Framework could be ported to modern .NET and then be hosted on Windows, Linux, or macOS.

Should you port?

Differences between .NET Framework and modern .NET

Understanding the .NET Portability Analyzer

Currently, it supports the following .NET Framework project types and more will be added later:

• ASP.NET MVC
• Windows Forms
• WPF
• Console Application
• Class Library

dotnet tool install -g upgrade-assistant

You can read more about this tool and how to use it at the following link:

Even though this package was created before .NET 6 existed, and the compiler and runtime have no way of knowing if it will work and therefore show warnings, because it happens to only call .NET Standard-compatible APIs, it works.

Working with preview features

It is a challenge for Microsoft to deliver some new features that have cross-cutting effects across many parts of .NET like the runtime, language compilers, and API libraries. It is the classic chicken and egg problem. What do you do first?

Requiring preview features

Enabling preview features

Generic mathematics

Why has Microsoft added the ability to define static abstract methods? What are they useful for?

If you are interested, you can read more about this at the following link: