Part I, “The C# Language”

The first part of this book covers all the aspects of the C# programming language. You learn the syntax options and see how the C# syntax integrates with classes and interfaces from .NET. This part gives good grounding in the C# language. This section doesn't presume knowledge of any particular programming language, but it's assumed you are an experienced programmer. You start looking at C#'s basic syntax and data types before getting into advanced C# features.

• Chapter 1, “.NET Applications and Tools,” covers what you need to know to create .NET applications. You learn about the .NET CLI and create a Hello World application using C# 9 top-level statements.
• Chapter 2, “Core C#,” dives into core C# features and gives you details on top-level statements and information on declaration of variables and data types. The chapter covers target-typed new expressions, explains nullable reference types, and defines a program flow that includes the new switch expressions.
• Chapter 3, “Classes, Records, Structs, and Tuples,” gives you information to create reference or value types, create and use tuples, and make use of the C# 9 enhancement to create and use records.
• Chapter 4, “Object-Oriented Programming in C#,” goes into details of object-oriented techniques with C# and demonstrates all the C# keywords for object orientation. It also covers using inheritance with C# 9 records.
• Chapter 5, “Operators and Casts,” explains the C# operators, and you also learn how to overload standard operators for custom types.
• Chapter 6, “Arrays,” doesn't stop with simple arrays; you learn using multidimensional and jagged arrays, use the Span type to access arrays, and use the new index and range operators to access arrays.
• Chapter 7, “Delegates, Lambdas, and Events,” covers .NET pointers to methods, lambda expressions with closures, and .NET events.
• Chapter 8, “Collections,” dives into the different kind of collections, such as lists, queues, stacks, dictionaries, and immutable collections. The chapter also gives you the information you need to decide which collection to use in what scenario.
• Chapter 9, “Language Integrated Query,” gives you the C# language integrated query features to query data from your collections. You also learn how to use multiple CPU cores with a query and what's behind expression trees that are used when you use LINQ to access your database with Entity Framework Core.
• Chapter 10, “Errors and Exceptions,” covers how you should deal with errors, throw and catch exceptions, and filter exceptions when catching them.
• Chapter 11, “Tasks and Asynchronous Programming,” shows the C# keywords async and await in action— not only with the task-based async pattern but also with async streams, which is a new feature since C# 8.
• Chapter 12, “Reflection, Metadata, and Source Generators,” covers using and reading attributes with C#. The attributes will not just be read using reflection, but you'll also see the functionality of source generators that allow creating source code during compile time.
• Chapter 13, “Managed and Unmanaged Memory,” is the last chapter of Part I, which not only shows using the IDisposable interface with the using statement and the new using declaration but also demonstrates using the Span type with managed and unmanaged memory. You can read about using Platform Invoke both with Windows and with Linux environments.

Part II, “Libraries”

Part II starts with creating custom libraries and NuGet packages, but the major topics covered with Part II are for using .NET libraries that are important for all application types.

• Chapter 14, “Libraries, Assemblies, Packages, and NuGet,” explains the differences between assemblies and NuGet packages. In this chapter, you learn how to create NuGet packages and are introduced to a new C# feature, module initializers, which allow you to run initial code in a library.
• Chapter 15, “Dependency Injection and Configuration,” gives detail about how the Host class is used to configure a dependency injection container and the built-in options to retrieve configuration information from a .NET application with different configuration providers, including Azure App Configuration and user secrets.
• Chapter 16, “Diagnostics and Metrics,” continues using the Host class to configure logging options. You also learn about reading metric information that's offered from some NET providers, using Visual Studio App Center, and extending logging for distributed tracing with OpenTelemetry.
• Chapter 17, “Parallel Programming,” covers myriad features available with .NET for parallelization and synchronization. Chapter 11 shows the core functionality of the Task class. In Chapter 17, more of the Task class is shown, such as forming task hierarchies and using value tasks. The chapter goes into issues of parallel programming such as race conditions and deadlocks, and for synchronization, you learn about different features available with the lock keyword, the Monitor, SpinLock, Mutex, Semaphore classes, and more.
• Chapter 18, “Files and Streams,” not only covers reading and writing from the file system with new stream APIs that allow using the Span type but also covers the new .NET JSON serializer with classes in the System.Text.Json namespace.
• In Chapter 19, “Networking,” you learn about foundational classes for network programming, such as the Socket class and how to create applications using TCP and UDP. You also use the HttpClient factory pattern to create HttpClient objects with automatic retries if transient errors occur.
• Chapter 20, “Security,” gives you information about cryptography classes for encrypting data, explains how to use the new Microsoft.Identity platform for user authentication, and provides information on web security and what you need to be aware of with encoding issues as well as cross-site request forgery attacks.
• Chapter 21, “Entity Framework Core,” covers reading and writing data from a database—including the many features offered from EF Core, such as shadow properties, global query filters, many-to-many relations, and what metric information is now offered by EF Core—and reading and writing to Azure Cosmos DB with EF Core.
• In Chapter 22, “Localization,” you learn to localize applications using techniques that are important both for Windows and web applications.
• Chapter 23, “Tests,” covers creating unit tests, analyzing code coverage with the .NET CLI, using a mocking library when creating unit tests, and what features are offered by ASP.NET Core to create integration tests.

Part III, “Web Applications and Services”

Part III of this book is dedicated to ASP.NET Core technologies for creating web applications and services, no matter whether you run these applications and services in your on-premises environment or in the cloud making use of Azure App Services, Azure Static Web Apps, or Azure Functions.

• Chapter 24, “ASP.NET Core,” gives you the foundation of ASP.NET Core. Based on the dependency injection container you learned about in Part II, this chapter shows how ASP.NET Core makes use of middleware to add functionality to every HTTP request and define routes with ASP.NET Core endpoint routing.
• Chapter 25, “Services,” dives into creating microservices using different technologies such as ASP.NET Core as well as using Azure Functions and gRPC for binary communication.
• Chapter 26, “Razor Pages and MVC,” is about interacting with users with ASP.NET Core technologies. It covers Razor pages, Razor views, and functionality such as tag helpers and view components.
• Chapter 27, “Blazor,” is about the newest enhancement of ASP.NET Core with Razor components, which allows you to implement C# code running either on the server or in the client using WebAssembly. You learn about the differences between Blazor Server and Blazor WebAssembly, what the restrictions are with these technologies, and the built-in components available.
• Chapter 28, “SignalR,” covers the real-time functionality available with ASP.NET Core to send information to a group of clients and how you can use C# async streams with SignalR.

Part IV, “Apps”

Part IV of this book is dedicated to XAML code and creating Windows applications with the native UI platform for Windows 10: WinUI. Much of the information you get here can also be applied to WPF applications and to .NET MAUI and developing XAML-based applications for mobile platforms.

• Chapter 29, “Windows Apps,” gives you foundational information on XAML, including dependency properties and attached properties. You learn how to create custom markup extensions and about the control categories available with WinUI, including advanced techniques such as adaptive triggers and deferred loading.
• Chapter 30, “Patterns with XAML Apps,” gives you the information you need to use the MVVM pattern and how you can share as much code as possible between different XAML-based technologies such as WinUI, WPF, and .NET MAUI.
• Chapter 31, “Styling Windows Apps,” explains XAML shapes and geometry elements, dives into styles and control templates, gives you information on creating animations, and explains how you can use the Visual State Manager with your XAML-based applications.

.NET SDK

For developing .NET applications, you need to install the .NET SDK. The SDK contains the .NET command-line interface (CLI), tools, libraries, and the runtime. With the .NET CLI, you can create new applications based on templates, restore packages, build and test the application, and create deployment packages. Later in this chapter in the section “.NET CLI,” you will see how to create and build applications.

If you use Visual Studio 2019, the .NET SDK is installed as part of Visual Studio. If you don't have Visual Studio, you can install the SDK from https://dot.net. Here, you can find instructions on how to install the SDK on Windows, Mac, and Linux systems.

You can install multiple versions of the .NET SDK in parallel. The command

> dotnet --list-sdks

shows all the different SDK versions that are installed on the system. By default, the latest version is used.

You can create a global.json file if you do not want to use the latest version of the SDK. The command

> dotnet new globaljson

creates the file global.json in the current directory. This file contains the version element with the version number currently used. You can change the version number to one of the other SDK versions that is installed:

{
  "sdk": {
    "version": "5.0.202"
  }
}

In the directory of global.json and its subdirectories, the specified SDK version is used. You can verify this with

> dotnet --version

.NET Runtime

On the target system, the .NET SDK is not required. Here you just need to install the .NET runtime. The runtime includes all the core libraries and the dotnet driver.

The dotnet driver is used to run the application—for example, the Hello, World application with

> dotnet hello-world.dll 

At https://dot.net, you can find not only instructions to download and install the SDK on different platforms but also the runtime.

Instead of installing the runtime on the target system, you also can deliver the runtime as part of the application (which is known as self-contained deployment). This technique is very different from older .NET Framework applications and is covered later in the chapter in the “Using the .NET CLI” section.

To see which runtimes are installed, you can use

> dotnet --list-runtimes

Common Language Runtime

The C# compiler compiles C# code to Microsoft Intermediate Language (IL) code. This code is a little bit like assembly code, but it has more object-oriented features. The IL code is run by the Common Language Runtime (CLR). What's done by a CLR?

The IL code is compiled to native code by the CLR. The IL code available in .NET assemblies is compiled by a Just-In-Time (JIT) compiler. This compiler creates platform-specific native code. The runtime includes a JIT compiler named RyuJIT. This compiler is not only faster than the previous one, but it also has better support for using Edit & Continue while you're debugging the application with Visual Studio.

The runtime also includes a type system with a type loader that is responsible for loading types from assemblies. Security infrastructure with the type system verifies whether certain type system structures are permitted—for example, with inheritance.

After instances of types are created, they also need to be destroyed, and memory needs to be recycled. Another feature of the runtime is the garbage collector. The garbage collector cleans up memory from objects that are no longer referenced in the managed heap.

The runtime is also responsible for threading. When you are creating a managed thread from C#, it is not necessarily a thread from the underlying operating system. Threads are virtualized and managed by the runtime.

.NET Compiler Platform

The C# compiler that's installed as part of the SDK belongs to the .NET Compiler Platform, which is also known by the code name Roslyn. Roslyn allows you to interact with the compilation process, work with syntax trees, and access the semantic model that is defined by language rules. You can use Roslyn to write code analyzers and refactoring features. You also can use Roslyn with a new feature of C# 9, code generators, which are discussed in Chapter 12, “Reflection, Metadata, and Source Generators.”

.NET Framework

The .NET Framework is the name of the old .NET. The last version available is .NET Framework 4.8. It's not that useful to create new applications with this framework, but of course you can maintain existing applications because this technology will still be supported for many years to come. If existing applications don't get any advantages by moving to new technologies and there's not a lot of maintenance going on, there's no need to switch in the short term.

Depending on the technologies used with existing applications, the switch to .NET can be easy. WPF and Windows Forms have been offered with newer technologies since .NET Core 3. However, WPF and Windows applications could have used features where the application architecture might need a change.

Examples of technologies that are no longer offered with new versions of .NET are ASP.NET Web Forms, Windows Communication Foundation (WCF), and Windows Workflow Foundation (WF). Instead of ASP.NET Web Forms, you can rewrite applications using ASP.NET Blazor. Instead of WCF, you can use ASP.NET Core Web API or gRPC. Instead of WF, moving to Azure Logic Apps might be useful.

.NET Core

.NET Core is the new .NET that is used by all new technologies and is a main focus of this book (with the new name .NET). This framework is open source, and you can find it at http://www.github.com/dotnet. The runtime is the CoreCLR repository; the framework containing collection classes, file system access, console, XML, and a lot more is in the CoreFX repository.

Unlike the .NET Framework, where the specific version you needed for the application had to be installed on the system, with .NET Core 1.0, the framework, including the runtime, is delivered with the application. Previously, there were times when you might have had problems deploying an ASP.NET web application to a shared server because the provider had older versions of .NET installed; those times are gone. Now you can deliver the runtime with the application, and you are not dependent on the version installed on the server.

.NET Core is designed in a modular approach. The framework is split into a large list of NuGet packages. So that you don't have to deal with all the packages, metapackages reference the smaller packages that work together. This even improved with .NET Core 2.0 and ASP.NET Core 2.0. With ASP.NET Core 2.0, you just need to reference Microsoft.AspNetCore.All to get all the packages you typically need with ASP.NET Core web applications.

.NET Core can be updated at a fast pace. Even updating the runtime doesn't influence existing applications because the runtime can be installed with the applications. Now Microsoft can improve .NET Core, including the runtime, with faster release cycles.

.NET

Starting with .NET 5, .NET Core has a new name: .NET. Removing “Core” from the name should tell developers who still use the .NET Framework that there's not a new version of the .NET Framework from now on. The .NET Framework is no longer receiving new features. For new applications, you should use .NET.

.NET Standard

.NET Standard is an important specification when creating and using libraries. .NET Standard offers a contract rather than an implementation. With this contract, available APIs are listed. With every new version of .NET Standard, new APIs are added. APIs are never removed. For example, .NET Standard 2.1 lists more APIs than .NET Standard 1.6.

When you're creating a library, you probably want to use as many APIs as possible, so I suggest you choose the most recent .NET Standard version. However, the highest standard version also means the lowest number of platforms that support this standard, so you may need to take that into consideration.

A table at https://docs.microsoft.com/dotnet/standard/net-standard gives you the details on what platform supports which version of the standard. For example, .NET Framework 4.6.1 and later support up to .NET Standard 2.0. In addition, .NET Core 3.0 and later (which includes .NET 5 and later) support .NET Standard 2.1. The Universal Windows Platform build 10.0.16299 supports .NET Standard 2.0. Xamarin.Android 10.0 supports .NET Standard 2.1.

As of .NET 5, the .NET Standard becomes irrelevant. If you're creating libraries with .NET 5, you can use libraries from .NET 5, .NET 6, and later applications. Similarly, when you're creating libraries with .NET 7, you can use libraries from applications written with .NET 7 and later.

However, we can't expect that the .NET Framework, Mono, and other older technologies will just fade away, so .NET Standard will still be needed for many years to come. If you need to support older technologies with your libraries, you'll still need .NET Standard.

NuGet Packages

In the early days, assemblies were reusable units with applications. That use is still possible (and necessary with some assemblies) when you're adding a reference to an assembly for using the public types and methods from your own code. However, using libraries can mean a lot more than just adding a reference and using it. Using libraries can also mean making some configuration changes or using scripts to take advantage of some features. The target framework determines which binaries you can use. These are reasons to package assemblies within NuGet packages, which are zip files that contain the assembly (or multiple assemblies) as well as configuration information and PowerShell scripts.

Another reason for using NuGet packages is that they can be found easily; they're available not only from Microsoft but also from third parties. NuGet packages are easily accessible on the NuGet server at https://www.nuget.org.

You can add NuGet packages to applications with the .NET CLI:

> dotnet add package <package-name>

From the references within a Visual Studio project, you can open the NuGet Package Manager (see Figure 1-1). There you can search for packages and add them to the application. This tool enables you to search for packages that are not yet released (including prerelease options) and define the NuGet server that should be searched for packages. One place to search for packages can be your own shared directory where you've placed your internal packages that you've used.

Namespaces

The classes available with .NET are organized in namespaces. Most of these namespaces start with the name System or Microsoft. The following table describes a few of the namespaces to give you an idea about the hierarchy:

Data Access

Before taking a look at the application types themselves, let's look at technologies that are used by all application types for access to data.

Files and directories can be accessed by using simple API calls; however, the simple API calls are not flexible enough for some scenarios. With the Stream API, you have a lot of flexibility, and the streams offer many more features, such as encryption or compression. Readers and writers make using streams easier. All of the different options available here are covered in Chapter 18, “Files and Streams.”

To read and write to databases, you can use an abstraction layer, Entity Framework Core (Chapter 21, “Entity Framework Core”). Entity Framework Core offers a mapping of object hierarchies to the relations of a database. EF Core not only offers using different relational databases but also has support for NoSQL databases, such as Azure Cosmos DB.

Windows Apps

For creating Windows apps, you can use the new UI control WinUI 3.0 to create either Universal Windows Platform (UWP) or Windows desktop applications. UWP applications make use of a sandboxed environment where the application needs to request permissions from the user depending on the APIs used. The desktop application version can be compared to a WPF and Windows Forms application where nearly all .NET 5 APIs can be used. WPF and Windows Forms applications can also be updated to use new modern WinUI controls.

Creating WinUI applications with XAML code using the MVVM pattern is covered in Chapter 30, “Patterns with XAML Apps,” and the chapters that follow it.

Web Applications

For creating web applications with .NET, several options are available. A technology that implements the Model-View-Controller (MVC) pattern with the application structure is ASP.NET Core MVC. If you have an existing .NET Framework ASP.NET MVC application, the move to ASP.NET Core MVC shouldn't be too hard.

ASP.NET Core Razor Pages provide an easier option compared to the MVC pattern. Razor Pages can use code-behind or mix the C# code with the HTML page. This solution is easier to start with, and it also can be used with MVC. The dependency injection features of Razor Pages make it easy to create reusable code.

ASP.NET Core Blazor is a new technology that is used to get rid of JavaScript code. With a server-side variant, user interface events are handled on the server. The client and server are continuously connected using SignalR behind the scenes. Another variant of Blazor is using WebAssembly on the client. With this, you can use C#, HTML, and CSS to write code running binary in the client. Because WebAssembly is an HTML 5 standard, Blazor runs in all modern browsers without the need for an add-in.

The original introduction of ASP.NET fundamentally changed the web programming model. ASP.NET Core changed it again. ASP.NET Core allows the use of .NET Core for high performance and scalability, and it runs not only on Windows but also on Linux systems.

With ASP.NET Core, ASP.NET Web Forms is no longer covered. (ASP.NET Web Forms can still be used and is updated with .NET 4.7.)

ASP.NET Core MVC is based on the well-known MVC pattern for easier unit testing. It also allows a clear separation for writing user interface code with HTML, CSS, and JavaScript, and it uses C# on the back end.

Services

SOAP and WCF fulfilled their duties in the past. Modern apps make use of Representational State Transfer (REST) and the Web API. Using ASP.NET Core to create a Web API is an option that is a lot easier for communication and fulfills more than 90 percent of requirements by distributed applications. This technology is based on REST, which defines guidelines and best practices for stateless and scalable web services.

The client can receive JSON or XML data. JSON and XML can also be formatted in a way to make use of the Open Data (OData) specification.

The features of this new API make it easy to consume from web clients using JavaScript, .NET, and other technologies.

Creating a Web API is a good approach for creating microservices. The approach to build microservices defines smaller services that can run and be deployed independently and have their own control of a data store.

To describe the services, a new standard has been developed—the OpenAPI (https://www.openapis.org), which has its roots with Swagger (https://swagger.io/).

For remote procedure calls (RPC) like communication, you can use gRPC, which offers a binary communication based on HTTP/2 that can be used across different platforms.

SignalR

For real-time web functionality and bidirectional communication between the client and the server, SignalR is an ASP.NET Core technology. SignalR allows pushing information to connected clients as soon as information is available. SignalR makes use of the WebSocket technology to push information.

Microsoft Azure

Nowadays, you can't ignore the cloud when considering the development picture. Although this book doesn't include a dedicated chapter on cloud technologies, Microsoft Azure is referenced in several chapters in this book.

Microsoft Azure offers software as a service (SaaS), infrastructure as a service (IaaS), platform as a service (PaaS), and functions as a service (FaaS), and sometimes offerings are in between these categories. Let's take a look at some Microsoft Azure offerings.

.NET CLI

For development, you need the .NET SDK. If you're using Visual Studio for development, the .NET SDK is installed with Visual Studio. If you're using a different environment or you want to install different versions that are not part of the Visual Studio installation, you can get downloads for the SDK from https://dot.net. Here you can download and install distributions of the SDK for different platforms.

Part of the SDK is the .NET CLI—the command-line interface to develop .NET applications. You can use the .NET CLI to create new applications, compile applications, run unit tests, create NuGet packages, and create the files you need for publishing. Other than that, you can use any editor such as Notepad to write the code. Of course, if you have access to other tools that offer IntelliSense, using them makes it easier to run and debug your applications.

A tour of the .NET CLI is given later in this chapter in the section “Using the .NET CLI.”

Visual Studio Code

Visual Studio Code is a lightweight editor available not only on Windows but also on Linux and macOS. The community created a huge number of extensions that make Visual Studio Code the preferred environment for many technologies.

With many chapters of this book, you can use Visual Studio Code as your development editor. What you currently can't do is create WinUI and Xamarin applications. You can use Visual Studio Code for .NET Core console applications and ASP.NET Core web applications.

You can download Visual Studio Code from http://code.visualstudio.com.

Visual Studio Community

This edition of Visual Studio is a free edition with features that the Professional edition previously had, but there's a license restriction for when it can be used. It's free for open-source projects and training and to academic and small professional teams. Unlike the Express editions of Visual Studio that previously have been the free editions, this product allows using extensions with Visual Studio.

Visual Studio Professional

Visual Studio Professional includes more features than the Community edition, such as the CodeLens and Team Foundation Server for source code management and team collaboration. With this edition, you also get a subscription that includes several server products from Microsoft for development and testing, as well as a free amount that you can use with Microsoft Azure for development and testing.

Visual Studio Enterprise

Unlike the Professional edition, Visual Studio Enterprise contains a lot of tools for testing, such as Live Unit Testing, Microsoft Fakes (unit test isolation), and IntelliTest (unit testing is part of all Visual Studio editions). With Code Clone you can find similar code in your solution. Visual Studio Enterprise also contains architecture and modeling tools to analyze and validate the solution architecture.

Visual Studio for Mac

Visual Studio for Mac originated in the Xamarin Studio, but now it has a lot more than the earlier product. The actual version of Visual Studio for Mac is using the same source code for the editor that is available with the Windows version of Visual Studio. With Visual Studio for Mac, you can create not only Xamarin apps but also ASP.NET Core apps that run on Windows, Linux, and Mac. With many chapters of this book, you can use Visual Studio for Mac. Exceptions are the chapters that cover WinUI (Chapters 29 through 31), which require Windows to run and develop the app.

Windows Terminal

After so many years without changes to the Windows command prompt, now there's a completely new one. The source code is public at https://github.com/Microsoft/terminal, and it offers many features that are useful for development. This terminal offers multiple tabs and different shells, such as the Windows PowerShell, a command prompt, the Azure Cloud Shell, and WSL 2 environments. You can have the terminal full screen, open different tabs to keep different folders easily accessible, and also split panes to have different folders open in a single screen for easy comparison. New features are added on a monthly basis, and you can install the terminal from the Microsoft Store.

WSL 2

WSL 2 is the second generation of the Windows Subsystem for Linux. With this, the subsystem to run Linux is not only faster, but it also offers practically all Linux APIs.

Using WSL 2, you can install different Linux distributions from the Microsoft Store. If you use the Windows Terminal, different tabs can be opened for every Linux distribution installed.

WSL 2 gives you an easy way to build and run .NET applications on a Linux environment from your Windows system. You can even use Visual Studio to debug your .NET applications while they run in the Linux environment. You just need to install the extension .NET Core Debugging with WSL 2. When you run a debug session from Visual Studio, the .NET SDK gets automatically installed in your WSL 2 environment.

Docker Desktop

The Docker Desktop for Linux (which you can install from https://hub.docker.com/editions/community/docker-ce-desktop-windows) allows running Docker containers for Linux or Windows. Using Docker allows creating images that include your application code based on images containing the .NET runtime. The .NET runtime itself is based on Linux or Windows images.

You can use Docker to create a solution using many .NET services running in multiple Docker containers. Docker containers are running instances of Docker images that you can built with support from Visual Studio or dotnet tools such as tye (https://github.com/dotnet/tye).

Creating the Application

The dotnet tools offer an easy way to create a “Hello World!” application. Just enter this command to create a console application:

> dotnet new console --output HelloWorld

This command creates a new HelloWorld directory and adds the source code file Program.cs and the project file HelloWorld.csproj. The command dotnet new also includes the functionality of dotnet restore where all needed NuGet packages are downloaded. To see a list of dependencies and versions of libraries used by the application, you can check the file project.assets.json in the obj subdirectory. Without using the option --output (or -o as shorthand), the files would be generated in the current directory.

The generated source code looks like the following code snippet:

using System;
 
namespace HelloWorld
{
  class Program
  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello World!");
    }
  }
}

Let's get into the syntax of this program. The Main method is the entry point for a .NET application. The CLR invokes a static Main method on startup. The Main method needs to be put into a class. Here, the class is named Program, but you could call it by any name.

Console.WriteLine invokes the WriteLine method of the Console class. The Console class can be found in the System namespace. To avoid writing System.Console.WriteLine to invoke this method, the System namespace is opened with the using declaration on top of the source file.

After writing the source code, you need to compile the code to run it. How you can do this is explained soon in the section “Building the Application.”

The created project configuration file is named HelloWorld.csproj. This file contains the project configuration, such as the target framework, and the type of binary to create. An important piece of information in this file is the reference to the SDK (project file HelloWorld/HelloWorld.csproj):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>
</Project>

Top-Level Statements

C# 9 allows you to simplify the code for the “Hello World!” application. With top-level statements, the namespace, class, and Main method declarations can be removed to write only top-level statements. The application can look like the “Hello World!” application code shown here (code file HelloWorld/Program.cs):

using System;
 
Console.WriteLine("Hello World!");

If you prefix the invocation of the WriteLine method to add the namespace, you can write the program in a single code line:

System.Console.WriteLine("Hello World!");

Selecting the Framework and Language Versions

Instead of building a binary for just one framework version, you can replace the TargetFramework element with TargetFrameworks, and you can specify multiple frameworks as shown with .NET 5 and .NET Framework 4.8. The LangVersion element is added because the sample application uses the C# 9 code (top-level statements). Without using this attribute, the C# version is defined by the framework version. .NET 5 by default is using C# 9, and .NET Framework 4.8 is using C# 7.3 (project file HelloWorld/HelloWorld.csproj):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net5.0;net48</TargetFrameworks>
    <LangVersion>9.0</LangVersion>
  </PropertyGroup>
</Project>

The Sdk attribute specifies the SDK that is used by the project. Microsoft ships different SDKs: Microsoft.NET.Sdk for console applications, Microsoft.NET.Sdk.Web for ASP.NET Core web applications, and Microsoft.NET.Sdk.BlazorWebAssembly for web applications with Blazor and WebAssembly.

You don't need to add source files to the project. Files with the .cs extension in the same directory and subdirectories are automatically added for compilation. Resource files with the .resx extension are automatically added for embedding resources. You can change the default behavior and exclude/include files explicitly.

You also don't need to add the .NET Core package. When you specify the target framework net5.0, the metapackage Microsoft.NETCore.App that references many other packages is automatically included.

Building the Application

To build the application, you need to change the current directory to the directory of the application and start dotnet build. You can see output like the following, which is compiled for .NET 5.0 and .NET Framework 4.8:

> dotnet build
Microsoft (R) Build Engine version 16.8.0 for .NET Copyright (C) 
Microsoft Corporation. All rights reserved.
 
  Determining projects to restore…
  Restored C:\procsharp\Intro\HelloWorld\HelloWorld.csproj (in 308 ms).
  HelloWorld -> C:\procsharp\Intro\HelloWorld\bin\Debug\net48\HelloWorld.exe
  HelloWorld -> C:\procsharp\Intro\HelloWorld\bin\Debug\net5.0\HelloWorld.dll
 
Build succeeded.
    0 Warning(s)
    0 Error(s)
 
Time Elapsed 00:00:02.82

As a result of the compilation process, you find the assembly containing the IL code of the Program class within the bin/debug/[net5.0|net48] folders. If you compare the build of .NET Core with .NET 4.8, you will find a DLL containing the IL code with .NET Core and an EXE containing the IL code with .NET 4.8. The assembly generated for .NET Core has a dependency on the System.Console assembly, whereas the .NET 4.8 assembly includes the Console class in the mscorlib assembly.

To build release code, you need to specify the option --configuration Release (shorthand -c Release):

> dotnet build --configuration Release

Running the Application

To run the application, you can use the following dotnet command:

> dotnet run

If the project file targets multiple frameworks, you need to tell the dotnet run command which framework to use to run the app by adding the option --framework. This framework must be configured with the csproj file. With the sample application, you should get the following output of the application after the restore information:

> dotnet run ––framework net5.0
Hello World!

On a production system, you don't use dotnet run to run the application; instead, you just use dotnet with the name of the library:

> dotnet bin/debug/net5.0/HelloWorld.dll

The compiler also creates an executable, which does nothing more than load and start the library. You can start the executable as well. How executables are built for publishing is shown in the next steps.

Creating a Web Application

Similarly to creating a console application, you can also use the .NET CLI to create a web application. As you enter dotnet new, you can see a list of templates available.

The command

> dotnet new webapp -o WebApp

creates a new ASP.NET Core web application with Razor Pages.

The created project file now contains a reference to the Microsoft.NET.Sdk.Web SDK. This SDK contains tools and extensions for the project file that are needed to create web applications and services:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>
</Project>

Now using

> dotnet build
> dotnet run

starts the Kestrel server of ASP.NET Core to listen on port 5000 and 5001. You can open a browser to access the pages returned from this server, as shown in Figure 1-2.

If you start this for the first time, you're giving a security warning to trust the developer certificate. As you trust the certificate, the warnings will no longer occur.

To stop the application, just press Ctrl+C to send the cancel command.

Publishing the Application

With the dotnet tool, you also can create a NuGet package and publish the application for deployment. Let's first create a framework-dependent deployment of the application. This reduces the number of files you need for publishing.

Using the previously created console application, you just need the following command to create the files for publishing. The framework is selected by using -f, and the release configuration by using -c :

> dotnet publish -f net5.0 -c Release

You put the files needed for publishing into the bin/Release/net5.0/publish directory.

When you use these files for publishing on the target system, you need the runtime as well. You can find the runtime downloads and installation instructions at https://www.microsoft.com/net/download/.

Self-Contained Deployments

Instead of needing to have the runtime installed on the target system, the application can deliver the runtime with it. This is known as self-contained deployment.

Depending on the platform where the application should be installed, the runtime differs. Thus, with self-contained deployment, you need to specify the platforms supported by specifying RuntimeIdentifiers in the project file as shown in the following project file. Here, the runtime identifiers for Windows 10, macOS, and Ubuntu Linux are specified (project file SelfContainedHelloWorld/SelfContainedHelloWorld.csproj):

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
  </PropertyGroup>
  <PropertyGroup>
    <RuntimeIdentifiers>
      win10-x64;ubuntu-x64;osx.10.11-x64;
    </RuntimeIdentifiers>
  </PropertyGroup>
</Project>

Now you can create publish files for all the different platforms:

> dotnet publish -c Release -r win10-x64
> dotnet publish -c Release -r osx.10.11-x64
> dotnet publish -c Release -r ubuntu-x64

After running these commands, you can find the files needed for publishing in the Release/[win10-x64|osx.10.11-x64|ubuntu-x64]/publish directories. As .NET 5.0 runtime is now included, the size of the files needed for publishing has grown. In these directories, you can also find platform-specific executables that can be started directly without using the .NET CLI command.

Creating a Single Executable

Instead of publishing a large list of files, you can create a single executable. Adding the option -p:PublishSingleFile=true adds the complete runtime to one binary, which then can be used for deployment. With the following command, a single file is created to the output directory singlefile. This directory also contains a file with the pdb extension. This file can be deployed to get symbol information for analysis in case the application crashes.

> dotnet publish -r win10-x64 -p:PublishSingleFile=true --self-contained 
-o singlefile

ReadyToRun

To speed up the startup performance of the application, some parts of the application can be precompiled to native code. This way, the IL compiler can reduce its work when running the application. This option can be used with or without PublishSingleFile.

> dotnet publish -r win10-x64 -p:PublishReadyToRun=true --self-contained 
-o readytorun

Instead of passing this configuration with the command line, the <PublishReadyToRun> element can also be specified in the project file.

Trimming

Of course, a single executable for publishing that includes the complete runtime is large. However, there's a way around that. You can trim all the classes and methods that are not needed for the application to make the binary smaller.

You can specify trimming with the PublishTrimmed element in the project file. The TrimMode specifies how aggressively trimming should be performed. The value link (used in this example) is used to trim based on members and to remove members that are not used. When you set the value to copyused, complete assemblies are kept if any of their members are used by the application:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
    <RuntimeIdentifiers>
      win10-x64;ubuntu-x64;osx.10.11-x64;
    </RuntimeIdentifiers>
    <PublishTrimmed>true</PublishTrimmed>
    <TrimMode>link</TrimMode>
  </PropertyGroup>
</Project>

You use the following command and the previous project configuration to create a single file executable that is trimmed. At the time of this writing, the size of the binary for “Hello, World!” is reduced from 54MB to 2.8MB. That's quite impressive. As the feature is improved continuously, more savings can be expected in the future.

> dotnet publish -o publishtrimmed -p:PublishSingleFile=true --self-contained 
-r win10-x64

There is a risk with trimming. For example, if the application makes use of reflection, the trimmer is not aware that the reflected members are needed during runtime. To deal with such issues, you can specify what assemblies, types, and type members should not be trimmed. To configure such options, read the detailed documentation at https://docs.microsoft.com/dotnet/core/deploying/trimming-options.

Top-Level Statements

A new feature of C# 9 is top-level statements. You can create simple applications without defining a namespace, declaring a class, and defining a Main method. A one-line “Hello, World!” application can look like this:

System.Console.WriteLine("Hello World!");

Let's enhance this one-line application to open the namespace where the Console class is defined first. With the using directive to import the System namespace, you can use class Console without prefixing it with the namespace:

using System;
Console.WriteLine("Hello World!");

Because WriteLine is a static method of the Console class, it's even possible to open the Console class with the using static directive:

using static System.Console;
WriteLine("Hello World!");

Behind the scenes, with top-level statements, the compiler creates a class with a Main method and adds the top-level statements to the Main method:

using System;
 
class Program
{
  static void Main()
  {
    Console.WriteLine("Hello, World!");
  }
}

Variables

C# offers different ways to declare and initialize variables. A variable has a type and a value that can change over time. In the next code snippet, the variable s1 is of type string as defined with the type declaration at the left of the variable name, and it is initialized to a new string object where the string literal "Hello, World!" is passed to the constructor. Because the string type is commonly used, instead of creating a new string object, the string "Hello, World!" can be directly assigned to the variable (shown with the variable s2).

C# 3 invented the var keyword with type inference, which can be used to declare a variable as well. Here, the type is required on the right side, and the left side would infer the type from it. As the compiler creates a string object from the string literal "Hello, World", s3 is in the same way a type-safe strongly defined string like s1 and s2.

C# 9 provides another new syntax to declare and initialize a variable with the target-typed new expression. Instead of writing the expression new string("Hello, World!"), if the type is known at the left side, using just the expression new("Hello, World!") is sufficient; you don't have to specify the type on the right side (code file TopLevelStatements/Program.cs):

using System;
 
string s1 = new string("Hello, World!");
string s2 = "Hello, World!";
var s3 = "Hello, World!";
string s4 = new("Hello, World!");
 
Console.WriteLine(s1);
Console.WriteLine(s2);
Console.WriteLine(s3);
Console.WriteLine(s4);
//…

Command-Line Arguments

When you're passing values to the application when starting the program, the variable args is automatically declared with top-level statements. In the following code snippet, with the foreach statement, the variable args is accessed to iterate through all the command-line arguments and display the values on the console (code file CommandLineArgs/Program.cs):

using System;
 
foreach (var arg in args)
{
  Console.WriteLine(arg);
}

Using the .NET CLI to run the application, you can use dotnet run followed by -- and then pass the arguments to the program. The -- needs to be added so as not to confuse the arguments of the .NET CLI with the arguments of the application:

> dotnet run -- one two three

When you run this, you see the strings one two three on the console.

When you create a custom Main method, the method needs to be declared to receive a string array. You can choose a name for the variable, but the variable named args is commonly used, which is the reason this name was selected for the automatically generated variable with top-level statements:

using System;
 
class Program
{
  static void Main(string[] args)
  {
    foreach (var arg in args)
    {
      Console.WriteLine(arg);
    }
  }
}

Understanding Variable Scope

The scope of a variable is the region of code from which the variable can be accessed. In general, the scope is determined by the following rules:

• A field (also known as a member variable) of a class is in scope for as long as its containing class is in scope.
• A local variable is in scope until a closing brace indicates the end of the block statement or method in which it was declared.
• A local variable that is declared in a for, while, or similar statement is in scope in the body of that loop.

It's common in a large program to use the same variable name for different variables in different parts of the program. This is fine as long as the variables are scoped to completely different parts of the program so that there is no possibility for ambiguity. However, bear in mind that local variables with the same name can't be declared twice in the same scope. For example, you can't do this:

int x = 20;
// some more code
int x = 30;

Consider the following code sample (code file VariableScopeSample/Program.cs):

using System;
 
for (int i = 0; i < 10; i++)
{
  Console.WriteLine(i);
} // i goes out of scope here
 
// We can declare a variable named i again, because
// there's no other variable with that name in scope
for (int i = 9; i>= 0; i--)
{
  Console.WriteLine(i);
} // i goes out of scope here.

This code simply prints out the numbers from 0 to 9, and then from 9 to 0, using two for loops. The important thing to note is that you declare the variable i twice in this code, within the same method. You can do this because i is declared in two separate loops, so each i variable is local to its own loop.

Here's another example (code file VariableScopeSample2/Program.cs):

int j = 20;
for (int i = 0; i < 10; i++)
{
  int j = 30; // Can't do this — j is still in scope
  Console.WriteLine(j + i);
}

If you try to compile this, you get an error like the following:

error CS0136: A local or parameter named 'j' cannot be declared in this scope because that name is used in an enclosing local scope to define a local or parameter

This occurs because the variable j, which is defined before the start of the for loop, is still in scope within the for loop and won't go out of scope until the Main method (which is created from the compiler) has finished executing. The compiler has no way to distinguish between these two variables, so it won't allow the second one to be declared.

It even doesn't help to put the variable j declared outside of the for loop after the end of the for loop. The compiler moves all variable declarations at the beginning of a scope no matter where you declare it.

Constants

For values that never change, you can define a constant. For constant values, you can use the const keyword.

With variables declared with the const keyword, the compiler replaces the variable in every occurrence with the value specified with the constant.

A constant is specified with the const keyword before the type:

const int a = 100; // This value cannot be changed.

The compiler replaces every occurrence of the local field with the value. This behavior is important in terms of versioning. If you declare a constant with a library and use the constant from an application, the application needs to be recompiled to get the new value; otherwise, the library could have a different value from the application. Because of this, it's best to use const only with values that never change, even in future versions.

Constants have the following characteristics:

• They must be initialized when they are declared. After a value has been assigned, it can never be overwritten.
• The value of a constant must be computable at compile time. You can't initialize a constant with a value taken from a variable. If you need to do this, you must use a read-only field.
• Constants are always implicitly static. Notice that you don't have to (and, in fact, are not permitted to) include the static modifier in the constant declaration.

The following are the advantages of using constants in your programs:

• Constants make your programs easier to read by replacing magic numbers and strings with readable names whose values are easy to understand.
• Constants help prevent mistakes in your programs. If you attempt to assign another value to a constant somewhere in your program other than at the point where the constant is declared, the compiler flags the error.

Methods and Types with Top-Level Statements

You can also add methods and types to the same file with top-level statements. In the following code snippet, the method named Method is defined and invoked after the method declaration and implementation (code file TopLevelStatements/Program.cs):

//…
void Method()
{
    Console.WriteLine("this is a method");
}
 
Method();
//…

The method can be declared before or after it is used. Types can be added to the same file, but these need to be specified following the top-level statements. With the following code snippet, the class Book is specified to contain a Title property and the ToString method. Before the declaration of the type, a new instance is created and assigned to the variable b1, the value of the Title property is set, and the instance is written to the console. When the object is passed as an argument to the WriteLine method, in turn the ToString method of Book class is invoked:

Book b1 = new();
b1.Title = "Professional C#";
Console.WriteLine(b1);
 
 
class Book
{
  public string Title { get; set; }
  public override string ToString() => Title;
}

Nullable Value Types

With a value type such as int, you cannot assign null to it. This can lead to difficulties when mapping to databases or other data sources, such as XML or JSON. Using a reference type instead results in additional overhead: an object is stored in the heap, and the garbage collection needs to clean it up when it's not used anymore. Instead, the ? can be used with the type definition, which allows assigning null :

int? x1 = null;

The compiler changes this to use the Nullable<T> type:

Nullable<int> x1 = null;

Nullable<T> doesn't add the overhead of a reference type. This is still a struct (a value type) but adds a Boolean flag to specify if the value is null.

The following code snippet demonstrates using nullable value types and assigning non-nullable values. The variable n1 is a nullable int that has been assigned the value null. A nullable value type defines the property HasValue, which can be used to check whether the variable has a value assigned. With the Value property, you can access its value. This can be used to assign the value to a non-nullable value type. A non-nullable value can always be assigned to a nullable value type; this always succeeds (code file NullableValueTypes/Program.cs):

int? n1 = null;
if (n1.HasValue)
{
  int n2 = n1.Value;
}
int n3 = 42;
int? n4 = n3;

Nullable Reference Types

Nullable reference types have the goal of reducing exceptions of type NullReferenceException, which is the most common exception that occurs with .NET applications. There always has been a guideline that an application should not throw such exceptions and should always check for null, but without the help of the compiler, such issues can be missed too easily.

To get help from the compiler, you need to turn on nullable reference types. Because this feature has breaking changes with existing code, you need to turn it on explicitly. You specify the Nullable element and set the enable value in the project file (project file NullableReferenceTypes.csproj):

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

Now, null cannot be assigned to reference types. When you write this code with nullable enabled,

string s1 = null; // compiler warning

you get the compiler warning “CS8600: Converting a null literal or a possible null value to non-nullable type.”

To assign null to the string, the type needs to be declared with a question mark—like nullable value types:

string? s1 = null;

When you're using the nullable s1 variable, you need to make sure to verify for not null before invoking methods or assigning it to non-nullable strings; otherwise, compiler warnings are generated:

string s2 = s1.ToUpper(); // compiler warning

Instead, you can check for null before invoking the method with the null-conditional operator ?., which invokes the method only if the object is not null. The result cannot be written to a non-nullable string. The result of the right expression can be null if s1 is null :

string? s2 = s1?.ToUpper();

You can use the coalescing operator ?? to define a different return value in the case of null. With the following code snippet, an empty string is returned in case the expression to the left of ?? returns null. The complete result of the right expression is now written to the variable s3, which can never be null. It's either the uppercase version of the s1 string if s1 is not null, or an empty string if s1 is null :

string s3 = s1?.ToUpper() ?? string.Empty;

Instead of using these operators, you can also use the if statement to verify whether a variable is not null. With the if statement in the following code snippet, the C# pattern is not is used to verify that s1 is not null. The block covered by the if statement is invoked only when s1 is not null. Here it is not necessary to use the null-conditional operator to invoke the method ToUpper :

if (s1 is not null)
{
  string s4 = s1.ToUpper();
}

Of course, it's also possible to use the not equals operator != :

if (s1 != null)
{
  string s5 = s1.ToUpper();
}

Using nullable reference types is also important with members of types, as shown in the Book class with the Title and Publisher properties in the following code snippet. The Title is declared with a non-nullable string type; thus, it needs to be initialized when creating a new object of the Book class. It's initialized with the constructor of the Book class. The Publisher property is allowed to be null, so it doesn't need initialization (code file NullableReferenceTypes/Program.cs):

class Book
{
  public Book(string title) => Title = title;
    
  public string Title { get; set; }
  public string? Publisher { get; set; }
}

When you're declaring a variable of the Book class, the variable can be declared as nullable (b1), or it needs a Book object with the declaration using the constructor (b2). The Title property can be assigned to a non-nullable string type. With the Publisher property, you can assign it to a nullable string or use the operators as shown earlier:

Book? b1 = null;
Book b2 = new Book("Professional C#");
string title = b2.Title;
string? publisher = b2.Publisher;

Behind the scenes with nullable value types, the type Nullable<T> is used behind the scenes. This is not the case with nullable reference types. Instead, the compiler adds annotation to the types. Nullable reference types have Nullable attributes associated. With this, nullable reference types can be used with libraries to annotate parameters and members with nullability. When the library is used with new applications, IntelliSense can give information regarding whether a method or property can be null, and the compiler acts accordingly with compiler warnings. Using an older version of the compiler (earlier than C# 8), the library can still be used in the same way nonannotated libraries are used. The compiler just ignores the attributes it doesn't know.

Integer Types

C# supports integer types with various numbers of bits used and differs between types that support only positive values or types with a range of negative and positive values. Eight bits are used by the byte and sbyte types. The byte type allows values from 0 to 255—only positive values—whereas the s in sbyte means to use a sign; that type supports values from –128 to 127, which is what's possible with 8 bits.

The short and ushort types make use of 16 bits. The short type covers the range from –32,768 to 32,767. With the ushort type, the u is for unsigned, and it covers 0 to 65,535. Similarly, the int type is a signed 32-bit integer, and the uint type is an unsigned 32-bit integer. long and ulong have 64 bits available. Behind the scenes, the C# keywords sbyte, short, int, and long map to System.SByte, System.Int16, System.Int32, and System.Int64. The unsigned versions map to System.Byte, System.UInt16, System.UInt32, and System.UInt64. The underlying .NET types clearly list the number of bits used in the name of the type.

To check for the maximum and minimum values from the type, you can use the MaxValue and MinValue properties.

Big Integer

In case you need a number representation that has a bigger value than the 64 bits available in the long type, you can use the BigInteger type. This struct doesn't have a limit on the number of bits and can grow until there's not enough memory available. There's not a specific C# keyword for this type, and you need to use BigInteger. Because this type can grow endlessly, MinValue and MaxValue properties are not available. This type offers built-in methods for calculation such as Add, Subtract, Divide, Multiply, Log, Log10, Pow, and others.

Native Integer Types

With int, short, and long, the number of bits and available sizes are independent if the application is a 32- or 64-bit application. This is different from the integer definitions as defined with C++. C# 9 has new keywords for platform-specific values: nint and nuint (native integer and native unsigned integer, respectively). In a 64-bit application, these integer types make use of 64 bits, whereas in a 32-bit application just 32 bits are used. These types are important with direct memory access, which is covered in Chapter 13, “Managed and Unmanaged Memory.”

Digit Separators

For better readability of numbers, you can use digit separators. You can add underscores to numbers, as shown in the following code snippet. In this code snippet, also the 0x prefix is used to specify hexadecimal values (code file DataTypes/Program.cs):

long l1 = 0x_123_4567_89ab_cedf;

The underscores used as separators are just ignored by the compiler. These separators help with readability and don't add any functionality. With the preceding sample, reading from the right, every 16 bits (or 4 hexadecimal characters) a digit separator is added. This is a lot more readable compared to this:

long l2 = 0x123456789abcedf;

Of course, because the compiler ignores the underscores, you are responsible for readability yourself. You can put the underscores at any position, which may not really help with readability:

long l3 = 0x_12345_6789_abc_ed_f;

It's useful that any position can be used, which allows for different use cases such as to work with hexadecimal or octal values or to separate different bits needed for a protocol, as shown in the next section.

Binary Values

Besides offering digit separators, C# also makes it easy to assign binary values to integer types. Using the 0b literal, it's only allowed to assign values of 0 and 1, such as the following (code file DataTypes/Program.cs):

uint binary1 = 0b_1111_1110_1101_1100_1011_1010_1001_1000; 

The preceding code snippet uses an unsigned int with 32 bits available. Digit separators help with readability for using binary values. This snippet makes a separation every 4 bits. Remember, you can write this in the hex notation as well:

uint hex1 = 0xfedcba98; 

Using the separator every 3 bits helps in working with the octal notation, where characters are used between 0 (000 binary) and 7 (111 binary).

uint binary2 = 0b_111_110_101_100_011_010_001_000;

If you need to define a binary protocol—for example, where 2 bits define the rightmost part followed by 6 bits in the next section, and two times 4 bits to complete 16 bits—you can put separators per this protocol:

ushort binary3 = 0b1111_0000_101010_11;

Floating-Point Types

C# also specifies floating-point types with different numbers of bits based on the IEEE 754 standard. The Half type (new as of .NET 5) uses 16 bits, float (Single with .NET) uses 32 bits, and double (Double) uses 64 bits. With all of these data types, 1 bit is used for the sign. Depending on the type, 10 through 52 bits are used for the significand, and 5 through 11 bits for the exponent. The following table shows the details:

When you assign a value, if you hard-code a noninteger number (such as 12.3), the compiler assumes that's a double. To specify that the value is a float, append the character F (or f):

float f = 12.3F;

With the decimal type (.NET struct Decimal), .NET has a high-precision floating-point type that uses 128 bits and can be used for financial calculations. With the 128 bits, 1 is used for the sign, and 96 for the integer number. The remaining bits specify a scaling factor. To specify that your number is a decimal type rather than a double, a float, or an integer, you can append the M (or m) character to the value:

decimal d = 12.30M;

The Boolean Type

You use the C# bool type to contain Boolean values of either true or false.

You cannot implicitly convert bool values to and from integer values. If a variable (or a function return type) is declared as a bool, you can only use values of true and false. You get an error if you try to use zero for false and a nonzero value for true.

The Character Type

The .NET string consists of two-byte characters. The C# keyword char maps to the .NET type Char. Using single quotation marks, for example, 'A', creates a char. With double quotation marks, a string is created.

As well as representing chars as character literals, you can represent them with four-digit hex Unicode values (for example, '\u0041'), as integer values with a cast (for example, (char)65), or as hexadecimal values (for example, '\x0041'). You can also represent them with an escape sequence, as shown in the following table:

Literals for Numbers

In the preceding sections, literals have been shown for numeric values. Let's summarize them here in the following table:

The object Type

Besides value types, with C# keywords, two reference types are defined: the object keyword that maps to the Object class and the string keyword that maps to the String class. The string type is discussed later in this chapter in the section “Working with Strings.” The Object class is the ultimate base class of all reference types and can be used for two purposes:

• You can use an object reference to bind to an object of any particular subtype. For example, in Chapter 5, you’ll see how you can use the object type to box a value object on the stack to move it to the heap; object references are also useful in reflection, when code must manipulate objects whose specific types are unknown.
• The object type implements a number of basic, general-purpose methods, which include Equals, GetHashCode, GetType, and ToString. User-defined classes might need to provide replacement implementations of some of these methods using an object-oriented technique known as overriding, which is discussed in Chapter 4. When you override ToString, for example, you equip your class with a method for intelligently providing a string representation of itself. If you don't provide your own implementations for these methods in your classes, the compiler picks up the implementations of the object type, which returns the name of the class.

The if Statement

With the if statement, you can specify an expression within parentheses. If the expression returns true, the block that's specified with curly braces is invoked. In case the condition is not true, you can check for another condition to be true using else if. The else if can be repeated to check for more conditions. If neither the expressions specified with the if nor all the else if expressions evaluate to true, the block specified with the else block is invoked.

With the following code snippet, a string is read from the console. If an empty string is entered, the code block following the if statement is invoked. The string method IsNullOrEmpty returns true if the string is either null or empty. The block specified with the else if statement is invoked when the length of the input is smaller than five characters. In all other cases—for example, with an input length of five or more characters—the else block is invoked (code file ProgramFlow/Program.cs):

Console.WriteLine("Type in a string");
string? input = Console.ReadLine();
 
if (string.IsNullOrEmpty(input))
{
  Console.WriteLine("You typed in an empty string.");
}
else if (input?.Length < 5)
{
  Console.WriteLine("The string had less than 5 characters.");
}
else
{
  Console.WriteLine("Read any other string");
}
Console.WriteLine("The string was " + input);

With the if statement, else if and else are optional. If you just need to invoke a code block based on a condition and don't invoke a code block if this condition is not met, you can use the if without else.

Pattern Matching with the is Operator

One of the C# features is pattern matching, which you can use with the if statement and the is operator. The earlier section “Nullable Reference Types” included an example that used an if statement and the pattern is not null.

The following code snippet compares the argument received that is of type object with null, using a const pattern to compare the argument with null and throw the ArgumentNullException. With the expression used in else if, the type pattern is used to check whether the variable o is of type Book. If this is the case, the variable o is assigned to the variable b. Because variable b is of type Book, with b the Title property that is specified by the Book type can be accessed (code file ProgramFlow/Program.cs):

void PatternMatching(object o)
{
  if (o is null) throw new ArgumentNullException(nameof(o));
  else if (o is Book b)
  {
    Console.WriteLine($"received a book: {b.Title}");
  }
}

A few more samples for const and type patterns are shown in the following code snippet:

if (o is 42) // const pattern
if (o is "42") // const pattern
if (o is int i) // type pattern

The switch Statement

The switch / case statement is good for selecting one branch of execution from a set of mutually exclusive ones. It takes the form of a switch argument followed by a series of case clauses. When the expression in the switch argument evaluates to one of the values specified by a case clause, the code immediately following the case clause executes. This is one example for which you don't need to use curly braces to join statements into blocks; instead, you mark the end of the code for each case using the break statement. You can also include a default case in the switch statement, which executes if the expression doesn't evaluate to any of the other cases. The following switch statement tests the value of the x variable (code file SwitchStatement/Program.cs):

void SwitchSample(int x)
{
  switch (x)
  {
    case 1:
      Console.WriteLine("integerA = 1");
      break;
    case 2:
      Console.WriteLine("integerA = 2");
      break;
    case 3:
      Console.WriteLine("integerA = 3");
      break;
    default:
      Console.WriteLine("integerA is not 1, 2, or 3");
      break;
  }
}

Note that the case values must be constant expressions; variables are not permitted.

With the switch statement, you cannot remove the break from the different cases. Contrary to the C++ and Java programming languages, with C# automatic fall-through from one case implementation to continue with another case is not done. Instead of an automatic fall-through, you can use the goto keyword for an explicit fall-through and select another case. Here's an example:

goto case 3;

If the implementation is completely the same with multiple cases, you can specify multiple cases before specifying an implementation:

switch(country)
{
  case "au":
  case "uk":
  case "us":
    language = "English";
    break;
  case "at":
  case "de":
    language = "German";
    break;
}

Pattern Matching with the switch Statement

Pattern matching can also be used with the switch statement. The following code snippet shows different case options with const and type, and relational patterns. The method SwitchWithPatternMatching receives a parameter of type object. case null is a const pattern that compares o for null. The next three cases specify a type pattern. case int i uses a type pattern that creates the variable i if o is an int, but only in combination with the when clause. The when clause uses a relational pattern to check if it is larger than 42. The next case matches every remaining int type. Here, no variable is specified where object o should be assigned. Specifying a variable is not necessary if you don't need this variable and just need to know it's of this type. With the match for a Book type, the variable b is used. Declaring a variable here, this variable is of type Book (code file SwitchStatement/Program.cs):

void SwitchWithPatternMatching(object o)
{
  switch (o)
  {
    case null:
      Console.WriteLine("const pattern with null");
      break;
    case int i when i> 42
      Console.WriteLine("type pattern with when and a relational pattern");   
    case int:
      Console.WriteLine("type pattern with an int");
      break;
    case Book b:
      Console.WriteLine($"type pattern with a Book {b.Title}");
      break;
    default:
      break;
  }
}

The switch Expression

The next example shows a switch based on an enum type. The enum type is based on an integer but gives names to the different values. The type TrafficLight defines the different values for the colors of a traffic light (code file SwitchExpression/Program.cs):

enum TrafficLight
{
  Red,
  Amber,
  Green
}

With the switch statement so far, you've only seen invoking some actions in every case. When you use the return statement to return from a method, you can also directly return a value from the case without continuing with the following cases. The method NextLightClassic receives a TrafficLight with its parameter and returns a TrafficLight. If the passed traffic light has the value TrafficLight.Green, the method returns TrafficLight.Amber. When the current light value is TrafficLight.Amber, TrafficLight.Red is returned:

TrafficLight NextLightClassic(TrafficLight light) 
{
  switch (light)
  {
    case TrafficLight.Green:
      return TrafficLight.Amber;
    case TrafficLight.Amber:
      return TrafficLight.Red;
    case TrafficLight.Red:
      return TrafficLight.Green;
    default:
       throw new InvalidOperationException();            
  }
}

In such a scenario, if you need to return a value based on different options, you can use the switch expression that is new as of C# 8. The method NextLight receives and returns a TrafficLight value similar to the previously shown method. The implementation is now done with an expression bodied member because the implementation is done in a single statement. Curly braces and the return statement are unnecessary in this case. When you use a switch expression instead of the switch statement, the variable and switch keyword are reversed. With the switch statement, the value on the switch follows in braces after the switch keyword. With the switch expression, the variable is followed by the switch keyword. A block with curly braces defines the different cases. Instead of using the case keyword, the => token is used to define what's returned. The functionality is the same as before, but you need fewer lines of code:

TrafficLight NextLight(TrafficLight light) =>
  light switch
  {
    TrafficLight.Green => TrafficLight.Amber,
    TrafficLight.Amber => TrafficLight.Red,
    TrafficLight.Red => TrafficLight.Green,
    _ => throw new InvalidOperationException()
  };

If the enum type TrafficLight is imported with the using static directive, you can simplify the implementation even more by just using the enum value definitions without the type name:

using static TrafficLight;
 
TrafficLight NextLight(TrafficLight light) =>
  light switch
  {
    Green => Amber,
    Amber => Red,
    Red => Green,
    _ => throw new InvalidOperationException()
  };

With the next example, a pattern combinator is used to combine multiple patterns. First, input is retrieved from the console. If string one or two is entered, the same match applies, using the or combinator pattern (code file SwitchExpression/Program.cs):

string? input = Console.ReadLine();
 
string result = input switch
{
  "one" => "the input has the value one",
  "two" or "three" => "the input has the value two or three",
  _ => "any other value"
};

With pattern combinators, you can combine patterns using the and, or, and not keywords.

The for Loop

C# provides four different loops (for, while, do - while, and foreach) that enable you to execute a block of code repeatedly until a certain condition is met. With the for keyword, you iterate through a loop whereby you test whether a particular condition holds true before you perform another iteration:

for (int i = 0; i < 100; i++)
{
  Console.WriteLine(i);
}

The first expression of the for statement is the initializer. It is evaluated before the first loop is executed. Usually you use this to initialize a local variable as a loop counter.

The second expression is the condition. This is checked before every iteration of the for block. If this expression evaluates to true, the block is executed. If it evaluates to false, the for statement ends, and the program continues with the next statement after the closing curly brace of the for body.

After the body is executed, the third expression, the iterator, is evaluated. Usually, you increment the loop counter. With i++, a value of 1 is added to the variable i. After the third expression, the condition expression is evaluated again to check whether another iteration with the for block should be done.

The for loop is a so-called pretest loop because the loop condition is evaluated before the loop statements are executed; therefore, the contents of the loop won't be executed at all if the loop condition is false.

It's not unusual to nest for loops so that an inner loop executes once completely for each iteration of an outer loop. This approach is typically employed to loop through every element in a rectangular multidimensional array. The outermost loop loops through every row, and the inner loop loops through every column in a particular row. The following code displays rows of numbers. It also uses another Console method, Console.Write, which does the same thing as Console.WriteLine but doesn't send a carriage return to the output (code file ForLoop/Program.cs):

// This loop iterates through rows
for (int i = 0; i < 100; i += 10)
{
  // This loop iterates through columns
  for (int j = i; j < i + 10; j++)
  {
    Console.Write($" {j}");
  }
  Console.WriteLine();
}

This sample results in this output:

0 1 2 3 4 5 6 7 8 9
10 11 12 13 14 15 16 17 18 19
20 21 22 23 24 25 26 27 28 29
30 31 32 33 34 35 36 37 38 39
40 41 42 43 44 45 46 47 48 49
50 51 52 53 54 55 56 57 58 59
60 61 62 63 64 65 66 67 68 69
70 71 72 73 74 75 76 77 78 79
80 81 82 83 84 85 86 87 88 89
90 91 92 93 94 95 96 97 98 99

The while Loop

Like the for loop, while is a pretest loop. The syntax is similar, but while loops take only one expression:

while(condition)
  statement(s);

Unlike the for loop, the while loop is most often used to repeat a statement or a block of statements for a number of times that is not known before the loop begins. Usually, a statement inside the while loop's body sets a Boolean flag to false on a certain iteration, triggering the end of the loop, as in the following example:

bool condition = false;
while (!condition)
{
  // This loop spins until the condition is true.
  DoSomeWork();
  condition = CheckCondition(); // assume CheckCondition() returns a bool
}

The do-while Loop

The do - while loop is the post-test version of the while loop. This means that the loop's test condition is evaluated after the body of the loop has been executed. Consequently, do - while loops are useful for situations in which a block of statements must be executed at least one time, as in this example:

bool condition;
do
{
  // This loop will at least execute once, even if the condition is false.
  MustBeCalledAtLeastOnce();
  condition = CheckCondition();
} while (condition);

The foreach Loop

The foreach loop enables you to iterate through each item in a collection. For now, don't worry about exactly what a collection is (it is explained fully in Chapter 6, “Arrays”); just understand that it is an object that represents a list of objects. Technically, for an object to count as a collection, it must support an interface called IEnumerable. Examples of collections include C# arrays, the collection classes in the System.Collections namespaces, and user-defined collection classes. You can get an idea of the syntax of foreach from the following code, if you assume that arrayOfInts is (unsurprisingly) an array of int s:

foreach (int temp in arrayOfInts)
{
  Console.WriteLine(temp);
}

Here, foreach steps through the array one element at a time. With each element, it places the value of the element in the int variable called temp and then performs an iteration of the loop.

Here is another situation where you can use type inference. The foreach loop would become the following:

foreach (var temp in arrayOfInts)
{
  // …
}

int would infer from temp because that is what the collection item type is.

An important point to note with foreach is that you can't change the value of the item in the collection (temp in the preceding code), so code such as the following will not compile:

foreach (int temp in arrayOfInts)
{
  temp++;
  Console.WriteLine(temp);
}

If you need to iterate through the items in a collection and change their values, you must use a for loop instead.

Exiting Loops

Within a loop, you can stop the iterations with the break statement or end the current iteration and continue with the next iteration with the continue statement. With the return statement, you can exit the current method and thus also exit a loop.

The using Directive

Obviously, namespaces can grow rather long and tiresome to type, and the capability to indicate a particular class with such specificity may not always be necessary. Fortunately, as noted earlier in this chapter, C# allows you to abbreviate a class's full name. To do this, list the class's namespace at the top of the file, prefixed with the using keyword. Throughout the rest of the file, you can refer to the types in the namespace by their type names.

If two namespaces referenced by using declarations contain a type of the same name, you need to use the full (or at least a longer) form of the name to ensure that the compiler knows which type to access. For example, suppose classes called Test exist in both the ProCSharp.CoreCSharp and ProCSharp.OOP namespaces. If you then create a class called Test and both namespaces are imported, the compiler reacts with an ambiguity compilation error. In this case, you need to specify the namespace name for the type.

Namespace Aliases

Instead of specifying the complete namespace name for the class to resolve ambiguity issues, you can specify an alias with the using directive, as shown with different Timer classes from two namespaces:

using TimersTimer = System.Timers.Timer;
using Webtimer = System.Web.UI.Timer;

Using the StringBuilder

The StringBuilder allows a program to dynamically work with strings using Append, Insert, Remove, and Replace methods without creating new objects. Instead, the StringBuilder uses a memory buffer and modifies this buffer as the need arises. When you're creating a StringBuilder, the default capacity is 16 characters. If strings are appended as shown in the following code snippet and more memory is needed, the capacity is doubled to 32 characters (code file StringSample/Program.cs):

void UsingStringBuilder()
{
  StringBuilder sb = new("the quick");
  sb.Append(' ');
  sb.Append("brown fox jumped over ");
  sb.Append("the lazy dogs 1234567890 times");
  string s = sb.ToString();
  Console.WriteLine(s);
}

If the capacity is too small, the buffer size always doubles—for example, from 16 to 32 to 64 to 128 characters. The length of the string can be accessed with the Length property. The capacity of the StringBuilder is returned from the Capacity property. After creating the necessary string, you can use the ToString method, which allocates a new string containing the content of the StringBuilder.

String Interpolation

Code snippets in this chapter have already included strings with the $ prefix. This prefix allows evaluating expressions within the string and is known as string interpolation. For example, with string s2, the content of string s1 is embedded within s2 to have the final result of Hello, World! :

string s1 = "World";
string s2 = $"Hello, {s1}!";

You can write code expressions within the curly braces to get the expression evaluated and the result added into the string. In the following code snippet, a string is specified with three placeholders where the value of x, the value of y, and the result of the addition of x and y are put into the string:

int x = 3, y = 4;
string s3 = $"The result of {x} and {y} is {x + y}";
Console.WriteLine(s3);

The resulting string is The result of 3 and 4 is 7.

The compiler translates the interpolated string to invoke the Format method of the string, passes a string with numbered placeholders, and passes additional arguments following the string. The result of the additional arguments is from the implementation of the Format method passed to the placeholders based on the numbers. The first argument following the string is passed to the 0 placeholder, the second argument to the 1 placeholder, and so on:

string s3 = string.Format("The result of {0} and {1} is {2}", x, y, x + y);

FormattableString

What the interpolated string gets translated to can easily be seen by assigning a string to a FormattableString. The interpolated string can be directly assigned to this type because it's a better match than the normal string. This type defines the Format property that returns the resulting format string, an ArgumentCount property, and the method GetArgument that returns the argument values (code file StringSample/Program.cs):

void UsingFormattableString()
{
  int x = 3, y = 4;
  FormattableString s = $"The result of {x} + {y} is {x + y}";
  Console.WriteLine($"format: {s.Format}");
  for (int i = 0; i < s.ArgumentCount; i++)
  {
    Console.WriteLine($"argument: {i}:{s.GetArgument(i)}");
  }
  Console.WriteLine();
}

Running this code snippet results in this output:

format: The result of {0} + {1} is {2}
argument 0: 3
argument 1: 4
argument 2: 7

String Formats

With an interpolated string, you can add a string format to the expression. .NET defines default formats for numbers, dates, and time based on the computer's locale. The following code snippet shows a date, an int value, and a double with different format representations. D is used to display the date in the long date format, d in the short date format. The number is shown with integral and decimal digits (n), using an exponential notation (e), a conversion to hexadecimal (x), and a currency (c). With the double value, the first result is shown rounded after the decimal point to three digits (###.###); with the second version, the three digits before the decimal point are shown as well (000.000):

void UseStringFormat()
{
  DateTime day = new(2025, 2, 14);
  Console.WriteLine($"{day:D}");
  Console.WriteLine($"{day:d}");
 
  int i = 2477;
  Console.WriteLine($"{i:n} {i:e} {i:x} {i:c}");
 
  double d = 3.1415;
  Console.WriteLine($"{d:###.###}");
  Console.WriteLine($"{d:000.000}");
  Console.WriteLine();
}

When you run the application, this is shown:

Friday, February 14, 2025
2/14/2025
2,477.00 2.477000e+003 9ad $2,477.00
3.142

Verbatim Strings

Code snippets in the section “The Character Type” earlier in this chapter included special characters such as \t for a tab or \r\n for carriage return newline. You can use these characters in a complete string to get the specific meaning. If you need a backslash in the output of the string, you can escape this with a double backslash \\. This can be annoying if backslashes are needed multiple times because they can make the code unreadable. For such scenarios, such as when using regular expressions, you can use verbatim strings. A verbatim string is prefixed with the @ character:

string s = @"a tab: \t, a carriage return: \r, a newline: \n";
Console.WriteLine(s);

Running the preceding code results in this output:

a tab: \t, a carriage return: \r, a newline: \n

Ranges with Strings

The String type offers a Substring method to retrieve a part of a string. Instead of using the Substring method, as of C# 8 you can use the hat and the range operators. The range operator uses the .. notation to specify a range. With the string, you can use the indexer to access one character or use it with the range operator to access a substring. The numbers left and right of the .. operator specify the range. The left number specifies the 0-indexed first value from the string, which is included from the string up to the 0-indexed last value that is excluded. The range 0..3 would span the string The. To start from the first character in the string, the 0 can be omitted as shown with the following code snippet. The range 4..9 starts with the fifth character and goes up to the eighth character. To count from the end, you can use the hat operator ^ (code file StringSample/Program.cs):

void RangesWithStrings()
{
  string s = "The quick brown fox jumped over the lazy dogs down " +
    "1234567890 times";
  string the = s[..3];
  string quick = s[4..9];
  string times = s[^5..^0];
  Console.WriteLine(the);
  Console.WriteLine(quick);
  Console.WriteLine(times);
  Console.WriteLine();
}

Internal Comments Within the Source Files

C# uses the traditional C-type single-line (//..) and multiline (/* .. */) comments:

// This is a single-line comment
/* This comment
spans multiple lines. */

Everything in a single-line comment, from the // to the end of the line, is ignored by the compiler, and everything from an opening /* to the next */ in a multiline comment combination is ignored. It is possible to put multiline comments within a line of code:

Console.WriteLine(/* Here's a comment! */ "This will compile.");

Inline comments can be useful when debugging if, for example, you temporarily want to try running the code with a different value somewhere, as in the following code snippet. However, inline comments can make code hard to read, so use them with care.

DoSomething(Width, /*Height*/ 100);

XML Documentation

In addition to the C-type comments illustrated in the preceding section, C# has a very neat feature: the capability to produce documentation in XML format automatically from special comments. These comments are single-line comments, but they begin with three slashes (///) instead of two. Within these comments, you can place XML tags containing documentation of the types and type members in your code.

The tags in the following table are recognized by the compiler:

The following code snippet shows the Calculator class with documentation specified for the class, and documentation for the Add method (code file Math/Calculator.cs):

namespace ProCSharp.MathLib
{
  ///<summary>
  /// ProCsharp.MathLib.Calculator class.
  /// Provides a method to add two doubles.
  ///</summary>
  public static class Calculator
  {
    ///<summary>
    /// The Add method allows us to add two doubles.
    ///</summary>
    ///<returns>Result of the addition (double)</returns>
    ///<param name="x">First number to add</param>
    ///<param name="y">Second number to add</param>
    public static double Add(double x, double y) => x + y;
  }
}

To generate the XML documentation, you can add the GenerateDocumentationFile to the project file (project configuration file Math/Math.csproj):

<Project Sdk="Microsoft.NET.Sdk">
 
  <PropertyGroup>
    <OutputType>exe</OutputType>
    <TargetFramework>net5.0</TargetFramework>
    <Nullable>enable</Nullable>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
 
</Project>

With this setting, the documentation file is created in the same directory where the program binary will show up as you compile the application. You can also specify the DocumentationFile element to define a name that's different from the project file, and you can also specify an absolute directory where the documentation should be generated.

Using tools like Visual Studio, IntelliSense will show tooltips with the information from the documentation as the classes and members are used.

#define and #undef

#define is used like this:

#define DEBUG

This tells the compiler that a symbol with the given name (in this case DEBUG) exists. It is a little bit like declaring a variable, except that this variable doesn't really have a value—it just exists. Also, this symbol isn't part of your actual code; it exists only for the benefit of the compiler, whereas the compiler is compiling the code and has no meaning within the C# code itself.

#undef does the opposite and removes the definition of a symbol:

#undef DEBUG

If the symbol doesn't exist in the first place, then #undef has no effect. Similarly, #define has no effect if a symbol already exists.

You need to place any #define and #undef directives at the beginning of the C# source file, before any code that declares any objects to be compiled.

#define isn't of much use on its own, but when combined with other preprocessor directives, especially #if, it becomes powerful.

By default, with a Debug build, the DEBUG symbol is defined, and with the Release code, the RELEASE symbol is defined. To define different code paths on debug and release builds, you don't need to define these symbols; all you have to do is to use the preprocessor directives shown in the next section to define the code paths the compiler should take.

#if, #elif, #else, and #endif

These directives inform the compiler whether to compile a block of code. Consider this method:

int DoSomeWork(double x)
{
  // do something
  #if DEBUG
  Console.WriteLine($"x is {x}");
  #endif
}

This code compiles as normal except for the Console.WriteLine method call contained inside the #if clause. This line is executed only if the symbol DEBUG has been defined. As previously mentioned, it's defined with a Debug build—or you defined it with a previous #define directive. When the compiler finds the #if directive, it checks to see whether the symbol concerned exists and compiles the code inside the #if clause only if the symbol does exist. Otherwise, the compiler simply ignores all the code until it reaches the matching #endif directive. Typical practice is to define the symbol DEBUG while you are debugging and have various bits of debugging-related code inside #if clauses. Then, when you are close to shipping, you simply comment out the #define directive, and all the debugging code miraculously disappears, the size of the executable file gets smaller, and your end users don't get confused by seeing debugging information. (Obviously, you would do more testing to ensure that your code still works without DEBUG defined.) This technique is common in C and C++ programming and is known as conditional compilation.

The #elif (= else if) and #else directives can be used in #if blocks and have intuitively obvious meanings. It is also possible to nest #if blocks:

#define ENTERPRISE
#define W10
// further on in the file
#if ENTERPRISE
// do something
#if W10
// some code that is only relevant to enterprise
// edition running on W10
#endif
#elif PROFESSIONAL
// do something else
#else
// code for the leaner version
#endif

#if and #elif support a limited range of logical operators, too, using the operators !, ==, !=, &&, and ||. A symbol is considered to be true if it exists and false if it doesn't. Here's an example:

#if W10 && !ENTERPRISE // if W10 is defined but ENTERPRISE isn't

#warning and #error

Two other useful preprocessor directives, #warning and #error, cause a warning or an error, respectively, to be raised when the compiler encounters them. If the compiler sees a #warning directive, it displays whatever text appears after the #warning to the user, after which compilation continues. If it encounters an #error directive, it displays the subsequent text to the user as if it is a compilation error message and then immediately abandons the compilation, so no IL code is generated.

You can use these directives as checks that you haven't done anything silly with your #define statements; you can also use the #warning statements to remind yourself to do something:

#if DEBUG && RELEASE
#error "You've defined DEBUG and RELEASE simultaneously!"
#endif
 
#warning "Don't forget to remove this line before the boss tests the code!"
Console.WriteLine("*I love this job.*");

#region and #endregion

The #region and #endregion directives are used to indicate that a certain block of code is to be treated as a single block with a given name, like this:

#region Member Field Declarations
int x;
double d;
decimal balance;
#endregion

The region directives are ignored by the compiler and used by tools such as the Visual Studio code editor. The editor allows you to collapse region sections, so only the text associated with the region shows. This makes it easier to scroll through the source code. However, you should prefer to write shorter code files instead.

#line

You can use the #line directive to alter the filename and line number information that is output by the compiler in warnings and error messages. You probably won't want to use this directive often. It's most useful when you are coding in conjunction with another package that alters the code you are typing before sending it to the compiler. In this situation, line numbers, or perhaps the filenames reported by the compiler, don't match up to the line numbers in the files or the filenames you are editing. The #line directive can be used to restore the match. You can also use the syntax #line default to restore the line to the default line numbering:

#line 164 "Core.cs" // We happen to know this is line 164 in the file
// Core.cs, before the intermediate
// package mangles it.
// later on
#line default // restores default line numbering

#pragma

The #pragma directive can either suppress or restore specific compiler warnings. Unlike command-line options, the #pragma directive can be implemented on the class or method level, enabling fine-grained control over what warnings are suppressed and when. The following example disables the “field not used” warning and then restores it after the MyClass class compiles:

#pragma warning disable 169
public class MyClass
{
  int neverUsedField;
}
#pragma warning restore 169

#nullable

With the #nullable directive, you can turn on or off nullable reference types within a code file. #nullable enable turns nullable reference types on, no matter what the setting in the project file. #nullable disable turns it off. #nullable restore switches the settings back to the settings of the project file.

How do you use this? If nullable reference types are enabled with the project file, you can temporarily turn them off in code sections where you have issues with this compiler behavior and restore it to the project file settings after the code with nullability issues.

Rules for Identifiers

This section examines the rules governing what names you can use for variables, classes, methods, and so on. Note that the rules presented in this section are not merely guidelines: they are enforced by the C# compiler.

Identifiers are the names you give to variables, user-defined types such as classes and structs, and members of these types. Identifiers are case sensitive, so, for example, variables named interestRate and InterestRate would be recognized as different variables. The following are a few rules determining what identifiers you can use in C#:

• They must begin with a letter or underscore, although they can contain numeric characters.
• You can't use C# keywords as identifiers.

See the list of C# reserved keywords at https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/.

If you need to use one of these words as an identifier (for example, if you are accessing a class written in a different language), you can prefix the identifier with the @ symbol to indicate to the compiler that what follows should be treated as an identifier, not as a C# keyword (so abstract is not a valid identifier, but @abstract is).

Finally, identifiers can also contain Unicode characters, specified using the syntax \uXXXX, where XXXX is the four-digit hex code for the Unicode character. The following are some examples of valid identifiers:

• Name
• Überfluß
• _Identifier
• \u005fIdentifier

The last two items in this list are identical and interchangeable (because 005f is the Unicode code for the underscore character), so, obviously, both these identifiers couldn't be declared in the same scope.

Usage Conventions

In any development language, certain traditional programming styles usually arise. The styles are not part of the language itself but rather are conventions—for example, how variables are named or how certain classes, methods, or functions are used. If most developers using that language follow the same conventions, it's easier for different developers to understand each other's code—which in turn generally helps program maintainability. Conventions do, however, depend on the language and the environment. For example, C++ developers programming on the Windows platform have traditionally used the prefixes psz or lpsz to indicate strings— char *pszResult; char *lpszMessage;—but on Unix machines it's more common not to use any such prefixes: char *Result; char *Message;.

Whereas many languages’ usage conventions simply evolved as the language was used, for C# and the whole of the .NET Framework, Microsoft has written comprehensive usage guidelines that are detailed in the .NET/C# documentation. This means that, right from the start, .NET programs have a high degree of interoperability in terms of developers being able to understand code. The guidelines have also been developed with the benefit of some 20 years’ hindsight in object-oriented programming. Judging by the relevant newsgroups, the guidelines have been carefully thought out and are well received in the developer community. Hence, the guidelines are well worth following.

Note, however, that the guidelines are not the same as language specifications. You should try to follow the guidelines when you can. Nevertheless, you won't run into problems if you have a good reason for not doing so—for example, you won't get a compilation error because you don't follow these guidelines. The general rule is that if you don't follow the usage guidelines, you must have a convincing reason. When you depart from the guidelines, you should be making a conscious decision rather than simply not bothering. Also, if you compare the guidelines with the samples in the remainder of this book, you'll notice that in numerous examples I have chosen not to follow the conventions. That's usually because the conventions are designed for much larger programs than the samples; although the guidelines are great if you are writing a complete software package, they're not really suitable for small 20-line stand-alone programs. In many cases, following the conventions would have made the samples harder, rather than easier, to follow.

The full guidelines for good programming style are quite extensive. This section is confined to describing some of the more important guidelines, as well as those most likely to surprise you. To be absolutely certain that your code follows the usage guidelines completely, you need to refer to the Microsoft documentation.

Naming Conventions

One important aspect of making your programs understandable is how you choose to name your items—and that includes naming variables, methods, classes, enumerations, and namespaces.

It is intuitively obvious that your names should reflect the purpose of the item and should not clash with other names. The general philosophy in the .NET Framework is also that the name of a variable should reflect the purpose of that variable instance and not the data type. For example, height is a good name for a variable, whereas integerValue isn't. However, you are likely to find that principle is an ideal that is hard to achieve. Particularly when you are dealing with controls, in most cases you'll probably be happier sticking with variable names such as confirmationDialog and chooseEmployeeListBox, which do indicate the data type in the name.

The following sections look at some of the things you need to think about when choosing names.

const int MaximumLength;

private string employeeName;
public string EmployeeName
{
  get
  {
    return employeeName;
  }
}

Use of Properties and Methods

One area that can cause confusion regarding a class is whether a particular quantity should be represented by a property or a method. The rules are not hard and strict, but in general you should use a property if something should look and behave like a variable. (If you're not sure what a property is, see Chapter 3.) This means, among other things, that

• Client code should be able to read its value. Write-only properties are not recommended, so, for example, use a SetPassword method, not a write-only Password property.
• Reading the value should not take too long. The fact that something is a property usually suggests that reading it will be relatively quick.
• Reading the value should not have any observable and unexpected side effect. Furthermore, setting the value of a property should not have any side effect that is not directly related to the property. Setting the width of a dialog has the obvious effect of changing the appearance of the dialog on the screen. That's fine, because it's obviously related to the property in question.
• It should be possible to set properties in any order. In particular, it is not good practice when setting a property to throw an exception because another related property has not yet been set. For example, to use a class that accesses a database, you need to set ConnectionString, UserName, and Password, and then the author of the class should ensure that the class is implemented such that users can set them in any order.
• Successive reads of a property should give the same result. If the value of a property is likely to change unpredictably, you should code it as a method instead. Speed, in a class that monitors the motion of an automobile, is not a good candidate for a property. Use a GetSpeed method here; but Weight and EngineSize are good candidates for properties because they will not change for a given object.

If the item you are coding satisfies all the preceding criteria, it is probably a good candidate for a property. Otherwise, you should use a method.

Use of Fields

The guidelines are pretty simple here. Fields should almost always be private, although in some cases it may be acceptable for constant or read-only fields to be public. Making a field public may hinder your ability to extend or modify the class in the future.

The previous guidelines should give you a foundation of good practices, and you should use them in conjunction with a good object-oriented programming style.

A final helpful note to keep in mind is that Microsoft has been relatively careful about being consistent and has followed its own guidelines when writing the .NET base classes, so a good way to get an intuitive feel for the conventions to follow when writing .NET code is to simply look at the base classes—see how classes, members, and namespaces are named, and how the class hierarchy works. Consistency between the base classes and your classes will facilitate readability and maintainability.

Fields

Fields are any variables associated with the class. In the class Person, the fields _ firstName and _lastName of type string are defined. It's a good practice to declare fields with the private access modifier, which only allows accessing fields from within the class (code file ClassesSample/Person.cs):

public class Person
{
  //…
  private string _firstName;
  private string _lastName;
  //…
}

In the class PeopleFactory, the field s_peopleCount is of type int and has the static modifier applied. With the static modifier, the field is used with all instances of the class. Instance fields (without the static modifier) have different values for every instance of the class. Because this class only has static members, the class itself can have the static modifier applied. The compiler than makes sure that instance members are not added (code file ClassesSample/PeopleFactory.cs):

public static class PeopleFactory
{
  //…
  private static int s_peopleCount;
  //…
}

Readonly Fields

To guarantee that fields of an object cannot be changed, fields can be declared with the readonly modifier. Fields with the readonly modifier can be assigned only values from constructors. This is different from the const modifier shown in Chapter 2, “Core C#.” With the const modifier, the compiler replaces the variable by its value everywhere it is used. The compiler already knows the value of the constant. Read-only fields are assigned during runtime from a constructor. The following Person class specifies a constructor where values for both firstName and lastName need to be passed.

Contrary to const fields, read-only fields can be instance members. With the following code snippet, the _firstName and _lastName fields are changed to add the readonly modifier. The compiler complains with errors if this field is changed after initializing it in the constructor (code file ClassesSample/Person.cs):

public class Person
{
  //…
  public Person(string firstName, string lastName)
  {
    _firstName = firstName;
    _lastName = lastName;
  }
 
  private readonly string _firstName;
  private readonly string _lastName;
  //…
}

Properties

Instead of having a method pair to set and get the values of a field, C# defines the syntax of a property. From outside of the class, a property looks like a field with typically used uppercase names. Within the class, you can write a custom implementation to set not just fields and get the value of fields, but you can add some programming logic to validate the value before assigning it to a variable. You can also define a purely computed property without any variable that is accessed by the property.

The class Person as shown in the following code snippet defines a property with the name Age accessing the private field _age. With the get accessor, the value of the field is returned. With the set accessor, the variable value, which contains the value passed when setting the property, is automatically created. In the code snippet, the value variable is used to assign the value to the _age field (code file ClassesSample/Person.cs):

public class Person
{ 
  //…
 
  private int _age;
  public int Age
  {
    get => _age;
    set => _age = value;
  }
}

In case more than one statement is needed with the implementation of the property accessor, you can use curly brackets as shown in the following code snippet:

private int _age;
public int Age
{
  get
  {
    return _age;
  }
  set 
  {
    _age = value;
  }
}

To use the property, you can access the property from an object instance. Setting a value to the property invokes the set accessor. Reading the value invokes the get accessor:

person.Age = 4; // setting a property value with the set accessor
int age = person.Age; // accessing the property with the get accessor

public int Age { get; set; }

public int Age { get; set; } = 42;

private string _name;
public string Name
{
  get => _name;
  private set => _name = value;
}

public int Age { get; private set; }

private readonly string _firstName;
public string FirstName
{
  get => _firstName;
}

private readonly string _firstName;
public string FirstName => _firstName;
private readonly string _lastName;
public strign LastName => _lastName;
public string FullName => $"{FirstName} {LastName}";

public string Id { get; } = Guid.NewGuid().ToString();

public class Book
{
  public Book(string title) => Title = title;
 
  public string Title { get; }
}

public class Book
{
  public Book(string title)
  {
    Title = title;
  }
 
  public string Title { get; init; }
  public string? Publisher { get; init; }
}

Book theBook = new("Professional C#") 
{ 
  Publisher = "Wrox Press"
};

Methods

With the C# terminology, there's a distinction between functions and methods. The term function member includes not only methods, but also other nondata members such as indexers, operators, constructors, destructors, and properties—all members that contain executable code.

public bool IsSquare(Rectangle rect)
{
  return (rect.Height == rect.Width);
}

public bool IsSquare(Rectangle rect) => rect.Height == rect.Width;

public class Math
{
  public int Value { get; set; }
  public int GetSquare() => Value * Value;
  public static int GetSquareOf(int x) => x * x;
}

using System;
 
// Call static members
int x = Math.GetSquareOf(5);
Console.WriteLine($"Square of 5 is {x}");
 
// Instantiate a Math object
Math math = new();
 
// Call instance members
math.Value = 30;
Console.WriteLine($"Value field of math variable contains {math.Value}");
Console.WriteLine($"Square of 30 is {math.GetSquare()}");

Square of 5 is 25
Value field of math variable contains 30
Square of 30 is 900

class ResultDisplayer
{
  public void DisplayResult(string result)
  {
    // implementation
  }
 
  public void DisplayResult(int result)
  {
    // implementation
  }
}

class MyClass
{
  public int DoSomething(int x) => DoSomething(x, 10);
 
  public int DoSomething(int x, int y)
  {
    // implementation
  }
}

public void MoveAndResize(int x, int y, int width, int height)

r.MoveAndResize(30, 40, 20, 40);

r.MoveAndResize(x: 30, y: 40, width: 20, height: 40);

public void TestMethod(int notOptionalNumber, int optionalNumber = 42)
{
  Console.WriteLine(optionalNumber + notOptionalNumber);
}

TestMethod(11);
TestMethod(11, 42);

public void TestMethod(int n, int opt1 = 11, int opt2 = 22, int opt3 = 33)
{
  Console.WriteLine(n + opt1 + opt2 + opt3);
}

TestMethod(1);
TestMethod(1, 2, 3);

TestMethod(1, opt3: 4);

public void AnyNumberOfArguments(params int[] data)
{
  foreach (var x in data)
  {
    Console.WriteLine(x);
  }
}

AnyNumberOfArguments(1);
AnyNumberOfArguments(1, 3, 5, 7, 11, 13);

public void AnyNumberOfArguments(params object[] data)
{
  // …

AnyNumberOfArguments("text", 42);

Console.WriteLine(string format, params object[] arg);

Constructors

The syntax for declaring basic constructors is a method that has the same name as the containing class and that does not have any return type:

public class MyClass
{
  public MyClass()
  {
  }
 
  //…
}

It's not necessary to provide a constructor for your class. If you don't supply any constructor, the compiler generates a default behind the scenes. This constructor initializes all the member fields to the default values, which is 0 for numbers, false for bool, and null for reference types. When you're using nullable reference types and don't declare your reference types to allow null, you'll get a compiler warning if these fields are not initialized.

Constructors follow the same rules for overloading as other methods—that is, you can provide as many overloads to the constructor as you want, provided they are clearly different in signature:

public MyClass() // parameterless constructor
{
  // construction code
}
 
public MyClass(int number) // constructor overload with an int parameter
{
  // construction code
}

If you supply any constructors, the compiler does not automatically supply a default one. The default constructor is created only if other constructors are not defined.

Note that it is possible to define constructors as private or protected so that they are invisible to code in unrelated classes, too:

public class MyNumber
{
  private int _number;
  private MyNumber(int number) => _number = number;
  //…
}

An example in which this is useful is to create a singleton where an instance can be created only from a static factory method.

public class Singleton
{
  private static Singleton s_instance;
  private int _state;
  private Singleton(int state) => _state = state;
 
  public static Singleton Instance => s_instance ??= new Singleton(42);
}

public class Book
{
  public Book(string title, string publisher) => 
    (Title, Publisher) = (title, publisher);
 
  public string Title { get; }
  public string Publisher { get; }
}

class Car
{
  private string _description;
  private uint _nWheels;
  public Car(string description, uint nWheels)
  {
    _description = description;
    _nWheels = nWheels;
  }
  public Car(string description): this(description, 4)
  {
  }
}

class MyClass
{
  static MyClass()
  {
    // initialization code
  }
  //…
}

Local Functions

Methods with a public access modifier can be invoked from outside of the class. Methods with a private access modifier can be invoked from anywhere within the class (from other methods, property accessors, constructors, and so on). To restrict this further, a local function can be invoked only from within the method where the local function is declared. The local function has the scope of the method and cannot be invoked from somewhere else.

Within the method IntroLocalFunctions, the local function Add is defined. Parameters and return types are implemented in the same way as a normal method. Similarly to a normal method, a local function can be implemented by using curly brackets or with an expression-bodied implementation as shown in the following code. Since C# 8, the local function can have the static modifier associated if the implementation doesn't access instance members defined with the class or local variables of the method. With the static modifier, the compiler makes sure this does not happen and can optimize the generated code. The local function is invoked in the method itself; it cannot be invoked anywhere else in the class. Whether the local function is declared before or after its use is just a matter of taste (code file MethodSample/LocalFunctionsSample.cs):

public static void IntroLocalFunctions()
{
  static int Add(int x, int y) => x + y;
 
  int result = Add(3, 7);
  Console.WriteLine("called the local function with this result: {result}");        
}

With the next code snippet, the local function Add is declared without the static modifier. In the implementation, this function not only uses the variables specified with the arguments of the function but also variable z, which is specified in the outer scope of the local function, within the scope of the method. When accessing the variable outside of its scope (known as closure), the compiler creates a class where the data used within this function is passed in a constructor. Here, the local function needs to be declared after the variables used within the local function. That's why the local function is put at the end of the method LocalFunctionWithClosure :

public static void LocalFunctionWithClosure()
{
  int z = 3;
 
  int result = Add(1, 2);
  Console.WriteLine("called the local function with this result: {result}");
 
  int Add(int x, int y) => x + y + z;
}

Generic Methods

If you need implementations of methods that support multiple types, you can implement generic methods. The method Swap<T> defines T as a generic type that is used for two arguments and a local variable temp (code file MeethodSample/GenericMethods.cs):

class GenericMethods
{
  public static void Swap<T>(ref T x, ref T y)
  {
    T temp;
    temp = x;
    x = y;
    y = temp;
  }
}

Extension Methods

With extension methods, you can create methods that extend other types.

The following code snippet defines the method GetWordCount that is used to extend the string type. An extension method is not defined by the name of the class but instead by using the this modifier with the parameter. GetWordCount extends the string type because the parameter with the this modifier (which needs to be the first parameter) is of type string. Extension methods need to be static and declared in a static class (code file ExtensionMethods/StringExtensions.cs):

public static class StringExtensions
{
  public static int GetWordCount(this string s) => s.Split().Length;           
}

To use this extension method, the namespace of the extension class needs to be imported; then the method can be called in the same way as an instance method (code file ExtensionMethods/Program.cs):

string fox = "the quick brown fox jumped over the lazy dogs";
int wordCount = fox.GetWordCount();
Console.WriteLine($"{wordCount} words");
Console.ReadLine();

It might look like extension methods break object-oriented rules in regard to inheritance and encapsulation because methods can be added to an existing type without inheriting from it and without changing the type. However, you can only access public members. Extension methods are really just “syntax sugar” because the compiler changes the invocation of the method to call a static method that's passing the instance as the parameter, as shown here:

int wordCount = StringExtensions.GetWordCount(fox);

Why would you create extension methods instead of calling static methods? The code can become a lot easier to read. Just check into the extension methods implemented for LINQ (see Chapter 9) or the extension methods used to configure configuration and logging providers (see Chapter 15, “Dependency Injection and Configuration”).

Anonymous Types

Chapter 2 discusses the var keyword in reference to implicitly typed variables. When used with the new keyword, you can create anonymous types. An anonymous type is simply a nameless class that inherits from object. The definition of the class is inferred from the initializer, just as with implicitly typed variables.

For example, if you need an object that contains a person's first, middle, and last name, the declaration would look like this:

var captain = new
{
  FirstName = "James",
  MiddleName = "Tiberius",
  LastName = "Kirk"
};

This would produce an object with FirstName, MiddleName, and LastName read-only properties. If you were to create another object that looked like this:

var doctor = new
{
  FirstName = "Leonard",
  MiddleName = string.Empty,
  LastName = "McCoy"
};

then the types of captain and doctor are the same. You could set captain = doctor, for example. This is possible only if all the properties match.

The names for the members of anonymous types can be inferred if the values that are being set come from another object. This way, the initializer can be abbreviated. If you already have a class that contains the properties FirstName, MiddleName, and LastName and you have an instance of that class with the instance name person, then the captain object could be initialized like this:

var captain = new
{
  person.FirstName,
  person.MiddleName,
  person.LastName
};

The property names from the person object are inferred in the new object named captain, so the object named captain has FirstName, MiddleName, and LastName properties.

The actual type name of anonymous types is unknown, which is where the name comes from. The compiler “makes up” a name for the type, but only the compiler is ever able to make use of it. Therefore, you can't and shouldn't plan on using any type reflection on the new objects because you will not get consistent results.

Immutable Types

A main use case for records is to create immutable types (although you can also create mutable types with records). An immutable type just contains members where the state of the type cannot be changed. You can initialize such a type in a constructor or with an object initializer, but you can't change any values afterward.

Immutable types are useful with multithreading. When you're using multiple threads to access the immutable object, you don't need to worry with synchronization because the values cannot change.

An example of an immutable type is the String class. This class does not define any member that is allowed to change its content. Methods such as ToUpper (which changes the string to uppercase) always return a new string, but the original string passed to the constructor remains unchanged.

Nominal Records

Records can be created in two kinds: nominal and positional records. A nominal record looks like a class just using the record keyword instead of the class keyword, as shown with the type Book1. Here, init-only set accessors are used to forbid state changes after an instance has been created (code file RecordsSample/Program.cs):

public record Book1
{
    public string Title { get; init; } = string.Empty;
    public string Publisher { get; init; } = string.Empty;
}

You can add constructors and all the other members you learned about in this chapter. The compiler just creates a class with the record syntax. What's different from classes is that the compiler creates some more functionality inside this class. The compiler overrides the GetHashCode and ToString methods of the base class object, creates methods and operator overloads to compare different values for equality, and creates methods to clone existing objects and create new ones where object initializers can be used to change some property values.

Positional Records

The second way to implement a record is to use the positional record syntax. With this syntax, parentheses are used after the name of the record to specify the members. This syntax has the name primary constructor. The compiler creates a class from this code as well, with init-only set accessors for the types used with the primary constructor and a constructor with the same parameters to initialize the properties (code file RecordsSample/Program.cs):

public record Book2(string Title, string Publisher);

You can use curly brackets to add what you need to the already existing implementation—for example, by adding overloaded constructors, methods, or any other members you've seen earlier in this chapter:

public record Book2(string Title, string Publisher)
{
  // add your members, overloads
}

As the compiler creates a constructor with parameters, you can instantiate an object as you're used to—by passing the values to the constructor (code file RecordsSample/Program.cs):

Book2 b2 = new("Professional C#", "Wrox Press");
Console.WriteLine(b2);

Because the compiler creates a ToString method that is implicitly invoked by passing the variable to the WriteLine method, this is what's shown on the console: the name of the class followed by the property names with their values in curly brackets:

Book2 { Title = Professional C#, Publisher = Wrox Press }

With positional records, the compiler creates the same members as with nominal records and adds methods for deconstruction. Deconstruction is explained later in this chapter in the section “Deconstruction.”

Equality Comparison with Records

With classes, the default implementation for equality is to compare the reference. Creating two new objects of the same type that are initialized to the same values are different because they reference different objects in the heap. This is different with records. With the equality implementation of records, two records are equal if their property values are the same.

In the following code snippet, two records that contain the same values are created. The object.ReferenceEquals method returns false, because these are two different references. Using the equal operator == returns true because this operator is implemented with the record type (code file RecordsSample/Program.cs):

Book1 book1a = new() { Title = "Professional C#", Publisher = "Wrox Press" };
Book1 book1b = new() { Title = "Professional C#", Publisher = "Wrox Press" };
if (!object.ReferenceEquals(book1a, book1b)) 
  Console.WriteLine("Two different references for equal records");
 
if (book1a == book1b) 
  Console.WriteLine("Both records have the same values");

The record type implements the IEquality interface with the Equals method, as well as the equality == and the inequality != operators.

With Expressions

Records make it easy to create immutable types, but there's a new feature with records for easily creating new record instances. The .NET Compiler Platform (also known by the name Roslyn) is built with immutable objects and many With methods to create new objects from existing ones. With the C# 9 enhancement, the with expressions, there's a lot of simplification that can be used by the Roslyn team. The code created with the record syntax includes a copy constructor and a Clone method with a hidden name where all the values of the existing object are copied to a new instance that's returned from this method. The with expression now makes use of this Clone method, and with the init-only set accessors, you can use object initialization to set the values that should be different.

var aNewBook = book1a with { Title = "Professional C# and .NET - 2024" };

ref Parameters

The following code snippet defines the method ChangeAValueType, where an int is passed by reference. Remember, the int is declared as struct, so this behavior is valid with custom structs as well. By default, the int would be passed by value. Because of the ref modifier, the int is passed by reference (using an address of the int variable). Within the implementation, now the variable named x references the same data on the stack as the variable a does. Changing the value of x also changes the value of a, so after the invocation, the variable a contains the value 2 (code file RefInOutSample/Program.cs):

int a = 1;
ChangeAValueType(ref a);
Console.WriteLine($"the value of a changed to {a}");
 
void ChangeAValueType(ref int x)
{
  x = 2;
}

Passing a value type by reference requires the ref keyword with the method declaration and when calling the method. This is important information for the caller; knowing the method receiving this value type can change the content.

Now you might wonder if it could be useful to pass a reference by using the ref keyword. Passing a reference allows the method to change the content anyway. Indeed, it can be useful, as the following code snippet demonstrates. The method ChangingAReferenceByReference specifies the ref modifier with the argument of type SomeData, which is a class. In the implementation, first the value of the Value property is changed to 2. After this, a new instance is created, which references an object with a Value of 3. If you try to remove the ref keyword from the method declaration, as well as the invocation of this method, after the invocation data1.Value has the value 2. Without the ref keyword, the data1 variable references the object on the heap and the data variable at the beginning of the method. After creating a new object, the data variable references a new object on the heap, which then contains the value 3. With the ref keyword used as in the sample, the data variable references the data1 variable; it's a pointer to a pointer. This way, a new instance can be created within the ChangingAReferenceByRef method, and the variable data1 references this new object instead of the old one:

SomeData data1 = new() { Value = 1 };
ChangingAReferenceByRef(ref data1);
Console.WriteLine($"the new value of data1.Value is: {data1.Value}");
 
void ChangingAReferenceByRef(ref SomeData data)
{
  data.Value = 2;
  data = new SomeData { Value = 3 };
}
 
class SomeData
{
  public int Value { get; set; }
}

in Parameters

If you want to avoid the overhead of copying a value type when passing it to a method but don't want to change the value within the method, you can use the in modifier.

For the next sample code, the SomeValue struct, which contains four int values, is defined (code file RefInOutSample/Program.cs):

struct SomeValue
{
  public SomeValue(int value1, int value2, int value3, int value4)
  {
    Value1 = value1;
    Value2 = value2;
    Value3 = value3;
    Value4 = value4;
  }
  public int Value1 { get; set; }
  public int Value2 { get; set; }
  public int Value3 { get; set; }
  public int Value4 { get; set; }
}

If you declare a method where the SomeValue struct is passed as an argument, the four int values need to be copied on method invocation. When you use the ref keyword, you don't need a copy, and you can pass a reference. However, with the ref keyword, the caller might not want the called method to make any change. To guarantee that changes are not happening, you use the in modifier. With this modifier, a pass by reference is happening, but the compiler does not allow change to any value when the data variable is used. Data is now a read-only variable:

void PassValueByReferenceReadonly(in SomeValue data)
{
  // data.Value1 = 4; - you cannot change a value, it's a read-only variable!
}

ref return

To avoid copying the value on return of a method, you can declare the return type with the ref keyword and use return ref. The Max method receives two SomeValue structs with the parameters and returns the larger of these two. With the parameters, the values are not copied using the ref modifier, as shown here:

ref SomeValue Max(ref SomeValue x, ref SomeValue y)
{
  int sumx = x.Value1 + x.Value2 + x.Value3 + x.Value4;
  int sumy = y.Value1 + y.Value2 + y.Value3 + y.Value4;
 
  if (sumx> sumy)
  {
    return ref x;
  }
  else
  {
    return ref y;
  }
}

Within the implementation of the Max method, you can replace the if / else statement with a conditional ref expression. With this, the ref keyword needs to be used with the expression to compare sumx and sumy. Based on the result, a ref to x or to y is written to a ref local, which is then returned:

ref SomeValue Max(ref SomeValue x, ref SomeValue y)
{
  int sumx = x.Value1 + x.Value2 + x.Value3 + x.Value4;
  int sumy = y.Value1 + y.Value2 + y.Value3 + y.Value4;
 
  ref SomeValue result = ref (sumx > sumy) ? ref x : ref y;
  return ref result;
}

Whether the returned value should be copied or a reference should be used is a decision from the caller. In the following code snippet, with the first invocation of the Max method, the result is copied to the bigger1 variable, although the method is declared to return a ref. There's not a compiler error with the first version (contrary to the ref parameters). You will not have any issues when the value is copied—other than the performance hit. With the second invocation, the ref keyword is used to invoke the method to get a ref return. With this invocation, the result needs to be written to a ref local. The third invocation writes the result into a ref readonly local. With the Max method, there's no change needed. The readonly used here is only to specify that the bigger3 variable will not be changed, and the compiler complains if properties are set to change its values:

SomeValue one = new SomeValue(1, 2, 3, 4);
SomeValue two = new SomeValue(5, 6, 7, 8);
 
SomeValue bigger1 = Max(ref one, ref two);
ref SomeValue bigger2 = ref Max(ref one, ref two);
ref readonly SomeValue bigger3 = ref Max(ref one, ref two);

The Max method doesn't change any of its inputs. This allows using the in keyword with the parameters as shown with the MaxReadonly method. However, here the declaration of the return must be changed to ref readonly. If this change wouldn't be necessary, the caller of this method would be allowed to change one of the inputs of the MaxReadonly method after receiving the result:

ref readonly SomeValue MaxReadonly(in SomeValue x, in SomeValue y)
{
  int sumx = x.Value1 + x.Value2 + x.Value3 + x.Value4;
  int sumy = y.Value1 + y.Value2 + y.Value3 + y.Value4;
 
  return ref (sumx> sumy) ? ref x : ref y;
}

Now the caller is required to write the result to a ref readonly or to copy the result into a new local. With bigger5, readonly is not required because the original value received is copied:

ref readonly SomeValue bigger4 = ref MaxReadonly(in one, in two);
SomeValue bigger5 = MaxReadonly(in one, in two);

out Parameters

If a method should return multiple values, there are different options. One option is to create a custom type. Another option is to use the ref keyword with parameters. Using the ref keyword, the parameter needs to be initialized before invoking the method. With the ref keyword, data is passed into and returned from the method. If the method should just return data, you can use the out keyword.

The int.Parse method expects a string to be passed and returns an int—if the parsing succeeds. If the string cannot be parsed to an int, an exception is thrown. To avoid such exceptions, you can instead use the int.TryParse method. This method returns a Boolean whether the parsing is successful or not. The result of the parse operation is returned with an out parameter.

This is the declaration of the TryParse method with the int type:

bool TryParse(string? s, out int result);

To invoke the TryParse method, an int is passed with the out modifier. Using the out modifier, the variable doesn't need to be declared before invoking the method and doesn't need to be initialized:

Console.Write("Please enter a number: ");
string? input = Console.ReadLine();
if (int.TryParse(input, out int x))
{
  Console.WriteLine();
  Console.WriteLine($"read an int: {x}");
}

TUPLES

With arrays, you can combine multiple objects of the same type into one object. When you're using classes, structs, and records, you can combine multiple objects into one object and add properties, methods, events, and all the different members of types. Tuples enable you to combine multiple objects of different types into one without the complexity of creating custom types.

To better understand some advantages of tuples, let's take a look at what a method can return. To return a result from a method that returns multiple results, you need to either create a custom type where you can combine the different result types or use the ref or out keywords with parameters. Using ref and out has an important restriction: you cannot use this with asynchronous methods. Creating custom types has its advantages, but in some cases, this is not needed. You have a simpler path with tuples and can return a tuple from a method. As of C# 7, tuples are integrated with the C# syntax.

Declaring and Initializing Tuples

A tuple can be declared using parentheses and initialized using a tuple literal that is created with parentheses as well. In the following code snippet, on the left side, a tuple variable tuple1 that contains a string, an int, and a Book is declared. On the right side, a tuple literal is used to create a tuple with the string magic, the number 42, and a Book object initialized using the primary constructor of the Book record. The tuple can be accessed using the variable tuple1 with the members declared in the parentheses (AString, Number, and Book in this example; code file TuplesSample/Program.cs):

void IntroTuples()
{
  (string AString, int Number, Book Book) tuple1 = 
    ("magic", 42, new Book("Professional C#", "Wrox Press"));
    Console.WriteLine($"a string: {tuple1.AString}, " + 
      $"number: {tuple1.Number}, " + 
      $"book: {tuple1.Book}");
  //…
}

public record Book(string Title, string Publisher);

When you run the application (the top-level statements invoke IntroTuples), the output shows the values of the tuple:

a string: magic, number: 42, book: Book { Title = Professional C#, Publisher = Wrox Press }

The tuple literal also can be assigned to a tuple variable without declaring its members. This way the members of the tuple are accessed using the member names of the ValueTuple struct: Item1, Item2, and Item3 :

var tuple2 = ("magic", 42, new Book("Professional C#", "Wrox Press"));
Console.WriteLine($"a string: {tuple2.Item1}, number: {tuple2.Item2}, " + 
  $"book: {tuple2.Item3}");

You can assign names to the tuple fields in the tuple literal by defining the name followed by a colon, which is the same syntax as with object literals:

var tuple3 = (AString: "magic", Number: 42, 
  Book: new Book("Professional C#", "Wrox Press"));

With all this, names are just a convenience. You can assign one tuple to another one when the types match; the names do not matter:

(string S, int N, Book B) tuple4 = tuple3;

The name of the tuple members can also be inferred from the source. With the variable tuple5, the second member is a string with the title of the book. A name for this member is not assigned, but because the property has the name Title, Title is automatically taken for the tuple member name:

Book book = new("Professional C#", "Wrox Press");
var tuple5 = (ANumber: 42, book.Title);
Console.WriteLine(tuple5.Title);

Tuple Deconstruction

Tuples can be deconstructed into variables. To do this, you just need to remove the tuple variable from the previous code sample and define variable names in parentheses. The variables that contain the values of the tuple parts can then be directly accessed. In case some variables are not needed, you can use discards. Discards are C# placeholder variables with the name _. Discards are meant to just ignore the results, as shown with the second deconstruction in the following code snippet (code file TuplesSample/Program.cs):

void TuplesDeconstruction()
{
  var tuple1 = (AString: "magic", 
    Number: 42, Book: new Book("Professional C#", "Wrox Press"));
  (string aString, int number, Book book) = tuple1;
 
  Console.WriteLine($"a string: {aString}, number: {number}, book: {book}");
 
  (_, _, var book1) = tuple1;
  Console.WriteLine(book1.Title);
}

Returning Tuples

Let's get into a more useful example: a method returning a tuple. The method Divide from the following code snippet receives two parameters and returns a tuple consisting of two int values. Tuple results are created by putting the methods return group within parentheses (code file Tuples/Program.cs):

static (int result, int remainder) Divide(int dividend, int divisor)
{
  int result = dividend / divisor;
  int remainder = dividend % divisor;
  return (result, remainder);
}

The result is deconstructed into the result and remainder variables:

private static void ReturningTuples()
{
  (int result, int remainder) = Divide(7, 2);
  Console.WriteLine($"7 / 2 - result: {result}, remainder: {remainder}");
}

Pattern Matching with Tuples

The previous chapter included a sample of simple pattern matching with traffic lights. Now let's extend this sample with not just a simple flow from red to green to amber to red… but to change to different states after amber depending on what the previous light was. Pattern matching can be based on tuple values.

The method NextLightUsingTuples receives enum values for the current and previous traffic light in two parameters. The two parameters are combined to a tuple with (current, previous) to define the switch expression based on this tuple. With the switch expression, tuple patterns are used. The first case matches when the current light has the value Red. The value of the previous light is ignored using a discard. The NextLightUsingTuples method is declared to return a tuple with Current and Previous properties. In the first match, a tuple that matches this return type is returned with (Amber, current) to specify the new value Amber for the current light. In all the cases, the previous light is set from the current light that was received. When the current light is Amber, now the tuple pattern results in different outcomes depending on the previous light. If the previous light was Red, the new light returned is Green, and vice versa (code file PatternMatchingSample/Program.cs):

(TrafficLight Current, TrafficLight Previous) 
  NextLightUsingTuples(TrafficLight current, TrafficLight previous) =>
    (current, previous) switch
    {
      (Red, _) => (Amber, current),
      (Amber, Red) => (Green, current),
      (Green, _) => (Amber, current),
      (Amber, Green) => (Red, current),
      _ => throw new InvalidOperationException()
    };

With the following code snippet, the method NextLightUsingTuples is invoked in a for loop. The return value is deconstructed into currentLight and previousLight variables to write the current light information to the console and to invoke the NextLightUsingTuples method in the next iteration:

var previousLight = Red;
var currentLight = Red;
for (int i = 0; i < 10; i++)
{
  (currentLight, previousLight) = NextLightUsingTuples(currentLight, 
    previousLight);
  Console.Write($"{currentLight} - ");
  await Task.Delay(1000);
}
Console.WriteLine();

Property Pattern

Let's extend the traffic light sample again. When you're using tuples, additional values and types can be added to extend the functionality. However, at some point this doesn't help with readability, and using classes or records is helpful.

One extension to the traffic light is having different timings for the different light phases. Another extension is used in some countries: before the light changes from the green to the amber light, another phase is introduced: the green light blinks three times. To keep up with the different states, the record TrafficLightState is introduced (code file PatternMatchingSample/Program.cs):

public record TrafficLightState(TrafficLight CurrentLight, 
  TrafficLight PreviousLight, int Milliseconds, int BlinkCount = 0);

The enum type TrafficLight is extended to include GreenBlink and AmberBlink :

public enum TrafficLight
{
  Red,
  Amber,
  Green,
  GreenBlink,
  AmberBlink
}

The new method NextLightUsingRecords receives a parameter of type TrafficLightState with the current light state and returns a TrafficLightState with the new state. In the implementation, a switch expression is used again. This time, the cases are selected using the property pattern. If the property CurrentLight of the variable trafficLightState has the value AmberBlink, a new TrafficLightState with the current red light is returned. When the CurrentLight is set to Amber, the PreviousLight property is verified as well. Depending on the PreviousLight value, different records are returned. Another pattern is used in this scenario—the relational pattern that is new with C# 9. BlinkCount: < 3 references the BlinkCount property and verifies whether the value is smaller than 3. If this is the case, the returned TrafficLightState is cloned from the previous state using the with expression, and the BlinkCount is incremented by 1 :

TrafficLightState NextLightUsingRecords(TrafficLightState trafficLightState) 
  => trafficLightState switch
  {
    { CurrentLight: AmberBlink } => 
      new TrafficLightState(Red, trafficLightState.PreviousLight, 3000),
    { CurrentLight: Red } => 
      new TrafficLightState(Amber, trafficLightState.CurrentLight, 200),
    { CurrentLight: Amber, PreviousLight: Red} => 
      new TrafficLightState(Green, trafficLightState.CurrentLight, 2000),
    { CurrentLight: Green } => 
      new TrafficLightState(GreenBlink, trafficLightState.CurrentLight, 
        100, 1),
    { CurrentLight: GreenBlink, BlinkCount: < 3 } => 
      trafficLightState with 
        { BlinkCount = trafficLightState.BlinkCount + 1 },
    { CurrentLight: GreenBlink } => 
      new TrafficLightState(Amber, trafficLightState.CurrentLight, 200),
    { CurrentLight: Amber, PreviousLight: GreenBlink } => 
      new TrafficLightState(Red, trafficLightState.CurrentLight, 3000),
    _ => throw new InvalidOperationException()
  };

The method NextLightUsingRecords is invoked in a for loop similar to the sample before. Now, an instance of TrafficLightState is passed as an argument to the method NextLightUsingRecords. The new value is received from this method, and the current state is shown on the console:

TrafficLightState currentLightState = new(AmberBlink, AmberBlink, 2000);
 
for (int i = 0; i < 20; i++)
{
  currentLightState = NextLightUsingRecords(currentLightState);
  Console.WriteLine($"{currentLightState.CurrentLight}, 
    {currentLightState.Milliseconds}");
  await Task.Delay(currentLightState.Milliseconds);
}

Virtual Methods

By declaring a base class method as virtual, you allow the method to be overridden in any derived classes.

The following code snippet shows the DisplayShape method that is declared with the virtual modifier. This method is invoked by the Draw method of the Shape. Virtual methods can be public or protected. The access modifier cannot be changed when overriding this method in a derived class. Because the Draw method has a public access modifier, this method can be used from the outside when using the Shape or when using any class deriving from Shape. The Draw method cannot be overridden as it doesn't have the virtual modifier applied (code file VirtualMethods/Shape.cs):

public class Shape
{
  public void Draw() => DisplayShape();
 
  protected virtual void DisplayShape()
  {
    Console.WriteLine($"Shape with {Position} and {Size}");
  }
}

You also may declare a property as virtual. For a virtual or overridden property, the syntax is the same as for a nonvirtual property, with the exception of the keyword virtual, which is added to the definition:

public virtual Size Size { get; set; }

For simplicity, the following discussion focuses mainly on methods, but it applies equally well to properties.

Methods that are declared virtual can be overridden in a derived class. To declare a method that overrides a method from a base class, use the override keyword (code file VirtualMethods/ConcreteShapes.cs):

public class Rectangle : Shape
{
  protected override void DisplayShape()
  {
    Console.WriteLine($"Rectangle at position {Position} with size {Size}");
  }
}

Virtual functions offer a core feature of OOP: polymorphism. With virtual functions, the decision of which method to invoke is delayed during runtime. The compiler creates a virtual method table (vtable) that lists the methods that can be invoked during runtime, and it invokes the method based on the type at runtime.

For performance reasons, in C#, functions are not virtual by default. For nonvirtual functions, the vtable is not needed, and the compiler directly addresses the method that's invoked.

The Size and Position types override the ToString method. This method is declared as virtual in the base class Object (code file VirtualMethods/ConcreteShapes.cs):

public class Position
{
  public int X { get; set; }
  public int Y { get; set; }
 
  public override string ToString() => $"X: {X}, Y: {Y}";
}
 
public class Size
{
  public int Width { get; set; }
  public int Height { get; set; }
 
  public override string ToString() => $"Width: {Width}, Height: {Height}";
}

Before C# 9, there was the rule that, when overriding methods of the base class, the signature (all parameter types and the method name) and the return type must match exactly. If you want different parameters, you need to create a new member that does not override the base member.

With C# 9, there's a small change to this rule: when overriding methods, the return type might differ, but only to return a type that derives from the return type of the base class. One example where this can be used is to create a type-safe Clone method. The Shape class defines a virtual Clone method that returns a Shape (code file VirtualMethods/Shape.cs):

public virtual Shape Clone() => throw new NotImplementedException(); 

The Rectangle class overrides this method to return a Rectangle type instead of the base class Shape by creating a new instance and copying all the values from the existing instance to the newly created one:

public override Rectangle Clone()
{
  Rectangle r = new();
  r.Position.X = Position.X;
  r.Position.Y = Position.Y;
  r.Size.Width = Size.Width;
  r.Size.Height = Size.Width;
  return r;
}

In the top-level statements of the Program.cs file, a rectangle and an ellipse are instantiated, properties are set, and the rectangle is cloned by invoking the virtual Clone method. Finally, the DisplayShapes method is invoked passing all the different created shapes. The Draw method of the Shape class is invoked to, in turn, invoke the overridden methods of the derived types. In this code snippet, you also see the Ellipse class used; this is similar to the Rectangle type, deriving from Shape (code file VirtualMethods/Program.cs):

Rectangle r1 = new();
r1.Position.X = 33;
r1.Position.Y = 22;
r1.Size.Width = 200;
r1.Size.Height = 100;
 
Rectangle r2 = r1.Clone();
r2.Position.X = 300;
 
Ellipse e1 = new();
e1.Position.X = 122;
e1.Position.Y = 200;
e1.Size.Width = 40;
e1.Size.Height = 20;
 
DisplayShapes(r1, r2, e1);
 
void DisplayShapes(params Shape[] shapes)
{
  foreach (var shape in shapes)
  {
    shape.Draw();
  }
}

Run the program to see the output of the Draw method coming from the implementation of the overridden Rectangle and Shape DisplayShape methods:

Rectangle at position X: 33, Y: 22 with size Width: 200, Height: 100
Rectangle at position X: 300, Y: 22 with size Width: 200, Height: 200
Ellipse at position X: 122, Y: 200 with size Width: 40, Height: 20

Hiding Methods

If a method with the same signature is declared in both base and derived classes, but the methods are not declared with the modifiers virtual and override, respectively, then the derived class version is said to hide the base class version.

For hiding methods, you can use the new keyword as a modifier with the method declaration. In most cases, you would want to override methods rather than hide them. By hiding them, you risk calling the wrong method for a given class instance. However, as shown in the following example, C# syntax is designed to ensure that the developer is warned at compile time about this potential problem, thus making it safer to hide methods if that is your intention. This also has versioning benefits for developers of class libraries.

Suppose that you have a class called Shape in a class library:

public class Shape
{
  // various members
}

At some point in the future, you write a derived class Ellipse that adds some functionality to the Shape base class. In particular, you add a method called MoveBy, which is not present in the base class:

public class Ellipse: Shape
{
  public void MoveBy(int x, int y)
  {
    Position.X += x;
    Position.Y += y;
  }
}

At some later time, the developer of the base class decides to extend the functionality of the base class and, by coincidence, adds a method that is also called MoveBy and that has the same name and signature as yours; however, it probably doesn't do the same thing. This new method might be declared virtual or not.

If you recompile the derived class, you get a compiler warning because of a potential method clash. The application is still working, and where you've written code to invoke the MoveBy method using the Ellipse class, the method you've written is invoked. Hiding a method is the default behavior to avoid breaking changes when adding methods to a base class.

To get rid of the compilation error, you need to add the new modifier to the MoveBy method. The code the compiler is creating with or without the new modifier is the same; you just get rid of the compiler warning and flag this as a new method—a different one from the base class:

public class Ellipse: Shape
{
  new public void MoveBy(int x, int y)
  {
    Position.X += x;
    Position.Y += y;
  }
  //…
}

Instead of using the new keyword, you can also rename the method or override the method of the base class if it is declared virtual and serves the same purpose. However, if other methods already invoke this method, a simple rename can lead to breaking other code.

Calling Base Versions of Methods

If a derived class overrides or hides a method in its base class, then it can invoke the base class version of the method by using the base keyword. For example, in the base class Shape, the virtual Move method is declared to change the actual position and write some information to the console. This method should be called from the derived class Rectangle to use the implementation from the base class (code file VirtualMethods/Shape.cs):

public class Shape
{
  public virtual void Move(Position newPosition)
  {
    Position.X = newPosition.X;
    Position.Y = newPosition.Y;
    Console.WriteLine($"moves to {Position}");
  }
  //…
}

The Move method is overridden in the Rectangle class to add the term Rectangle to the console. After this text is written, the method of the base class is invoked using the base keyword (code file VirtualMethods/ConcreteShapes.cs):

public class Rectangle: Shape
{
  public override void Move(Position newPosition)
  {
    Console.Write("Rectangle ");
    base.Move(newPosition);
  }
  //…
}

Now move the rectangle to a new position (code file VirtualMethods/Program.cs):

r1.Move(new Position { X = 120, Y = 40 });

Run the application to see output that is a result of the Move method in the Rectangle and the Shape classes:

Rectangle moves to X: 120, Y: 40

Abstract Classes and Methods

C# allows both classes and methods to be declared as abstract. An abstract class cannot be instantiated, whereas an abstract method does not have an implementation and must be overridden in any nonabstract derived class. Obviously, an abstract method is automatically virtual. If any class contains any abstract methods, that class is also abstract and must be declared as such.

Let's change the Shape class to be abstract. Instead of throwing a NotImplementedException, the Clone method is now declared abstract, and thus it can't have any implementation in the Shape class (code file AbstractClasses/Shape.cs):

public abstract class Shape
{
  public abstract Shape Clone(); // abstract method
} 

When deriving a type from the abstract base class that itself is not abstract, it's a concrete type. With a concreate class it is necessary to implement all abstract members. Otherwise, the compiler complains (code file AbstractClasses/ConcreteShapes.cs):

public class Rectangle : Shape
{
  //…
  public override Rectangle Clone()
  {
    Rectangle r = new();
    r.Position.X = Position.X;
    r.Position.Y = Position.Y;
    r.Size.Width = Size.Width;
    r.Size.Height = Size.Width;
    return r;
  }
}

Using the abstract Shape class and the derived Ellipse class, you can declare a variable of a Shape. You cannot instantiate it, but you can instantiate an Ellipse and assign it to the Shape variable (code file AbstractClasses/Program.cs):

Shape s1 = new Ellipse();
s1.Draw();

Sealed Classes and Methods

If you don't want to allow other classes to derive from your class, your class should be sealed. Adding the sealed modifier to a class doesn't allow you to create a subclass of it. Sealing a method means it's not possible to override this method.

sealed class FinalClass
{
  //…
}
 
class DerivedClass: FinalClass // wrong. Cannot derive from sealed class.
{
  //…
}

The most likely situation in which you'll mark a class or method as sealed is if the class or method is internal to the operation of the library, class, or other classes that you are writing. Overriding methods could lead to instability of the code. When you seal the class, you make sure that overriding is not possible.

There's another reason to seal classes. With a sealed class, the compiler knows that derived classes are not possible, and thus the virtual table used for virtual methods can be reduced or eliminated, which can increase performance. The string class is sealed. I haven't seen a single application that doesn't use strings, so it's best to have this type as performant as possible. Making the class sealed is a good hint for the compiler.

Declaring a method as sealed serves a purpose similar to that for a class. The method can be an overridden method from a base class, but in the following example, the compiler knows another class cannot extend the virtual table for this method; it ends here.

class MyClass: MyBaseClass
{
  public sealed override void FinalMethod()
  {
    // implementation
  }
}
 
class DerivedClass: MyClass
{
  public override void FinalMethod() // wrong. Will give compilation error
  {
  }
}

To use the sealed keyword on a method or property, the member must have first been overridden from a base class. If you do not want a method or property in a base class overridden, then don't mark it as virtual.

Constructors of Derived Classes

Chapter 3 discusses how constructors can be applied to individual classes. An interesting question arises as to what happens when you start defining your own constructors for classes that are part of a hierarchy, inherited from other classes that may also have custom constructors.

In the sample application that uses shapes, so far, custom constructors have not been specified. The compiler creates a default constructor automatically to initialize all members to null or 0 (depending on whether the types are reference or value types) or uses the code from specified property initializers to add these to the default constructor. Now, let's change the implementation to create immutable types and define custom constructors to initialize their values. The Position, Size, and Shape classes are changed to specify read-only properties, and the constructors are changed to initialize the properties. The Shape class is still abstract, which doesn't allow creating instances of this type (code file InheritanceWithConstructors/Shape.cs):

public class Position
{
  public Position(int x, int y) => (X, Y) = (x, y);
 
  public int X { get; }
  public int Y { get; }
 
  public override string ToString() => $"X: {X}, Y: {Y}";
}
 
public class Size
{
  public Size(int width, int height) => (Width, Height) = (width, height);
 
  public int Width { get; }
  public int Height { get; }
 
  public override string ToString() => $"Width: {Width}, Height: {Height}";
}
 
public abstract class Shape
{
  public Shape(int x, int y, int width, int height)
  {
    Position = new Position(x, y);
    Size = new Size(width, height);
  }
 
  public Position Position { get; }
  public virtual Size Size { get; }
 
  public void Draw() => DisplayShape();
 
  protected virtual void DisplayShape()
  {
    Console.WriteLine($"Shape with {Position} and {Size}");
  }
 
  public abstract Shape Clone();
}

Now the Rectangle and Ellipse types need to be changed as well. Because the Shape class doesn't have a parameterless constructor, the compiler complains because it cannot automatically invoke the constructor of the base class. A custom constructor is required here as well.

With the new implementation of the Ellipse class, a constructor is defined to supply the position and size for the shape. To invoke the constructor from the base class, such as invoking methods of the base class, you use the base keyword, but you just can't use the base keyword in the block of the constructor body. Instead, you need to use the base keyword in the constructor initializer and pass the required arguments. The Clone method can now be simplified to invoke the constructor to create a new Ellipse object by forwarding the values from the existing object (code file InheritanceWithConstructors/ConcreteShapes.cs):

public class Ellipse : Shape
{
  public Ellipse(int x, int y, int width, int height)
    : base(x, y, width, height) { }
 
  protected override void DisplayShape()
  {
    Console.WriteLine($"Ellipse at position {Position} with size {Size}");
  }
 
  public override Ellipse Clone() => 
    new(Position.X, Position.Y, Size.Width, Size.Height);
}

Access Modifiers

Access modifiers indicate which other code items can access an item.

You can use all the access modifiers with members of a type. The public and internal access modifiers can also be applied to the type itself. With nested types (types that are specified within types), you can apply all access modifiers. In regard to access modifiers, nested types are members of the outer type, such as those shown in the following code snippet where the OuterType is declared with the public access modifier, and the type InnerType has the protected access modifier applied. With the protected access modifier, the InnerType can be accessed from the members of the OuterType, and all types that derive from the OuterType :

public class OuterType
{
  protected class InnerType
  {
    // members of the inner type
  }
  // more members of the outer type
}

The public access modifier is the most open one; everyone has access to a class or a member that has the public access modifier applied. The private access modifier is the most restrictive one. Members with this access modifier can be used only within the class where the modifier is used. The protected access modifier is in between these access restrictions. In addition to the private access modifier, it allows access to all types that derive from the type where the protected access modifier is used.

The internal access modifier is different. This access modifier has the scope of the assembly. All the types defined within the same assembly have access to members and types where the internal access modifier is used.

If you do not supply an access modifier with a type, by default internal access is specified. You can use this type only within the same assembly.

The protected internal access modifier is a combination of protected and internal —combining these access modifiers with OR. protected internal members can be used from any type in the same assembly or from types from another assembly if an inheritance relationship is used. With the intermediate language (IL) code, this is known as famorassem (family or assembly)—family for the protected C# keyword and assembly for the internal keyword. famandassem is also available with the IL code. Because of the demand for an AND combination, the C# team had some issues finding a good name for this, and finally it was decided to use private protected to restrict access from within the assembly to types that have an inheritance relationship but no types from any other assembly.

The following table lists all the access modifiers and their uses:

Other Modifiers

The modifiers in the following table can be applied to members of types and have various uses. A few of these modifiers also make sense when applied to types:

Predefined Interfaces

Let's take a look at some predefined interfaces and how they are used with .NET. Some C# keywords are even designed to work with particular predefined interfaces. The using statement and the using declaration (covered in detail in Chapter 13) use the IDisposable interface. This interface defines the method Dispose without any arguments and without return type. A class deriving from this interface needs to implement this Dispose method:

public IDisposable
{
  void Dispose();
}

The using statement uses this interface. You can use this statement with any class (here, the Resource class) implementing this interface:

using (Resource resource = new())
{
  // use the resource
}

The compiler converts the using statement to this code to invoke the Dispose method in the finally block of the try / finally statement:

Resource resource = new();
try
{
  // use the resource
}
finally
{
  resource.Dispose();
}

Another example where an interface is used with a language keyword is the foreach statement that's using the IEnumerator and IEnumerable interfaces. This code snippet

string[] names = { "James", "Jack", "Jochen" };
foreach (var name in names)
{
  Console.WriteLine(name);
}

is converted to access the GetEnumerator method of the IEnumerable interface and uses a while loop to access the MoveNext method and the Current property of the IEnumerator interface:

string[] names = { "James", "Jack", "Jochen" };
var enumerator = names.GetEnumerator();
while (enumerator.MoveNext())
{
  var name = enumerator.Current;
  Console.WriteLine(name);
}

Let's look at an example where an interface is used from a .NET class, and you can easily implement this interface. The interface IComparable<T> defines the CompareTo method to sort objects of the type you need to specify with the generic parameter T. This interface is used by various classes in .NET to order objects of any type:

public interface IComparable<in T>
{
  int CompareTo(T? other);
}

With the following code snippet, the record Person implements this interface specifying Person as a generic parameter. Person specifies the properties FirstName and LastName. The CompareTo method is defined to return 0 if both values (this and other) are the same, a value lower than 0 if this object should come before the other object, and a value greater than 0 if other should be first. Because the string type also implements IComparable, this implementation is used to compare the LastName properties. If the comparison on the last name returns 0, a comparison is done on the FirstName property as well (code file UsingInterfaces/Person.cs):

public record Person(string FirstName, string LastName) : IComparable<Person>
{
  public int CompareTo(Person? other)
  {
    int compare = LastName.CompareTo(other?.LastName);
    if (compare is 0)
    {
      return FirstName.CompareTo(other?.FirstName);
    }
    return compare;
  }
}

With the top-level statements in Program.cs, three Person records are created within an array, and the array's Sort method is used to sort the elements in the array (code file UsingInterfaces/Program.cs):

Person p1 = new("Jackie", "Stewart");
Person p2 = new("Graham", "Hill");
Person p3 = new("Damon", "Hill");
 
Person[] people = { p1, p2, p3 };
Array.Sort(people);
foreach (var p in people)
{
  Console.WriteLine(p);
}

Running the application shows the ToString output of the record type in a sorted order:

Person { FirstName = Damon, LastName = Hill }
Person { FirstName = Graham, LastName = Hill }
Person { FirstName = Jackie, LastName = Stewart }

Interfaces can act as a contract. The record Person implements the IComparable contract that is used by the Sort method of the Array class. The Array class just needs to know the contract definition (the members of the interface) to know what it can use.

Dependency Injection with Interfaces

Let's create a custom interface. With the shapes sample, the Shape and Rectangle types used the Console.WriteLine method to write a message to the console:

protected virtual void DisplayShape()
{
  Console.WriteLine($"Shape with {Position} and {Size}");
}

This way, the method DisplayShape has a strong dependency on the Console class. To make this implementation independent of the Console class and to write to either the console or a file, you can define a contract such as the ILogger interface in the following code snippet. This interface specifies the Log method where a string can be passed as an argument (code file UsingInterfaces/ILogger.cs):

public interface ILogger
{
  void Log(string message);
}

A new version of the Shape class uses constructor injection where the interface is injected into an object of this class. In the constructor, the object passed with the parameter is assigned to the read-only property Logger. With the implementation of the DisplayShape method, the property of type ILogger is used to write a message (code file UsingInterfaces/Shape.cs):

public abstract class Shape
{
  public Shape(ILogger logger)
  {
    Logger = logger;
  }
 
  protected ILogger Logger { get; }
  public Position? Position { get; init; }
  public Size? Size { get; init; }
 
  public void Draw() => DisplayShape();
 
  protected virtual void DisplayShape()
  {
    Logger.Log($"Shape with {Position} and {Size}");
  }
}

With a concrete implementation of the abstract Shape class, in the constructor, the ILogger interface is forwarded to the constructor of the base class. With the DisplayShape method, the protected property Logger is used from the base class (code file UsingInterfaces/ConcreteShapes.cs):

public class Ellipse : Shape
{
  public Ellipse(ILogger logger) : base(logger) { }
 
  protected override void DisplayShape()
  {
    Logger.Log($"Ellipse at position {Position} with size {Size}");
  }
}

Next, a concrete implementation of the ILogger interface is required. One way you can implement writing a message to the console is with the ConsoleLogger class. This class implements the ILogger interface to write a message to the console (code file UsingInterfaces/ConsoleLogger.cs):

public class ConsoleLogger : ILogger
{
  public void Log(string message) => Console.WriteLine(message);    
}

For creating a Rectangle, the ConsoleLogger can be created on passing an instance to implement the ILogger interface (code file UsingInterfaces/Program.cs):

Ellipse e1 = new(new ConsoleLogger()) 
{ 
  Position = new(20, 30), 
  Size = new(100, 120) 
};
r1.Draw();

Explicit and Implicit Implemented Interfaces

Interfaces can be explicitly or implicitly implemented. With the example so far, you've seen implicitly implemented interfaces, such as with the ConsoleLogger class:

public class ConsoleLogger : ILogger
{
  public void Log(string message) => Console.WriteLine(message);    
}

With an explicit interface implementation, the member implemented doesn't have an access modifier and has the interface prefixed to the method name:

public class ConsoleLogger : ILogger
{
  void ILogger.Log(string message) => Console.WriteLine(message);
}

With an explicit interface implementation, the interface is not accessible when you use a variable of type ConsoleLogger (it's not public). If you use a variable of the interface type (ILogger), you can invoke the Log method; the contract of the interface is fulfilled. You can also cast the ConsoleLogger variable to the interface ILogger to invoke this method.

Why would you want to do this? One reason is to resolve a conflict. If different interfaces define the same method signature, your class needs to implement all these interfaces, and the implementations need to differ, you can use explicit interface implementation.

Another reason to use explicit interface implementation is to hide the interface method from code outside of the class but still fulfill the contract from the interface. An example is the StringCollection class from the System.Collections.Specialized namespace and the IList interface. One of the members that's defined by the IList interface is the Add method:

int Add(object? value);

The StringCollection class is optimized for strings and thus prefers to use the string type with the Add method:

public int Add(string? value);

The version to pass an object is hidden from the StringCollection class because the StringCollection class has an explicit interface implementation with this method. To use this type directly, you just pass a string parameter. If a method uses IList as a parameter, then you can use any object that implements IList for that parameter. In particular, you can use a StringCollection for the parameter because that class still implements that interface.

Comparing Interfaces and Classes

Now that you've seen the foundations of interfaces, let's compare interfaces, classes, records, and structs with regard to object orientation:

• You can declare a variable of the type of all these C# constructs. You can declare a variable of a class, an interface, a record, or a struct.
• You can instantiate a new object with classes, records, and structs. You cannot instantiate a new object with an abstract class or an interface.
• With a class, you can derive from a base class. With a record, you can derive from a base record. Both with classes and records, implementation inheritance is supported. Structs don't support inheritance.
• Classes, records, and structs can implement multiple interfaces. Implementing interfaces is not possible with ref structs.

Default Interface Methods

Before C# 8, changing an interface was always a breaking change. Even just adding a member to an interface is a breaking change. The type implementing this interface needs to implement this new interface member. Because of this, many .NET libraries are built with abstract base classes. When you add a new member to an abstract base class, if it's not an abstract member, it is not a breaking change. With Microsoft's Component Object Model (COM), which is based on interfaces, always a new interface was defined when a breaking change was introduced—for example, IViewObject, IViewObjectEx, IViewObject2, IViewObject3.

As of C# 8, interfaces can have implementations. However, you need to be aware where you can use this feature. C# 8 is supported by .NET Core 3.x. With older technologies, you can change the compiler version at your own risk. To support default interface members, a runtime change is required. This runtime change is available only with .NET Core 3.x+ and .NET Standard 2.1+. You cannot use default interface members with .NET Framework applications or UWP applications without .NET 5 support.

public interface ILogger
{
  void Log(string message);
}

public interface ILogger
{
  void Log(string message);
  public void Log(Exception ex) => Log(ex.Message);
}

ILogger logger = new ConsoleLogger();
logger.Log("message");
logger.Log(new Exception("sample exception"));

public class ConsoleLogger : ILogger
{
  public void Log(string message) => Console.WriteLine(message);
 
  void ILogger.Log(Exception ex)
  {
    Console.WriteLine(
      $"exception type: {ex.GetType().Name}, message: {ex.Message}");
  }
}

using System;
using System.Collections.Generic;
 
public interface IEnumerableEx<T> : IEnumerable<T>
{
  public IEnumerable<T> Where(Func<T, bool> pred)
  {
    foreach (T item in this)
    {
      if (pred(item))
      {
        yield return item;
      }
    }
  }
}

class MyCollection<T> : Collection<T>, IEnumerableEx<T>
{
}

IEnumerableEx<string> names = new MyCollection<string> 
  { "James", "Jack", "Jochen", "Sebastian", "Lewis", "Juan" };
 
var jNames = names.Where(n => n.StartsWith("J"));
foreach (var name in jNames)
{
  Console.WriteLine(name);
}

Constraints

With the previous implementation of the LinkedListNode<T> and LinkedList<T> types there was not a special requirement on the generic type; any type can be used. This prevents you from using any nonobject members with the implementation. The compiler doesn't accept invoking any property or method on the generic type T.

Adding the DisplayAllTitles method to the LinkedList<T> class results in a compiler error. T does not contain a definition for Title, and no accessible extension method Title accepting a first argument of type T could be found (code file GenericTypesWithConstraints/LinkedList.cs):

  public void DisplayAllTitles()
  {
    foreach (T item in this)
    {
      Console.WriteLine(item.Title);
    }
  }

To resolve this, the interface ITitle is specified that defines a Title property that needs to be implemented with the implementation of this interface:

public interface ITitle
{
  string Title { get; }
}

Defining the generic LinkedList<T>, now the constraint for the generic type T, can be specified to implement the interface ITitle. Constraints are specified with the where keyword followed by the requirement on the type:

public class LinkedList<T> : IEnumerable<T>
    where T : ITitle
{
  //…
}

With this change in place, the DisplayAllTitles method compiles. This method uses the members specified by the ITitle interface, and this is a requirement on the generic type. You can no longer use int and string for the generic type parameter, but the Person record can be changed to implement this constraint (code file GenericTypesWithConstraints/Program.cs):

public record Person(string FirstName, string LastName, string Title) 
  : ITitle { }

The following table lists the constraints you can specify with a generic:

Compound Assignment Operators

Compound assignment operators are a shortcut to using the assignment operator with another operator. Instead of writing x = x + 2, you can use the compound assignment x += 2. Incrementing by 1 is required even more often, so there's another shortcut, x++ :

int x = 1;
int x += 2; // shortcut for int x = x + 2;
x++; // shortcut for x = x + 1;

Shortcuts can be used with all the other compound assignment operators. A new compound assignment operator has been available since C# 8: the null-coalescing compound assignment operator. This operator is discussed later in this chapter.

You may be wondering why there are two examples for the ++ increment operator. Placing the operator before the expression is known as a prefix; placing the operator after the expression is known as a postfix. Note that there is a difference in the way they behave.

The increment and decrement operators can act both as entire expressions and within expressions. When used by themselves, the effect of both the prefix and postfix versions is identical and corresponds to the statement x = x + 1. When used within larger expressions, the prefix operator increments the value of x before the expression is evaluated; in other words, x is incremented, and the new value is used as the result of the expression. Conversely, the postfix operator increments the value of x after the expression is evaluated. The result of the expression returns the original value of x. The following example uses the increment operator (++) as an example to demonstrate the difference between the prefix and postfix behavior (code file OperatorsSample/Program.cs):

void PrefixAndPostfix()
{
  int x = 5;
  if (++x == 6) // true – x is incremented to 6 before the evaluation
  {
    Console.WriteLine("This will execute");
  }
  if (x++ == 6) // true – x is incremented to 7 after the evaluation
  {
    Console.WriteLine("The value of x is: {x}"); // x has the value 7
  }
}

The following sections look at some of the commonly used and new operators that you will frequently use within your C# code.

The Conditional-Expression Operator (?:)

The conditional-expression operator (?:), also known as the ternary operator, is a shorthand form of the if…else construction. It gets its name from the fact that it involves three operands. It allows you to evaluate a condition, returning one value if that condition is true or another value if it is false. The syntax is as follows:

condition ? true_value: false_value

Here, condition is the Boolean expression to be evaluated, true _ value is the value that is returned if condition is true, and false _ value is the value that is returned otherwise.

When used sparingly, the conditional-expression operator can add a dash of terseness to your programs. It is especially handy for providing one of a couple of arguments to a function that is being invoked. You can use it to quickly convert a Boolean value to a string value of true or false. It is also handy for displaying the correct singular or plural form of a word (code file OperatorsSample/Program.cs):

int x = 1;
string s = x + " ";
s += (x == 1 ? "man": "men");
Console.WriteLine(s);

This code displays 1 man if x is equal to one but displays the correct plural form for any other number. Note, however, that if your output needs to be localized to different languages, you have to write more sophisticated routines to take into account the different grammatical rules of different languages. Read Chapter 22, “Localization,” for globalizing and localizing .NET applications.

The checked and unchecked Operators

Consider the following code:

byte b = byte.MaxValue;
b++;
Console.WriteLine(b);

The byte data type can hold values only in the range 0 to 255. Assigning byte.MaxValue to a byte results in 255. With 255, all bits of the 8 available bits in the byte are set: 11111111. Incrementing this value by one causes an overflow and results in 0.

To get exceptions in such cases, C# provides the checked and unchecked operators. If you mark a block of code as checked, the CLR enforces overflow checking, throwing an OverflowException if an overflow occurs. The following changes the preceding code to include the checked operator (code file OperatorsSample/Program.cs):

byte b = 255;
checked
{
  b++;
}
Console.WriteLine(b);

Instead of writing a checked block, you also can use the checked keyword in an expression:

b = checked(b + 3);

When you try to run this code, the OverflowException is thrown.

You can enforce overflow checking for all unmarked code by adding the CheckForOverflowUnderflow setting in the csproj file:

<PropertyGroup>
  <OutputType>Exe</OutputType>
  <TargetFramework>net5.0</TargetFramework>
  <Nullable>enable</Nullable>
  <CheckForOverflowUnderflow>true</CheckForOverflowUnderflow>
</PropertyGroup>

With a project setting to be configured for overflow checking, you can mark code that should not be checked using the unchecked operator.

The is and as Operators

You can use the is and as operators to determine whether an object is compatible with a specific type. This is useful with class hierarchies.

Let's assume a simple class hierarchy. The class DerivedClass derives from the class BaseClass. You can assign a variable of type DerivedClass to a variable of type BaseClass ; all the members of the BaseClass are available with the DerivedClass. In the following example, an implicit conversion is taking place:

BaseClass = new();
DerivedClass = new();
baseClass = derivedClass; 

If you have a parameter of the BaseClass and want to assign it to a variable of the DerivedClass, implicit conversion is not possible. To the SomeAction method, an instance of the BaseClass or any type that derives from this class can be passed. This will not necessarily succeed. Here, you can use the as operator. The as operator either returns a DerivedClass instance (if the variable is of this type) or returns null :

public void SomeAction(BaseClass baseClass)
{
  DerivedClass? derivedClass = baseClass as DerivedClass;
  if (derivedClass != null)
  {
    // use the derivedClass variable
  } 
}

Instead of using the as operator, you can use the is operator. The is operator returns true if the conversion succeeds; otherwise, it returns false. With the is operator, a variable can be specified that is assigned if the is operator returns true:

public void SomeAction(BaseClass baseClass)
{
  if (baseClass is DerivedClass derivedClass)
  {
    // use the derivedClass variable
  }
}

The sizeof Operator

You can determine the size (in bytes) required on the stack by a value type using the sizeof operator (code file OperatorsSample/Program.cs):

Console.WriteLine(sizeof(int));

This displays the number 4 because an int is 4 bytes long.

You can also use the sizeof operator with structs if the struct contains only value types—for example, the Point class as shown here (code file OperatorsSample/Point.cs):

public readonly struct Point
{
  public Point(int x, int y) => (X, Y) = (x, y);
 
  public int X { get; }
  public int Y { get; }
}

When you use sizeof with custom types, you need to write the code within an unsafe code block (code file OperatorsSample/Program.cs):

unsafe
{
  Console.WriteLine(sizeof(Point));
}
 

The typeof Operator

The typeof operator returns a System.Type object representing a specified type. For example, typeof(string) returns a Type object representing the System.String type. This is useful when you want to use reflection to find information about an object dynamically. For more information, see Chapter 12, “Reflection, Metadata, and Source Generators.”

The nameof Expression

The nameof operator is of practical use when strings are needed as parameters that are already known at compile time. This operator accepts a symbol, property, or method and returns the name.

One use example is when the name of a variable is needed, as in checking a parameter for null, as shown here:

public void Method(object o)
{
  if (o == null) throw new ArgumentNullException(nameof(o)); 
}

Of course, it would be similar to throw the exception by passing a string instead of using the nameof operator. However, using nameof prevents you from misspelling the parameter name when you pass it to the exception's constructor. Also, when you change the name of the parameter, you can easily miss changing the string passed to the ArgumentNullException constructor. Refactoring features also help changing all occurrences where nameof is used:

if (o == null) throw new ArgumentNullException("o");

Using the nameof operator for the name of a variable is just one use case. You can also use it to get the name of a property—for example, for firing a change event (using the interface INotifyPropertyChanged) in a property set accessor and passing the name of a property.

public string FirstName
{
  get => _firstName;
  set
  {
    _firstName = value;
    OnPropertyChanged(nameof(FirstName));
  }
}

The nameof operator can also be used to get the name of a method. This also works if the method is overloaded because all overloads result in the same value: the name of the method.

public void Method()
{
  Log($"{nameof(Method)} called");

The Indexer

You use the indexer (brackets) for accessing arrays in Chapter 6. In the following code snippet, the indexer is used to access the third element of the array named arr1 by passing the number 2:

int[] arr1 = {1, 2, 3, 4};
int x = arr1[2]; // x == 3 

Similarly to accessing elements of an array, the indexer is implemented with collection classes (discussed in Chapter 8, “Collections”).

The indexer doesn't require an integer within the brackets. Indexers can be defined with any type. The following code snippet creates a generic dictionary where the key is a string and the value an int. With dictionaries, the key can be used with the indexer. In the following sample, the string first is passed to the indexer to set this element in the dictionary, and then the same string is passed to the indexer to retrieve this element:

Dictionary<string, int> dict = new();
dict["first"] = 1;
int x = dict["first"];

The Null-Coalescing and Null-Coalescing Assignment Operators

The null-coalescing operator (??) provides a shorthand mechanism to cater to the possibility of null values when working with nullable and reference types. The operator is placed between two operands—the first operand must be a nullable type or reference type, and the second operand must be of the same type as the first or of a type that is implicitly convertible to the type of the first operand. The null-coalescing operator evaluates as follows:

• If the first operand is not null, then the overall expression has the value of the first operand.
• If the first operand is null, then the overall expression has the value of the second operand.

Here's an example:

int? a = null;
int b;
b = a ?? 10; // b has the value 10
a = 3;
b = a ?? 10; // b has the value 3

If the second operand cannot be implicitly converted to the type of the first operand, a compile-time error is generated.

The null-coalescing operator is not only important with nullable types but also with reference types. In the following code snippet, the property Val returns the value of the _val variable only if it is not null. In case it is null, a new instance of MyClass is created, assigned to the _val variable, and finally returned from the property. This second part of the expression within the get accessor only happens when the variable _val is null:

private MyClass _val;
public MyClass Val
{
  get => _val ?? (_val = new MyClass());
}

Using the null-coalescing assignment operator, the preceding code can now be simplified to create a new MyClass and assign it to _val if _val is null :

private MyClass _val;
public MyClass Val
{
  get => _val ??= new MyClass();
}

The Null-Conditional Operator

The null-conditional operator, is a feature of C# that reduces the number of code lines. A great number of code lines in production code verify null conditions. Before accessing members of a variable that is passed as a method parameter, the variable needs to be checked to determine whether it has a value of null. Otherwise, a NullReferenceException would be thrown. A .NET design guideline specifies that code should never throw exceptions of these types and should always check for null conditions. However, such checks could be missed easily. This code snippet verifies whether the passed parameter p is not null. In case it is null, the method just returns without continuing:

public void ShowPerson(Person? p)
{
  if (p is null) return;
  string firstName = p.FirstName;
  //…
}

Using the null-conditional operator to access the FirstName property (p?.FirstName), when p is null, only null is returned without continuing to the right side of the expression (code file OperatorsSample/Program.cs):

public void ShowPerson(Person? p)
{
  string firstName = p?.FirstName;
  //…
}

When a property of an int type is accessed using the null-conditional operator, the result cannot be directly assigned to an int type because the result can be null. One option to resolve this is to assign the result to a nullable int :

int? age = p?.Age;

Of course, you can also solve this issue by using the null-coalescing operator and defining another result (for example, 0) in case the result of the left side is null :

int age1 = p?.Age ?? 0;

You also can combine multiple null-conditional operators. In the following example, the Address property of a Person object is accessed, and this property in turn defines a City property. Null checks need to be done for the Person object and, if it is not null, also for the result of the Address property:

Person p = GetPerson();
string city = null;
if (p != null && p.HomeAddress != null)
{
  city = p.HomeAddress.City;
}

When you use the null-conditional operator, the code becomes much simpler:

string city = p?.HomeAddress?.City;

You can also use the null-conditional operator with arrays. With the following code snippet, a NullReferenceException is thrown using the index operator to access an element of an array variable that is null :

int[] arr = null;
int x1 = arr[0];

Of course, traditional null checks could be done to avoid this exceptional condition. A simpler version uses ?[0] to access the first element of the array. In case the result is null, the null-coalescing operator returns the value 0 for the x1 variable:

int x1 = arr?[0] ?? 0;

Shifting Bits

As you've already seen in the previous sample, shifting three bits to the left is a multiplication by 8. A shift by one bit is a multiplication by 2. This is a lot faster than invoking the multiply operator—in case you need to multiply by 2, 4, 8, 16, 32, and so on.

The following code snippet sets one bit in the variable s1, and in the for loop the bit always shifts by one bit (code file BinaryCalculations/Program.cs):

void ShiftingBits()
{
  Console.WriteLine(nameof(ShiftingBits));
  ushort s1 = 0b01;
  Console.WriteLine($"{"Binary",16} {"Decimal",8} {"Hex",6}");
  for (int i = 0; i < 16; i++)
  { 
    Console.WriteLine($"{s1.ToBinaryString(),16} {s1,8} hex: {s1,6:X}");
    s1 = (ushort)(s1 << 1);
  }
  Console.WriteLine();
}

In the program output, you can see binary, decimal, and hexadecimal values with the loop:

          Binary  Decimal    Hex
0000000000000001        1      1
0000000000000010        2      2
0000000000000100        4      4
0000000000001000        8      8
0000000000010000       16     10
0000000000100000       32     20
0000000001000000       64     40
0000000010000000      128     80
0000000100000000      256    100
0000001000000000      512    200
0000010000000000     1024    400
0000100000000000     2048    800
0001000000000000     4096   1000
0010000000000000     8192   2000
0100000000000000    16384   4000
1000000000000000    32768   8000

Signed and Unsigned Numbers

One important thing to remember when working with binary numbers is that when using signed types, such as int, long, and short, the leftmost bit is used to represent the sign. When you use an int, the highest number available is 2147483647 —the positive number of 31 bits or 0x7FFF_FFFF. With a uint, the highest number available is 4294967295 or 0xFFFF_FFFF. This represents the positive number of 32 bits. With the int, the other half of the number range is used for negative numbers.

To understand how negative numbers are represented, the following code snippet initializes the maxNumber variable to the highest positive number that fits into 15 bits using short.MaxValue. Then, in a for loop, the variable is incremented three times. In the results, binary, decimal, and hexadecimal values are shown (code file BinaryCalculations/Program.cs):

void SignedNumbers()
{
  Console.WriteLine(nameof(SignedNumbers));
 
  void DisplayNumber(string title, short x) =>
    Console.WriteLine($"{title,-11} " +
      $"bin: {x.ToBinaryString().AddSeparators()}, " +     
      $"dec: {x,6}, hex: {x,4:X}");
 
  short maxNumber = short.MaxValue;
  DisplayNumber("max short", maxNumber);
  for (int i = 0; i < 3; i++)
  {
    maxNumber++;
    DisplayNumber($"added {i + 1}", maxNumber);
  }
  Console.WriteLine();
  //…
}

With the output of the application, you can see all the bits—except the sign bit—are set to achieve the maximum integer value. The output shows the same value in different formats—binary, decimal, and hexadecimal. Adding 1 to the first output results in an overflow of the short type setting the sign bit, and all other bits are 0. This is the highest negative value for the int type. After this result, two more increments are done:

max short    bin: 0111_1111_1111_1111, dec:  32767, hex: 7FFF
added 1      bin: 1000_0000_0000_0000, dec: -32768, hex: 8000
added 2      bin: 1000_0000_0000_0001, dec: -32767, hex: 8001
added 3      bin: 1000_0000_0000_0010, dec: -32766, hex: 8002

With the next code snippet, the variable zero is initialized to 0. In the for loop, this variable is decremented three times:

short zero = 0;
DisplayNumber("zero", zero);
for (int i = 0; i < 3; i++)
{
  zero--;
  DisplayNumber($"subtracted {i + 1}", zero);
}
Console.WriteLine();

With the output, you can see 0 is represented with all the bits not set. Doing a decrement results in decimal -1, which is all the bits set, including the sign bit:

zero         bin: 0000_0000_0000_0000, dec:      0, hex:    0
subtracted 1 bin: 1111_1111_1111_1111, dec:     -1, hex: FFFF
subtracted 2 bin: 1111_1111_1111_1110, dec:     -2, hex: FFFE
subtracted 3 bin: 1111_1111_1111_1101, dec:     -3, hex: FFFD

Next, start with the largest negative number for a short. The number is incremented three times:

short minNumber = short.MinValue;
DisplayNumber("min number", minNumber);
for (int i = 0; i < 3; i++)
{
  minNumber++;
  DisplayNumber($"added {i + 1}", minNumber);
}
Console.WriteLine();

The highest negative number was already shown earlier when overflowing the highest positive number. Earlier you saw this same number when int.MinValue was used. This number is then incremented three times:

min number   bin: 1000_0000_0000_0000, dec: -32768, hex: 8000
added 1      bin: 1000_0000_0000_0001, dec: -32767, hex: 8001
added 2      bin: 1000_0000_0000_0010, dec: -32766, hex: 8002
added 3      bin: 1000_0000_0000_0011, dec: -32765, hex: 8003

Type Conversions

Often, you need to convert data from one type to another. Consider the following code:

byte value1 = 10;
byte value2 = 23;
byte total = value1 + value2;
Console.WriteLine(total);

When you attempt to compile these lines, you get the following error message:

Cannot implicitly convert type 'int' to 'byte'

The problem here is that when you add 2 bytes together, the result is returned as an int, not another byte. This is because a byte can contain only 8 bits of data, so adding 2 bytes together could easily result in a value that cannot be stored in a single byte. If you want to store this result in a byte variable, you have to convert it back to a byte. The following sections discuss two conversion mechanisms supported by C#—implicit and explicit.

byte value1 = 10;
byte value2 = 23;
long total = value1 + value2; // this will compile fine
Console.WriteLine(total);

long val = 30000;
int i = (int)val; // A valid cast. The maximum int is 2147483647

long val = 3000000000;
int i = (int)val; // An invalid cast. The maximum int is 2147483647

-1294967296

long val = 3000000000;
int i = checked((int)val);

double price = 25.30;
int approximatePrice = (int)(price + 0.5);

ushort c = 43;
char symbol = (char)c;
Console.WriteLine(symbol);

struct ItemDetails
{
  public string Description;
  public int ApproxPrice;
}
//…
double[] Prices = { 25.30, 26.20, 27.40, 30.00 };
ItemDetails id;
id.Description = "Hello there.";
id.ApproxPrice = (int)(Prices[0] + 0.5);

int? a = null;
int b = (int)a; // Will throw exception

int i = 10;
string s = i.ToString();

string s = "100";
int i = int.Parse(s);
Console.WriteLine(i + 50); // Add 50 to prove it is really an int

Boxing and Unboxing

Chapter 2 explains that all types—both the simple predefined types, such as int and char, and the complex types, such as classes and structs—derive from the object type. This means you can treat even literal values as though they are objects:

string s = 10.ToString();

However, you also saw that C# data types are divided into value types, which are allocated on the stack, and reference types, which are allocated on the managed heap. How does this work with the capability to call methods on an int, if the int is nothing more than a 4-byte value on the stack?

C# achieves this through a bit of magic called boxing. Boxing and its counterpart, unboxing, enable you to convert value types to reference types and then back to value types. I include this topic in the section on casting because this is essentially what you are doing—you are casting your value to the object type. Boxing is the term used to describe the transformation of a value type to a reference type. Basically, the runtime creates a temporary reference-type box for the object on the heap.

This conversion can occur implicitly, as in the preceding example, but you can also perform it explicitly:

int myIntNumber = 20;
object myObject = myIntNumber;

Unboxing is the term used to describe the reverse process, whereby the value of a previously boxed value type is cast back to a value type. Here, I use the term cast because this has to be done explicitly. The syntax is similar to explicit type conversions already described:

int myIntNumber = 20;
object myObject = myIntNumber; // Box the int
int mySecondNumber = (int)myObject; // Unbox it back into an int

A variable can be unboxed only if it has been boxed. If you execute the last line when myObject is not a boxed int, you get a runtime exception.

One word of warning: When unboxing, you have to be careful that the receiving value is of the same type as the value that was boxed. Even if the resulting type has enough room to store all the bytes in the value being unboxed, an InvalidCastException is thrown. You can avoid this by casting from the original type in the new type, as shown here:

int myIntNumber = 42;
object myObject = (object)myIntNumber;
long myLongNumber = (long)(int)myObject;

How Operators Work

To understand how to overload operators, it's useful to think about what happens when the compiler encounters an operator. Using the addition operator (+) as an example, suppose that the compiler processes the following lines of code:

int x = 1;
int y = 2;
long z = x + y;

The compiler identifies that it needs to add two integers and assign the result to a long. The expression x + y is just an intuitive and convenient syntax for calling a method that adds two numbers. The method takes two parameters, x and y, and returns their sum. Therefore, the compiler does the same thing it does for any method call: it looks for the best matching overload of the addition operator based on the parameter types—in this case, one that takes two integers. As with normal overloaded methods, the desired return type does not influence the compiler's choice as to which version of a method it calls. As it happens, the overload called in the example takes two int parameters and returns an int ; this return value is subsequently converted to a long. This can result in an overflow if the two added int values don't fit into an int although a long is declared to write the result to.

The next lines cause the compiler to use a different overload of the addition operator:

double d1 = 4.0;
double d2 = d1 + x;

In this instance, the parameters are a double and an int, but there is no overload of the addition operator that takes this combination of parameters. Instead, the compiler identifies the best matching overload of the addition operator as being the version that takes two double s as its parameters, and it implicitly casts the int to a double. Adding two double s requires a different process from adding two integers. Floating-point numbers are stored as a mantissa and an exponent. Adding them involves bit-shifting the mantissa of one of the double s so that the two exponents have the same value, adding the mantissas, and then shifting the mantissa of the result and adjusting its exponent to maintain the highest possible accuracy in the answer.

Now you are in a position to see what happens if the compiler finds something like this:

Vector vect1, vect2, vect3;
// initialize vect1 and vect2
vect3 = vect1 + vect2;
vect1 = vect1 * 2;

Here, Vector is the struct, which is defined in the following section. The compiler sees that it needs to add two Vector instances, vect1 and vect2, together. It looks for an overload of the addition operator, which takes two Vector instances as its parameters.

If the compiler finds an appropriate overload, it calls up the implementation of that operator. If it cannot find one, it checks whether there is any other overload for + that it can use as a best match—perhaps something with two parameters of other data types that can be implicitly converted to Vector instances. If the compiler cannot find a suitable overload, it raises a compilation error, just as it would if it could not find an appropriate overload for any other method call.

Operator Overloading with the Vector Type

This section demonstrates operator overloading through developing a struct named Vector that represents a three-dimensional vector. The 3D vector is just a set of three numbers (doubles) that tell you how far something is moving. The variables representing the numbers are called X, Y, and Z : the X tells you how far something moves east, Y tells you how far it moves north, and Z tells you how far it moves upward. Combine the three numbers and you get the total movement.

You can add or multiply vectors by other vectors or by numbers. Incidentally, in this context, we use the term scalar, which is math-speak for a simple number—in C# terms that is just a double. The significance of addition should be clear. If you move first by the vector (3.0, 3.0, 1.0) and then move by the vector (2.0, -4.0, -4.0), the total amount you have moved can be determined by adding the two vectors. Adding vectors means adding each component individually, so you get (5.0, -1.0, -3.0). In this context, mathematicians write c=a+b, where a and b are the vectors and c is the resulting vector. You want to be able to use the Vector struct the same way.

The following is the definition for Vector —containing the read-only public fields, constructors, and a ToString override so you can easily view the contents of a Vector. Operator overloads are added next (code file OperatorOverloadingSample/Vector.cs):

readonly struct Vector
{
  public Vector(double x, double y, double z) => (X, Y, Z) = (x, y, z);
 
  public Vector(Vector v) => (X, Y, Z) = (v.X, v.Y, v.Z);
 
  public readonly double X;
  public readonly double Y;
  public readonly double Z;
  public override string ToString() => $"( {X}, {Y}, {Z} )";
}

This example has two constructors that require specifying the initial value of the vector, either by passing in the values of each component or by supplying another Vector whose value can be copied. Constructors like the second one, which takes a single Vector argument, are often termed copy constructors because they effectively enable you to initialize a class or struct instance by copying another instance.

Here is the interesting part of the Vector struct—the operator overload that provides support for the addition operator:

public static Vector operator +(Vector left, Vector right) =>
  new Vector(left.X + right.X, left.Y + right.Y, left.Z + right.Z); 

The operator overload is declared in much the same way as a static method, except that the operator keyword tells the compiler it is actually an operator overload you are defining. The operator keyword is followed by the actual symbol for the relevant operator, in this case the addition operator (+). The return type is whatever type you get when you use this operator. Adding two vectors results in a vector; therefore, the return type is also a Vector. For this particular override of the addition operator, the return type is the same as the containing class, but that is not necessarily the case, as you see later in this example. The two parameters are the things you are operating on. For binary operators (those that take two parameters), such as the addition and subtraction operators, the first parameter is the value on the left of the operator, and the second parameter is the value on the right.

The implementation of this operator returns a new Vector that is initialized using the X, Y, and Z fields from the left and right variables.

C# requires that all operator overloads be declared as public and static, which means they are associated with their class or struct, not with a particular instance. Because of this, the body of the operator overload has no access to nonstatic class members or the this identifier. This is fine because the parameters provide all the input data the operator needs to know to perform its task.

Now all you need to do is write some simple code to test the Vector struct (code file OperatorOverloadingSample/Program.cs):

Vector vect1, vect2, vect3;
vect1 = new(3.0, 3.0, 1.0);
vect2 = new(2.0, -4.0, -4.0);
vect3 = vect1 + vect2;
Console.WriteLine($"vect1 = {vect1}");
Console.WriteLine($"vect2 = {vect2}");
Console.WriteLine($"vect3 = {vect3}");

Compiling and running this code returns the following result:

vect1 = ( 3, 3, 1 )
vect2 = ( 2, -4, -4 )
vect3 = ( 5, -1, -3 )

Just by implementing the + operator, you can use the compound assignment operator +=. Let's add vect2 to the existing value of vect3 :

vect3 += vect2;
Console.WriteLine($"vect3 = {vect3}");

This compiles and runs, resulting in the following:

vect3 = ( 7, -5, -7)

In addition to adding vectors, you can multiply and subtract them and compare their values. These operators can be implemented in the same way as the + operator. What might be more interesting is multiplying a vector by a double. With the following three operator overloads, a vector is multiplied by a vector, a vector is multiplied by a double, and a double is multiplied by a vector. You need to implement the different operators depending what's on the left and right sides, but you can reuse implementations. The operator overload where the vector is on the left and the double on the right just reuses the operator overload where the arguments are changed (code file OperatorOverloadingSample/Vector.cs):

public static Vector operator *(Vector left, Vector right) =>
  new Vector(left.X * right.X, left.Y * right.Y, left.Z * right.Z);
 
public static Vector operator *(double left, Vector right) =>
  new Vector(left * right.X, left * right.Y, left * right.Z);
 
public static Vector operator *(Vector left, double right) =>
  right * left;

The operators are used in the following code snippet. The int number used is converted to a double because this is the best match for the overload:

Console.WriteLine($"2 * vect3 = {2 * vect3}");
Console.WriteLine($"vect3 += vect2 gives {vect3 += vect2}");
Console.WriteLine($"vect3 = vect1 * 2 gives {vect3 = vect1 * 2}");
Console.WriteLine($"vect1 * vect3 = {vect1 * vect3}");

Implementing User-Defined Casts

This section illustrates the use of implicit and explicit user-defined casts in an example called CastingSample. In this example, you define a struct, Currency, which holds a positive USD ($) monetary value. C# provides the decimal type for this purpose, but it is possible you still will want to write your own struct or class to represent monetary values if you need to perform sophisticated financial processing and therefore want to implement specific methods on such a class.

Initially, the definition of the Currency struct is as follows (code file CastingSample/Currency.cs):

public readonly struct Currency
{
  public readonly uint Dollars;
  public readonly ushort Cents;
 
  public Currency(uint dollars, ushort cents) => (Dollars, Cents) = (dollars, cents);
 
  public override string ToString() => $"${Dollars}.{Cents,-2:00}";
}

The use of unsigned data types for the Dollar and Cents fields ensures that a Currency instance can hold only positive values. It is restricted this way to illustrate some points about explicit casts later. You might want to use a type like this to hold, for example, salary information for company employees (people's salaries tend not to be negative!).

Start by assuming that you want to be able to convert Currency instances to float values, where the integer part of the float represents the dollars. In other words, you want to be able to write code like this:

Currency balance = new(10, 50);
float f = balance; // We want f to be set to 10.5

To be able to do this, you need to define a cast. Hence, you add the following to your Currency definition:

public static implicit operator float (Currency value) =>
  value.Dollars + (value.Cents/100.0f);

The preceding cast is implicit. It is a sensible choice in this case because, as it should be clear from the definition of Currency, any value that can be stored in the Currency can also be stored in a float. There is no way that anything should ever go wrong in this cast.

However, if you have a float that you would like to be converted to a Currency, the conversion is not guaranteed to work. A float can store negative values, whereas Currency instances can't, and a float can store numbers of a far higher magnitude than can be stored in the (uint) Dollar field of Currency. Therefore, if a float contains an inappropriate value, converting it to a Currency could give unpredictable results. Because of this risk, the conversion from float to Currency should be defined as explicit. Here is the first attempt, which does not return quite the correct results, but it is instructive to examine why:

public static explicit operator Currency (float value)
{
  uint dollars = (uint)value;
  ushort cents = (ushort)((value-dollars)*100);
  return new Currency(dollars, cents);
}

The following code now successfully compiles:

float amount = 45.63f;
Currency amount2 = (Currency)amount;

However, the following code, if you tried it, would generate a compilation error because it attempts to use an explicit cast implicitly:

float amount = 45.63f;
Currency amount2 = amount; // wrong

By making the cast explicit, you warn the developer to be careful because data loss might occur. However, as you will soon see, this is not how you want your Currency struct to behave. Try writing a test harness and running the sample. Here is the Main method, which instantiates a Currency struct and attempts a few conversions. At the start of this code, you write out the value of balance in two different ways—this is needed to illustrate something later in the example (code file CastingSample/Program.cs):

  try
  {
    Currency balance = new(50,35);
    Console.WriteLine(balance);
    Console.WriteLine($"balance is {balance}"); // implicitly invokes ToString
    float balance2 = balance;
    Console.WriteLine($"After converting to float, = {balance2}");
    balance = (Currency) balance2;
    Console.WriteLine($"After converting back to Currency, = {balance}");
    Console.WriteLine("Now attempt to convert out of range value of " +
      "-$50.50 to a Currency:");
 
    checked
    {
      balance = (Currency) (-50.50);
      Console.WriteLine($"Result is {balance}");
    }
  }
  catch(Exception e)
  {
    Console.WriteLine($"Exception occurred: {e.Message}");
  }

Notice that the entire code is placed in a try block to catch any exceptions that occur during your casts. In addition, the lines that test converting an out-of-range value to Currency are placed in a checked block in an attempt to trap negative values. Running this code produces the following output:

50.35
Balance is $50.35
After converting to float, = 50.35
After converting back to Currency, = $50.34
Now attempt to convert out of range value of -$50.50 to a Currency:
Result is $4294967246.00

This output shows that the code did not quite work as expected. First, converting back from float to Currency gave a wrong result of $50.34 instead of $50.35. Second, no exception was generated when you tried to convert an obviously out-of-range value.

The first problem is caused by rounding errors. If a cast is used to convert from a float to a uint, the computer truncates the number rather than rounds it. The computer stores numbers in binary rather than decimal, and the fraction 0.35 cannot be exactly represented as a binary fraction (just as 1∕3 cannot be represented exactly as a decimal fraction; it comes out as 0.3333 recurring). The computer ends up storing a value very slightly lower than 0.35 that can be represented exactly in binary format. Multiply by 100, and you get a number fractionally less than 35, which is truncated to 34 cents. Clearly, in this situation, such errors caused by truncation are serious, and the way to avoid them is to ensure that some intelligent rounding is performed in numerical conversions.

Luckily, Microsoft has written a class that does this: System.Convert. The System.Convert object contains a large number of static methods to perform various numerical conversions, and the one that we want is Convert.ToUInt16. Note that the extra care taken by the System.Convert methods comes at a performance cost. You should use them only when necessary.

Let's examine the second problem—why the expected overflow exception wasn't thrown. The issue here is that the place where the overflow really occurs isn't actually in the Main routine at all—it is inside the code for the cast operator, which is called from the Main method. The code in this method was not marked as checked.

The solution is to ensure that the cast itself is computed in a checked context, too. With both this change and the fix for the first problem, the revised code for the conversion looks like the following:

public static explicit operator Currency (float value)
{
  checked
  {
    uint dollars = (uint)value;
    ushort cents = Convert.ToUInt16((value-dollars)*100);
    return new Currency(dollars, cents);
  }
}

Note that you use Convert.ToUInt16 to calculate the cents, as described earlier, but you do not use it for calculating the dollar part of the amount. System.Convert is not needed when calculating the dollar amount because truncating the float value is what you want there.

You won't look at the new results with this new checked cast just yet because you have some more modifications to make to the CastingSample example later in this section.

Casts Between Classes

The Currency example involves only classes that convert to or from float —one of the predefined data types. However, it is not necessary to involve any of the simple data types. It is perfectly legitimate to define casts to convert between instances of different structs or classes that you have defined. You need to be aware of a couple of restrictions, however:

• You cannot define a cast if one of the classes is derived from the other (these types of casts already exist, as you will see later).
• The cast must be defined inside the definition of either the source or the destination data type.

To illustrate these requirements, suppose that you have the class hierarchy shown in Figure 5-1.

In other words, classes C and D are indirectly derived from A. In this case, the only legitimate user-defined cast between A, B, C, or D would be to convert between classes C and D, because these classes are not derived from each other. The code for this might look like the following (assuming you want the casts to be explicit, which is usually the case when defining casts between user-defined classes):

public static explicit operator D(C value)
{
  //…
}
 
public static explicit operator C(D value)
{
  //…
}

For each of these casts, you can choose where you place the definitions—inside the class definition of C or inside the class definition of D, but not anywhere else. C# requires you to put the definition of a cast inside either the source class (or struct) or the destination class (or struct). A side effect of this is that you cannot define a cast between two classes unless you have access to edit the source code for at least one of them. This is sensible because it prevents third parties from introducing casts into your classes.

After you have defined a cast inside one of the classes, you cannot also define the same cast inside the other class. Obviously, there should be only one cast for each conversion; otherwise, the compiler would not know which one to use.

MyDerived derivedObject = new MyDerived();
MyBase baseCopy = derivedObject;

MyBase derivedObject = new MyDerived();
MyBase baseObject = new MyBase();
MyDerived derivedCopy1 = (MyDerived) derivedObject; // OK
MyDerived derivedCopy2 = (MyDerived) baseObject; // Throws exception

class DerivedClass: BaseClass
{
  public DerivedClass(BaseClass base)
  {
    // initialize object from the Base instance
  }
  // …

Currency balance = new(40,0);
object baseCopy = balance;

object derivedObject = new Currency(40,0);
object baseObject = new object();
Currency derivedCopy1 = (Currency)derivedObject; // OK
Currency derivedCopy2 = (Currency)baseObject; // Exception thrown

Multiple Casting

One thing you have to watch for when you are defining casts is that if the C# compiler is presented with a situation in which no direct cast is available to perform a requested conversion, it attempts to find a way of combining casts to do the conversion. For example, with the Currency struct, suppose the compiler encounters a few lines of code like this:

Currency balance = new(10,50);
long amount = (long)balance;
double amountD = balance;

You first initialize a Currency instance, and then you attempt to convert it to a long. The trouble is that you haven't defined the cast to do that. However, this code still compiles successfully. Here's what happens: the compiler realizes that you have defined an implicit cast to get from Currency to float, and the compiler already knows how to explicitly cast a float to a long. Hence, it compiles that line of code into IL code that converts balance first to a float and then converts that result to a long. The same thing happens in the final line of the code, when you convert balance to a double. However, because the cast from Currency to float and the predefined cast from float to double are both implicit, you can write this conversion in your code as an implicit cast. If you prefer, you could also specify the casting route explicitly:

Currency balance = new(10,50);
long amount = (long)(float)balance;
double amountD = (double)(float)balance;

However, in most cases, this would be seen as needlessly complicating your code. The following code, by contrast, produces a compilation error:

Currency balance = new(10,50);
long amount = balance;

The reason is that the best match for the conversion that the compiler can find is still to convert first to float and then to long. The conversion from float to long needs to be specified explicitly, though.

Not all of this by itself should give you too much trouble. The rules are, after all, fairly intuitive and designed to prevent any data loss from occurring without the developer knowing about it. However, the problem is that if you are not careful when you define your casts, it is possible for the compiler to select a path that leads to unexpected results. For example, suppose that it occurs to someone else in the group writing the Currency struct that it would be useful to be able to convert a uint containing the total number of cents in an amount into a Currency (cents, not dollars, because the idea is not to lose the fractions of a dollar). Therefore, this cast might be written to try to achieve this:

// Do not do this!
public static implicit operator Currency(uint value) =>
  new Currency(value/100u, (ushort)(value%100));

Note the u after the first 100 in this code ensures that value/100u is interpreted as a uint. If you had written value/100, the compiler would have interpreted this as an int, not a uint.

The comment Do not do this! is clearly noted in this code, and here is why: the following code snippet merely converts a uint containing 350 into a Currency and back again; but what do you think bal2 will contain after executing this?

uint bal = 350;
Currency balance = bal;
uint bal2 = (uint)balance;

The answer is not 350 but 3 ! Moreover, it all follows logically. You convert 350 implicitly to a Currency, giving the result balance.Dollars = 3, balance.Cents = 50. Then the compiler does its usual figuring out of the best path for the conversion back. Balance ends up being implicitly converted to a float (value 3.5), and this is converted explicitly to a uint with value 3. One way to fix this would be to create a user-defined cast to uint.

Of course, other instances exist in which converting to another data type and back again causes data loss. For example, converting a float containing 5.8 to an int and back to a float again loses the fractional part, giving you a result of 5, but there is a slight difference in principle between losing the fractional part of a number and dividing an integer by more than 100. Currency has suddenly become a rather dangerous class that does strange things to integers!

The problem is that there is a conflict between how your casts interpret integers. The casts between Currency and float interpret an integer value of 1 as corresponding to one dollar, but the latest uint -to- Currency cast interprets this value as one cent. This is an example of poor design. If you want your classes to be easy to use, you should ensure that all your casts behave in ways that are mutually compatible, in the sense that they intuitively give the same results. In this case, the solution is obviously to rewrite the uint -to- Currency cast so that it interprets an integer value of 1 as one dollar:

public static implicit operator Currency (uint value) =>
  new Currency(value, 0);

Incidentally, you might wonder whether this new cast is necessary at all. The answer is that it could be useful. Without this cast, the only way for the compiler to carry out a uint -to- Currency conversion would be via a float. Converting directly is a lot more efficient in this case, so having this extra cast provides performance benefits, though you need to ensure that it provides the same result as via a float, which you have now done. In other situations, you may also find that separately defining casts for different predefined data types enables more conversions to be implicit rather than explicit, though that is not the case here.

A good test of whether your casts are compatible is to ask whether a conversion will give the same results (other than perhaps a loss of accuracy as in float -to- int conversions) regardless of which path it takes. The Currency class provides a good example of this. Consider this code:

Currency balance = new(50, 35);
ulong bal = (ulong) balance;

At present, there is only one way that the compiler can achieve this conversion: by converting the Currency to a float implicitly and then to a ulong explicitly. The float -to- ulong conversion requires an explicit conversion, but that is fine because you have specified one here.

Suppose, however, that you then added another cast to convert implicitly from a Currency to a uint. You actually do this by modifying the Currency struct by adding the casts both to and from uint (code file CastingSample/Currency.cs):

public static implicit operator Currency(uint value) => 
  new Currency(value, 0);
public static implicit operator uint(Currency value) => value.Dollars;

Now the compiler has another possible route to convert from Currency to ulong : to convert from Currency to uint implicitly and then to ulong implicitly. Which of these two routes will it take? C# has some precise rules about the best route for the compiler when there are several possibilities. (The rules are not covered in this book, but if you are interested in the details, see the MSDN documentation.) The best answer is that you should design your casts so that all routes give the same answer (other than possible loss of precision), in which case it doesn't really matter which one the compiler picks. (As it happens in this case, the compiler picks the Currency -to- uint -to- ulong route in preference to Currency -to- float -to- ulong.)

To test casting the Currency to uint, add this test code to the Main method (code file UserDefinedConversion/Program.cs):

try
{
  Currency balance = new(50,35);
  Console.WriteLine(balance);
  Console.WriteLine($"balance is {balance}");
  uint balance3 = (uint) balance;
  Console.WriteLine($"Converting to uint gives {balance3}");
}
catch (Exception ex)
{
  Console.WriteLine($"Exception occurred: {ex.Message}");
}