Getting code solutions for this book

The GitHub repository for this book has solutions using full application projects for all code tasks and exercises, found at the following link:https://github.com/markjprice/cs12dotnet8After navigating to the GitHub repository in your web browser, press the . (dot) key on your keyboard, or manually change .com to .dev in the link to convert the repository into a live code editor based on Visual Studio Code using GitHub Codespaces, as shown in Figure 1.1:

We provide you with a PDF file that has color images of the screenshots and diagrams used in this book. You can download this file from https://static.packt-cdn.com/downloads/???_ColorImages.pdf.

Visual Studio Code in a web browser is great to run alongside your chosen local code editor as you work through the book's coding tasks. You can compare your code to the solution code and easily copy and paste parts if needed.

You do not need to use or know anything about Git to get the solution code of this book. You can download a ZIP file containing all the code solutions by using the following direct link and then extract the ZIP file into your local filesystem: https://github.com/markjprice/cs12dotnet8/archive/refs/heads/main.zip.

.NET terms used in this book

Throughout this book, I use the term modern .NET to refer to .NET 8 and its predecessors like .NET 6 that derive from .NET Core. I use the term legacy .NET to refer to .NET Framework, Mono, Xamarin, and .NET Standard. Modern .NET is a unification of those legacy platforms and standards.

The structure and style of this book

After this first chapter, the book can be divided into three parts: language, libraries, and web development.First, the grammar and vocabulary of the C# language; second, the types available in the .NET libraries for building app features; and third, the fundamentals of cross-platform websites, services, and browser apps that you can build using C# and .NET.Most people learn complex topics best by imitation and repetition rather than reading a detailed explanation of the theory; therefore, I will not overload you with detailed explanations of every step throughout this book. The idea is to get you to write some code and see it run.You don't need to know all the nitty-gritty details immediately. That will be something that comes with time as you build your own apps and go beyond what any book can teach you.In the words of Samuel Johnson, author of the English dictionary in 1755, I have committed "a few wild blunders, and risible absurdities, from which no work of such multiplicity is free." I take sole responsibility for these and hope you appreciate the challenge of my attempt to lash the wind by writing this book about rapidly evolving technologies like C# and .NET, and the apps that you can build with them.

If you have a complaint about this book, then please contact me before writing a negative review on Amazon. Authors cannot respond to Amazon reviews so I cannot contact you to resolve the problem and help you or listen to your feedback and try to do better in the next edition. Please ask a question on the Discord channel for this book at https://packt.link/cs12dotnet8, email me at markjprice@gmail.com, or raise an issue in the GitHub repository for the book at the following link: https://github.com/markjprice/cs12dotnet8/issues.

Topics covered by this book

The following topics are covered in this book:

• Language fundamentals: Fundamental features of the C# language, from declaring variables to writing functions and object-oriented programming.
• Library fundamentals: Fundamental features of the .NET base class library as well as some important optional packages for common tasks like database access.
• Web development fundamentals: Fundamental features of the ASP.NET Core framework for server-side and client-side website and web service development.

Topics covered by Apps and Services with .NET 8

The following topics are available in a companion book, Apps and Services with .NET 8:

• Data: SQL Server, Azure Cosmos DB.
• Specialized libraries: Dates, times, time zones, and internationalization; common third-party libraries for image handling, logging, mapping, and generating PDFs; multitasking and concurrency; and many more.
• Services: Caching, queuing, background services, gRPC, GraphQL, Azure Functions, SignalR, and Minimal APIs.
• User Interfaces: ASP.NET Core, Blazor, and .NET MAUI.

This book, C# 12 and .NET 8 – Modern Cross-Platform Development Fundamentals, is best read linearly, chapter by chapter, because it builds up fundamental skills and knowledge. The companion book, Apps and Services with .NET 8, can be read more like a cookbook, so if you are especially interested in building gRPC services, then you could read that chapter without the preceding chapters about Minimal API services. To see a list of all books I have published with Packt, you can use the following link:https://subscription.packtpub.com/search?query=mark+j.+priceA similar list is available on Amazon:https://www.amazon.com/Mark-J-Price/e/B071DW3QGN/You can search other book-selling sites for my books too.

Choosing the appropriate tool and application type for learning

What is the best tool and application type for learning C# and .NET?When learning, the best tool is one that helps you write code and configuration but does not hide what is really happening. IDEs provide graphical user interfaces that are friendly to use, but what are they doing for you underneath? A more basic code editor that is closer to the action while providing help to write your code can be better while you are learning.Having said that, you can make the argument that the best tool is the one you are already familiar with or that you or your team will use as your daily development tool. For that reason, I want you to be free to choose any C# code editor or IDE to complete the coding tasks in this book, including Visual Studio Code, Visual Studio 2022, or even JetBrains Rider.In this book, I give detailed step-by-step instructions in Chapter 1 for how to create multiple projects in both Visual Studio 2022 for Windows and Visual Studio Code. There are also links to online instructions for other code editors, as shown at the following link: https://github.com/markjprice/cs12dotnet8/blob/main/docs/code-editors/README.md.In subsequent chapters, I will only give the names of projects along with general instructions so you can use whichever tool you prefer. The best application type for learning the C# language constructs and many of the .NET libraries is one that does not distract with unnecessary application code. For example, there is no need to create an entire Windows desktop application or a website just to learn how to write a switch statement.For that reason, I believe the best method for learning the C# and .NET topics in Chapters 1 to 11 is to build console apps. Then, in Chapters 12 to 16, you will build websites, services, and web browser apps.

Deploying cross-platform

Your choice of code editor and operating system for development does not limit where your code gets deployed..NET 8 supports the following platforms for deployment:

• Windows: Windows 10 version 1607 or later. Windows 11 version 22000 or later. Windows Server 2012 R2 SP1 or later. Nano Server version 1809 or later.
• Mac: macOS Catalina version 10.15 or later and in the Rosetta 2 x64 emulator.
• Linux: Alpine Linux 3.17 or later. Debian 11 or later. Fedora 37 or later. openSUSE 15 or later. Oracle Linux 8 or later. RHEL 8 or later. SUSE Enterprise Linux 12 SP2 or later. Ubuntu 20.04 or later.
• Android: API 21 or later.
• iOS and tvOS: 11.0 or later.
• MacCatalyst: 10.15 or later. 11.0 or later on Arm64.

Warning! .NET support for Windows 7 and 8.1 ended in January 2023: https://github.com/dotnet/core/issues/7556.

Windows Arm64 support in .NET 5 and later means you can develop on, and deploy to, Windows Arm devices like Microsoft's Windows Dev Kit 2023 (formerly known as Project Volterra) and Surface Pro X.

You can review the latest supported operating systems and versions at the following link: https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md.

Downloading and installing Visual Studio 2022

Many professional .NET developers use Visual Studio 2022 for Windows in their day-to-day development work. Even if you choose to use Visual Studio Code to complete the coding tasks in this book, you might want to familiarize yourself with Visual Studio 2022 for Windows too. It is not until you have written a decent amount of code with a tool that you can really judge if it fits your needs.If you do not have a Windows computer, then you can skip this section and continue to the next section where you will download and install Visual Studio Code on macOS or Linux.Since October 2014, Microsoft has made a professional-quality edition of Visual Studio available to students, open-source contributors, and individuals for free. It is called Community Edition. Any of the editions are suitable for this book. If you have not already installed it, let's do so now:

1. Download Microsoft Visual Studio 2022 version 17.8 or later for Windows from the following link: https://visualstudio.microsoft.com/downloads/.
2. Run the installer to start the installation.
3. On the Workloads tab, select the following:
   • ASP.NET and web development.
   • .NET desktop development (because this includes console apps).
   • Desktop development with C++ with all default components (because this enables publishing console apps and web services that start faster and have smaller memory footprints).
4. Click Install and wait for the installer to acquire the selected software and install it.
5. When the installation is complete, click Launch.
6. The first time that you run Visual Studio, you will be prompted to sign in. If you have a Microsoft account, you can use that account. If you don't, then register for a new one at the following link: https://signup.live.com/.
7. The first time that you run Visual Studio, you will be prompted to configure your environment. For Development Settings, choose Visual C#. For the color theme, I chose Blue, but you can choose whatever tickles your fancy.
8. If you want to customize your keyboard shortcuts, navigate to Tools | Options…, and then select the Keyboard section.

Downloading and installing Visual Studio Code

Visual Studio Code has rapidly improved over the past couple of years and has pleasantly surprised Microsoft with its popularity. If you are brave and like to live on the bleeding edge, then there is the Insiders edition, which is a daily build of the next version.Even if you plan to only use Visual Studio 2022 for Windows for development, I recommend that you download and install Visual Studio Code and try the coding tasks in this chapter using it, and then decide if you want to stick with just using Visual Studio 2022 for the rest of the book.Let's now download and install Visual Studio Code, the .NET SDK, and the C# Dev Kit extension:

1. Download and install either the Stable build or the Insiders edition of Visual Studio Code from the following link: https://code.visualstudio.com/.

   More Information: If you need more help installing Visual Studio Code, you can read the official setup guide at the following link: https://code.visualstudio.com/docs/setup/setup-overview.

2. Download and install the .NET SDKs for version 8.0 and at least one other version like 6.0 or 7.0 from the following link: https://www.microsoft.com/net/download.

   In real life, you are extremely unlikely to only have one .NET SDK version installed on your computer. To learn how to control which .NET SDK version is used to build a project, we need multiple versions installed. .NET 6, .NET 7, and .NET 8 are supported versions at the time of publishing in November 2023. You can safely install multiple SDKs side by side. The most recent SDK will be used to build your projects.

3. To install the C# Dev Kit extension with a user interface, you must first launch the Visual Studio Code application.
4. In Visual Studio Code, click the Extensions icon or navigate to View | Extensions.

5. C# Dev Kit is one of the most popular extensions available, so you should see it at the top of the list, and you can enter C# in the search box.

   C# Dev Kit has a dependency on the C# extension version 2.0 or later, so you do not have to install the C# extension separately. Note that C# extension version 2.0 or later no longer uses OmniSharp since it has a new Language Service Protocol (LSP) host. C# Dev Kit also has dependencies on the .NET Install Tool for Extension Authors and IntelliCode for C# Dev Kit extensions so they will be installed too.

6. Click Install and wait for supporting packages to download and install.

Good Practice: Be sure to read the license agreement for the C# Dev Kit. It has a more restrictive license than the C# extension: https://aka.ms/vs/csdevkit/license.

code --install-extension ms-dotnettools.csdevkit

Understanding .NET support

.NET versions are either Long Term Support (LTS), Standard Term Support (STS) (formerly known as Current), or Preview, as described in the following list:

• LTS releases are a good choice for applications that you do not intend to update frequently, although you must update the .NET runtime for your production code monthly. LTS releases are supported by Microsoft for 3 years after General Availability (GA), or 1 year after the next LTS release ships, whichever is longer.
• STS releases include features that may change based on feedback. These are a good choice for applications that you are actively developing because they provide access to the latest improvements. STS releases are supported by Microsoft for 18 months after GA, or 6 months after the next STS or LTS release ships, whichever is longer.
• Preview releases are for public testing. These are a good choice for adventurous programmers who want to live on the bleeding edge, or programming book authors who need to have early access to new language features, libraries, and app and service platforms. Preview releases are not usually supported by Microsoft, but some preview or Release Candidate (RC) releases may be declared Go Live, meaning they are supported by Microsoft in production.

STS and LTS releases receive critical patches throughout their lifetime for security and reliability.

Good Practice: You must stay up to date with the latest patches to get support. For example, if a system is running on .NET runtime version 8.0.0 and then version 8.0.1 is released, you must install version 8.0.1 to get support. These updates are released on the second Tuesday of each month, aka Patch Tuesday.

To better understand your choices of STS and LTS releases, it is helpful to see it visually, with 3-year-long black bars for LTS releases, and 1½-year-long gray bars for STS releases, as shown in Figure 1.2:

During the lifetime of .NET 8, two older versions will reach end-of-life and two new versions will be released. I have tried to be cognizant that you might choose to use .NET 9 or .NET 10 with this book, although, obviously, the book cannot cover new features of those future versions!

End of support or end-of-life (EOL) means the date after which bug fixes, security updates, or technical assistance are no longer available from Microsoft.

If you need long-term support from Microsoft, then choose .NET 8 today and stick with it even after .NET 9 releases in 2024. This is because .NET 9 will be an STS release, and it will therefore lose support in May 2026, before .NET 8 does in November 2026. As soon as .NET 10 is released, start upgrading your .NET 8 projects to it. You will have a year to do so before .NET 8 reaches its end-of-life.

Good Practice: Remember that with all releases, you must upgrade to bug-fix releases like .NET runtime 8.0.1 and .NET SDK 8.0.101, which are expected to release in December 2023, because updates are released every month.

At the time of publishing in November 2023, all versions of modern .NET have reached their end of life except those shown in the following list that are ordered by their end-of-life dates:

• .NET 7 will reach end-of-life on May 14, 2024.
• .NET 6 will reach end-of-life on November 12, 2024.
• .NET 8 will reach end-of-life on November 10, 2026.

You can check which .NET versions are currently supported and when they will reach end-of-life at the following link: https://github.com/dotnet/core/blob/main/releases.md.

Understanding .NET support phases

The lifetime of a version of .NET passes through several phases, during which they have varying levels of support, as described in the following list:

• Preview: Not supported. .NET 8 Preview 1 to Preview 7 were in this support phase from February 2023 to August 2023.
• Go Live: Supported until GA, then becomes immediately unsupported so you must upgrade to the final release version as soon as it is available. .NET 8 Release Candidate 1 and Release Candidate 2 were in this support phase in September and October 2023.
• Active: .NET 8 will be in this support phase from November 2023 to May 2026.
• Maintenance: Supported only with security fixes for the last six months of its lifetime. .NET 8 will be in this support phase from May 2026 to November 2026.
• End-of-life: Not supported. .NET 8 will reach its end-of-life in November 2026.

Understanding .NET Runtime and .NET SDK versions

If you have not built a standalone app, then the .NET Runtime is the minimum needed to install so that an operating system can run a .NET application. The .NET SDK includes the .NET Runtime as well as the compilers and other tools needed to build .NET code and apps..NET Runtime versioning follows semantic versioning, that is, a major increment indicates breaking changes, minor increments indicate new features, and patch increments indicate bug fixes..NET SDK versioning does not follow semantic versioning. The major and minor version numbers are tied to the runtime version it is matched with. The patch number follows a convention that indicates the major and minor versions of the SDK.You can see an example of this in Table 1.3:

Table 1.3: Examples of changes and versions for a .NET runtime and SDK

Listing and removing versions of .NET

.NET Runtime updates are compatible with a major version such as 8.x, and updated releases of the .NET SDK maintain the ability to build applications that target previous versions of the runtime, which enables the safe removal of older versions.You can see which SDKs and runtimes are currently installed using the following commands:

dotnet --list-sdks
dotnet --list-runtimes
dotnet --info

Good Practice: To make it easier to enter commands at the command prompt or terminal, the following link lists all commands throughout the book as a single statement that can be easily copied and pasted: https://github.com/markjprice/cs12dotnet8/blob/main/docs/command-lines.md.

On Windows, use the Apps & features section to remove .NET SDKs.On Linux, there is no single mechanism, but you can learn more at the following link:https://learn.microsoft.com/en-us/dotnet/core/install/remove-runtime-sdk-versions?pivots=os-linux

You could use a third-party tool like Dots, the friendly .NET SDK manager, found at the following link: https://johnnys.news/2023/01/Dots-a-dotnet-SDK-manager. At the time of writing, you must build the app from source on its GitHub repository, so I only recommend that for advanced developers.

Understanding intermediate language

The C# compiler (named Roslyn) used by the dotnet CLI tool converts your C# source code into intermediate language (IL) code and stores the IL in an assembly (a DLL or EXE file). IL code statements are like assembly language instructions, which are executed by .NET's virtual machine, known as CoreCLR.At runtime, CoreCLR loads the IL code from the assembly, the just-in-time (JIT) compiler compiles it into native CPU instructions, and then it is executed by the CPU on your machine.The benefit of this two-step compilation process is that Microsoft can create Common Language Runtimes (CLRs) for Linux and macOS, as well as for Windows. The same IL code runs everywhere because of the second compilation step, which generates code for the native operating system and CPU instruction set.Regardless of which language the source code is written in, for example, C#, Visual Basic, or F#, all .NET applications use IL code for their instructions stored in an assembly. Microsoft and others provide disassembler tools that can open an assembly and reveal this IL code, such as the ILSpy .NET Decompiler extension. You will learn more about this in Chapter 7, Packaging and Distributing .NET Types.

Comparing .NET technologies

We can summarize and compare .NET technologies today, as shown in Table 1.4:

Table 1.4: Comparison of .NET technologies

Managing multiple projects using code editors

Visual Studio 2022 for Windows, JetBrains Rider, and even Visual Studio Code (with the C# Dev Kit extension installed) all have a concept called a solution that allows you to open and manage multiple projects simultaneously. We will use a solution to manage the two projects that you will create in this chapter.

Writing code using Visual Studio 2022

Let's get started writing code:

1. Start Visual Studio 2022. You must have installed version 17.8 or later to see the new Welcome tab that replaces the old modal dialog box.

2. In the Welcome tab, click New Project, as shown in Figure 1.3:

   

3. In the Create a new project dialog, select the C# language to filter the project templates, and then enter console in the Search for templates box, and select Console App, making sure that you have chosen the cross-platform project template, not the one for .NET Framework, which is Windows-only, and the C# project template rather than another language, such as Visual Basic or TypeScript, so that it is selected as shown in Figure 1.4:

   

4. Click Next.

5. In the Configure your new project dialog, enter HelloCS for the project name, enter C:\cs12dotnet8 for the location, and enter Chapter01 for the solution name.

   More screenshots of Visual Studio 2022 when creating new projects can be found in the GitHub repository at the following link: https://github.com/markjprice/cs12dotnet8/blob/main/docs/ch01-project-options.md.

6. Click Next.

7. In the Additional information dialog, in the Framework drop-down list, note that your .NET SDK choices indicate if that version is Standard Term Support, Long Term Support, Preview, or Out of support, and then select .NET 8.0 (Long Term Support).

   You can install as many .NET SDK versions as you like. If you are missing a .NET SDK version, then you can install it from the following link: https://dotnet.microsoft.com/en-us/download/dotnet.

8. Leave the check box labeled Do not use top-level statements cleared. (Later in this chapter, you will create a console app that selects this option so you can see the difference.)
9. Leave the check box labeled Enable native AOT publish cleared. You will learn what this option does in Chapter 7, Packaging and Distributing .NET Types.
10. Click Create.
11. If you cannot see the Solution Explorer, then navigate to View | Solution Explorer.

12. If code is not shown, then in Solution Explorer, double-click the file named Program.cs to open it, and note that Solution Explorer shows the HelloCS project, as shown in Figure 1.5:

    

13. In Program.cs, note the code consists of only a comment and a single statement, as shown in the following code:

// See https://aka.ms/new-console-template for more information
Console.WriteLine("Hello, World!");

This template uses the top-level program feature introduced in C# 9, which I will explain later in this chapter. As the comment in the code says, you can read more about this template at the following link: https://aka.ms/new-console-template.

1. In Program.cs, modify line 2 so that the text that is being written to the console says Hello, C#!

All code examples and commands that the reader must review or type are shown in plain text so you will never have to read code or commands from a screenshot like in Figure 1.5, which might be too small or too faint in print.

Compiling and running code using Visual Studio

The next task is to compile and run the code:

1. In Visual Studio, navigate to Debug | Start Without Debugging.

   Good Practice: When you start a project in Visual Studio 2022, you can choose to attach a debugger or not. If you do not need to debug, then it is better not to attach one because attaching a debugger requires more resources and slows everything down. Attaching a debugger also limits you to only starting one project. If you want to run more than one project, each with a debugger attached, then you must start multiple instances of Visual Studio. In the toolbar, click the green outline triangle button (to the right of HelloCS in Figure 1.5) to start without debugging instead of the green solid triangle button (to the left of HelloCS in Figure 1.5), unless you need to debug.

2. The output in the console window will show the result of running your application, as shown in Figure 1.6:

   

3. Press any key to close the console app window and return to Visual Studio.
4. Optionally, close the Properties pane to make more vertical space for Solution Explorer.
5. Double-click the HelloCS project and note the HelloCS.csproj project file shows that this project has its target framework set to net8.0, as shown in Figure 1.7.
6. In the Solution Explorer toolbar, toggle on the Show All Files button , and note that the compiler-generated bin and obj folders are visible, as shown in Figure 1.7:

Understanding the compiler-generated folders and files

Two compiler-generated folders were created, named obj and bin, as described in the following list:

• The obj folder contains one compiled object file for each source code file. These objects haven't been linked together into a final executable yet.
• The bin folder contains the binary executable for the application or class library. We will look at this in more detail in Chapter 7, Packaging and Distributing .NET Types.

You do not need to look inside these folders or understand their files yet (but feel free to browse around if you are curious). Just be aware that the compiler needs to create temporary folders and files to do its work. You could delete these folders and their files, and they will be automatically recreated the next time you "build" or run the project. Developers often delete these temporary folders and files to "clean" a project. Visual Studio even has a command on the Build menu named Clean Solution that deletes some of these temporary files for you. The equivalent command with Visual Studio Code is dotnet clean.

Understanding top-level programs

If you have seen older .NET projects before, then you might have expected more code, even just to output a simple message. This project has minimal statements because some of the required code is written for you by the compiler when you target .NET 6 or later. If you had created the project with .NET SDK 5 or earlier, or if you had selected the check box labeled Do not use top-level statements, then the Program.cs file would have more statements, as shown in the following code:

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

During compilation with .NET SDK 6 or later, all the boilerplate code to define the Program class and its Main method is generated and wrapped around the statements you write.This uses a feature introduced in .NET 5 called top-level programs, but it was not until .NET 6 that Microsoft updated the project template for console apps to use top-level statements by default. Then in .NET 7 or later, Microsoft added options to use the older style if you prefer:

• If you are using Visual Studio 2022, select the check box labeled Do not use top-level statements.
• If you are using the dotnet CLI at the command prompt, add a switch:

dotnet new console --use-program-main

Warning! One functional difference is that the auto-generated code does not define a namespace, so the Program class is implicitly defined in an empty namespace with no name instead of a namespace that matches the name of the project.

Requirements for top-level programs

Key points to remember about top-level programs include the following:

• There can be only one file like this in a project.
• Any using statements must be at the top of the file.
• If you declare any classes or other types, they must be at the bottom of the file.
• Although you should name the method Main if you explicitly define it, the method is named <Main>$ when created by the compiler.

Implicitly imported namespaces

The using System; statement at the top of the file imports the System namespace. This enables the Console.WriteLine statement to work. Why do we not have to import it in our project? The trick is that we do still need to import the System namespace, but it is now done for us using a combination of features introduced in C# 10 and .NET 6. Let's see how:

1. In Solution Explorer, expand the obj folder, expand the Debug folder, expand the net8.0 folder, and open the file named HelloCS.GlobalUsings.g.cs.
2. Note that this file is automatically created by the compiler for projects that target .NET 6 or later, and that it uses a feature introduced in C# 10 called global namespace imports, which imports some commonly used namespaces like System for use in all code files, as shown in the following code:

// <autogenerated />
global using global::System;
global using global::System.Collections.Generic;
global using global::System.IO;
global using global::System.Linq;
global using global::System.Net.Http;
global using global::System.Threading;
global using global::System.Threading.Tasks;

1. In Solution Explorer, click the Show All Files button to hide the bin and obj folders.

I will explain more about the implicit imports feature in the next chapter. For now, just note that a significant change that happened between .NET 5 and .NET 6 is that many of the project templates, like the one for console apps, use new SDK and language features to hide what is really happening.

Revealing the hidden code by throwing an exception

Now let's discover how the hidden code has been written:

1. In Program.cs, after the statement that outputs the message, add a statement to throw a new exception, as shown in the following code:

throw new Exception();

1. In Visual Studio, navigate to Debug | Start Without Debugging. (Do not start the project with debugging or the exception will be caught by the debugger!)

2. The output in the console window will show the result of running your application, including that a hidden Program class was defined by the compiler with a method named <Main>$ that has a parameter named args for passing in arguments, as shown in Figure 1.8:

   

3. Press any key to close the console app window and return to Visual Studio.

Revealing the namespace for the Program class

Now, let's discover what namespace the Program class has been defined within:

1. In Program.cs, before the statement that throws an exception, add statements to get the name of the namespace of the Program class, and then write it to the console, as shown in the following code:

string name = typeof(Program).Namespace ?? "None!";
Console.WriteLine($"Namespace: {name}");

?? is the null-coalescing operator. The first statement means, "If the namespace of Program is null, then return None!; otherwise, return the name." You will see more explanations of these keywords and operators throughout the book. For now, just enter the code and run it to see what it does.

1. In Visual Studio, navigate to Debug | Start Without Debugging.
2. The output in the console window will show the result of running your application, including that the hidden Program class was defined without a namespace, as shown in the following output:

Namespace: None!

1. Press any key to close the console app window and return to Visual Studio.

Adding a second project using Visual Studio 2022

Let's add a second project to our solution to explore how to work with multiple projects:

1. In Visual Studio, navigate to File | Add | New Project….

   Warning! The above step adds a new project to the existing solution. Do NOT navigate to File | New | Project…, which instead is meant to be used to create a new project and solution (although the dialog box has a dropdown to choose to add to an existing solution too).

2. In the Add a new project dialog, in Recent project templates, select Console App [C#] and then click Next.
3. In the Configure your new project dialog, for Project name, enter AboutMyEnvironment, leave the location as C:\cs12dotnet8\Chapter01, and then click Next.

4. In the Additional information dialog, select .NET 8.0 (Long Term Support) and select the Do not use top-level statements check box.

   Warning! Make sure you have selected the Do not use top-level statements check box, so we get to see the older style of Program.cs.

5. Click Create.
6. In the AboutMyEnvironment project, in Program.cs, note the statements to define a namespace that matches the project name, an internal class named Program, and a static method named Main with a parameter named args that returns nothing (void), as shown in the following code:

namespace AboutMyEnvironment
{
  internal class Program
  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello, World!");
    }
  }
}

1. In Program.cs, in the Main method, replace the existing Console.WriteLine statement with statements to output the current directory, the version of the operating system, and the namespace of the Program class, as shown in the following code:

Console.WriteLine(Environment.CurrentDirectory);
Console.WriteLine(Environment.OSVersion.VersionString);
Console.WriteLine("Namespace: {0}", typeof(Program).Namespace);

1. In Solution Explorer, right-click the Chapter01 solution, and then select Configure Startup Projects….
2. In the Solution 'Chapter01' Property Pages dialog box, set Startup Project to Current selection, and then click OK.

3. In Solution Explorer, click the AboutMyEnvironment project (or any file or folder within it), and note that Visual Studio indicates that AboutMyEnvironment is now the startup project by making the project name bold.

   Good Practice: I recommend this way of setting the startup project because it then makes it very easy to switch startup projects by simply clicking a project (or any file in a project) to make it the startup project. Although you can right-click a project and set it as a startup project, if you then want to run a different project, you must manually change it again. Simply clicking anywhere in the project is easier. In most chapters, you will only need to run one project at a time. In Chapter 15, Building and Consuming Web Services, I will show you how to configure multiple startup projects.

4. Navigate to Debug | Start Without Debugging to run the AboutMyEnvironment project, and note the result, as shown in the following output and in Figure 1.9:

C:\cs12dotnet8\Chapter01\AboutMyEnvironment\bin\Debug\net8.0
Microsoft Windows NT 10.0.22621.0
Namespace: AboutMyEnvironment

Windows 11 is just branding. Its official name is Windows NT, and its major version number is still 10! But its patch version is 22000 or higher.

1. Press any key to close the console app window and return to Visual Studio.

When using Visual Studio 2022 for Windows to run a console app, it executes the app from the <projectname>\bin\Debug\net8.0 folder. It will be important to remember this when we work with the filesystem in later chapters. When using Visual Studio Code, or more accurately, the dotnet CLI, it has different behavior, as you are about to see.

Writing code using Visual Studio Code

Let's get started writing code!

1. Start your favorite tool for working with the filesystem, for example, File Explorer on Windows or Finder on Mac.
2. Navigate to your C: drive on Windows, your user folder on macOS or Linux (mine are named markjprice and home/markjprice), or any directory or drive in which you want to save your projects.
3. Create a new folder named cs12dotnet8. (If you completed the section for Visual Studio 2022, then this folder will already exist.)

4. In the cs12dotnet8 folder, create a new folder named Chapter01-vscode.

   If you did not complete the section for Visual Studio 2022, then you could name this folder Chapter01, but I will assume you will want to complete both sections and therefore need to use a non-conflicting name.

5. In the Chapter01-vscode folder, open the command prompt or terminal. For example, on Windows, right-click in the folder and then select Open in Terminal.
6. At the command prompt or terminal, use the dotnet CLI to create a new solution named Chapter01, as shown in the following command:

dotnet new sln --name Chapter01

You can use either -n or --name as the switch to specify a name. The default would match the name of the folder, for example, Chapter01-vscode.

1. Note the result, as shown in the following output:

The template "Solution File" was created successfully.

1. At the command prompt or terminal, use the dotnet CLI to create a new subfolder and project for a console app named HelloCS, as shown in the following command:

dotnet new console --output HelloCS

You can use either -o or --output as the switch to specify the folder and project name. The dotnet new console command targets your latest .NET SDK version by default. To target a different version, use the -f or --framework switch to specify a target framework. For example, to target .NET 6, as shown in the following command: dotnet new console -f net6.0

1. At the command prompt or terminal, use the dotnet CLI to add the project to the solution, as shown in the following command:

dotnet sln add HelloCS

1. Note the results, as shown in the following output:

Project `HelloCS\HelloCS.csproj` added to the solution.

1. At the command prompt or terminal, start Visual Studio Code and open the current folder indicated with a . (dot), as shown in the following command:

code .

1. If you are prompted, Do you trust the authors of the files in this folder?, then select the Trust the authors of all files in the parent folder 'cs12dotnet8' check box and then click Yes, I trust the authors.

2. In Visual Studio Code, in EXPLORER, in the CHAPTER01-VSCODE folder view, expand the HelloCS folder, and you will see that the dotnet command-line tool created two files, HelloCS.csproj and Program.cs, and bin and obj folders, as shown in Figure 1.10:

   

3. Navigate to View | Output.

4. In the OUTPUT pane, select C# Dev Kit and note the tool has recognized and processed the solution, as shown in Figure 1.11:

   

5. At the bottom of EXPLORER, note the SOLUTION EXPLORER.
6. Drag SOLUTION EXPLORER to the top of the EXPLORER pane and expand it.
7. In SOLUTION EXPLORER, expand the HelloCS project, and then click the file named Program.cs to open it in the editor window.
8. In Program.cs, modify line 2 so that the text that is being written to the console says Hello, C#!

Good Practice: Navigate to File | Auto Save. This toggle will save the annoyance of remembering to save before rebuilding your application each time.

Compiling and running code using the dotnet CLI

The next task is to compile and run the code:

1. In SOLUTION EXPLORER, right-click on any file in the HelloCS project and choose Open In Integrated Terminal.
2. In TERMINAL, enter the following command: dotnet run.

3. The output in the TERMINAL window will show the result of running your application, as shown in Figure 1.12:

   

4. In Program.cs, after the statement that outputs the message, add statements to get the name of the namespace of the Program class, write it to the console, and then throw a new exception, as shown in the following code:

string name = typeof(Program).Namespace ?? "None!";
Console.WriteLine($"Namespace: {name}");
throw new Exception();

1. In TERMINAL, enter the following command: dotnet run.

   In TERMINAL, you can press the up and down arrows to loop through previous commands and then press the left and right arrows to edit the command before pressing Enter to run them.

2. The output in the TERMINAL window will show the result of running your application, including that a hidden Program class was defined by the compiler with a method named <Main>$ that has a parameter named args for passing in arguments, and that it does not have a namespace, as shown in the following output:

Hello, C#!
Namespace: None!
Unhandled exception. System.Exception: Exception of type 'System.Exception' was thrown.
   at Program.<Main>$(String[] args) in C:\cs12dotnet8\Chapter01-vscode\HelloCS\Program.cs:line 7

Adding a second project using Visual Studio Code

Let's add a second project to explore how to work with multiple projects:

1. In TERMINAL, change to the Chapter01-vscode directory, as shown in the following command:

cd ..

1. In TERMINAL, enter the command to create a new console app project named AboutMyEnvironment using the older non-top-level program style, as shown in the following command:

dotnet new console -o AboutMyEnvironment --use-program-main

Good Practice: Be careful when entering commands in TERMINAL. Be sure that you are in the correct folder before entering potentially destructive commands!

1. In TERMINAL, use the dotnet CLI to add the new project folder to the solution, as shown in the following command:

dotnet sln add AboutMyEnvironment

1. Note the results, as shown in the following output:

Project `AboutMyEnvironment\AboutMyEnvironment.csproj` added to the solution.

1. In SOLUTION EXPLORER, in the AboutMyEnvironment project, open Program.cs, and then in the Main method, change the existing statement to output the current directory, the operating system version string, and the namespace of the Program class, as shown in the following code:

Console.WriteLine(Environment.CurrentDirectory);
Console.WriteLine(Environment.OSVersion.VersionString);
Console.WriteLine("Namespace: {0}", typeof(Program).Namespace);

1. In SOLUTION EXPLORER, right-click on any file in the AboutMyEnvironment project and choose Open In Integrated Terminal.
2. In TERMINAL, enter the command to run the project, as shown in the following command: dotnet run.
3. Note the output in the TERMINAL window, as shown in the following output and in Figure 1.13:

C:\cs12dotnet8\Chapter01-vscode\AboutMyEnvironment
Microsoft Windows NT 10.0.22621.0
Namespace: AboutMyEnvironment

Once you open multiple terminal windows, you can toggle between them by clicking their names in the panel on the right-hand side of TERMINAL. By default, the name will be one of the common shells like pwsh, powershell, zsh, or bash. Right-click and choose to rename to set something else.

When using Visual Studio Code, or more accurately, the dotnet CLI, to run a console app, it executes the app from the <projectname> folder. When using Visual Studio 2022 for Windows, it executes the app from the <projectname>\bin\Debug\net8.0 folder. It will be important to remember this when we work with the filesystem in later chapters.

If you were to run the program on macOS Ventura, the environment operating system would be different, as shown in the following output:

Unix 13.5.2

Good Practice: Although the source code, like the .csproj and .cs files, is identical, the bin and obj folders that are automatically generated by the compiler could have mismatches that give you errors. If you want to open the same project in both Visual Studio 2022 and Visual Studio Code, delete the temporary bin and obj folders before opening the project in the other code editor. This potential problem is why I asked you to create a different folder for the Visual Studio Code projects in this chapter.

Summary of steps for Visual Studio Code

Follow these steps to create a solution and projects using Visual Studio Code:

1. Create a folder for the solution, for example, Chapter01.
2. Create a solution file in the folder: dotnet new sln.
3. Create a folder and project using a template: dotnet new console -o HelloCS.
4. Add the folder and its project to the solution: dotnet sln add HelloCS.
5. Repeat steps 3 and 4 to create and add any other projects.
6. Open the folder containing the solution using Visual Studio Code: code .

Summary of other project types used in this book

A Console App / console project is just one type of project template. In this book, you will also create projects using the following project templates, as shown in Table 1.5:

Table 1.5: Project template names for various code editors

The steps for adding any type of new project to a solution are the same. Only the type name of the project template differs, and sometimes some command-line switches to control options. I will always specify what those switches and options should be if they differ from the defaults.A summary of project template defaults, options, and switches can be found here: https://github.com/markjprice/cs12dotnet8/blob/main/docs/ch01-project-options.md.

Understanding the solution code on GitHub

The solution code in the GitHub repository for this book includes folders for each chapter that can be opened with any of the following code editors:

• Visual Studio 2022 or JetBrains Rider: Open the .sln solution file.
• Visual Studio Code: Open the folder that contains the solution file.

Chapters 1 to 11 each have their own solution file named ChapterXX.sln where XX is the chapter number. Chapters 12 to 16 share a single solution file named PracticalApps.sln.All the code solutions can be found at the following link:https://github.com/markjprice/cs12dotnet8/tree/main/code

Good Practice: If you need to, return to this chapter to remind yourself how to create and manage multiple projects in the code editor of your choice. The GitHub repository has step-by-step instructions for three code editors (Visual Studio 2022, Visual Studio Code, and JetBrains Rider), along with additional screenshots: https://github.com/markjprice/cs12dotnet8/tree/main/docs/code-editors/.

Raising issues with the book

If you get stuck following any of the instructions in this book, or if you spot a mistake in the text or the code in the solutions, please raise an issue in the GitHub repository:

1. Use your favorite browser to navigate to the following link: https://github.com/markjprice/cs12dotnet8/issues.
2. Click New Issue.
3. Enter as much detail as possible that will help me to diagnose the issue. For example:
   • The specific section title, page number, and step number.
   • Your code editor, for example, Visual Studio 2022, Visual Studio Code, or something else, including the version number.
   • As much of your code and configuration that you feel is relevant and necessary.
   • Description of expected behavior and the behavior experienced.
   • Screenshots (you can drag and drop image files into the Issue box).

The following is less relevant but might be useful:

• Your operating system, for example, Windows 11 64-bit, or macOS Ventura version 13.5.2.
• Your hardware, for example, Intel, Apple Silicon, or ARM CPU.

I cannot always respond immediately to issues. But I want all my readers to be successful with my book, so if I can help you (and others) without too much trouble, then I will gladly do so.

Giving me feedback

If you'd like to give me more general feedback about the book, then either email me at markjprice@gmail.com or ask me a question on Discord in the book channel. You can provide the feedback anonymously, or if you would like a response from me, then you can supply an email address. I will only use this email address to answer your feedback.Please join me and your fellow readers on Discord using this invite: https://packt.link/cs12dotnet8I recommend that you add the preceding link to your favorite bookmarks.I love to hear from my readers about what they like about my book, as well as suggestions for improvements and how they are working with C# and .NET, so don't be shy. Please get in touch!Thank you in advance for your thoughtful and constructive feedback.

Avoiding common mistakes

After working through the step-by-step tasks in this book, readers often then strike out on their own and attempt to write similar code, but sometimes they hit problems and either raise an issue in the GitHub repository or post a question to the Discord channel for the book. From these, I have noted some common mistakes, so I maintain a page in the repository to highlight and explain these potential traps and how to fix them:https://github.com/markjprice/cs12dotnet8/blob/main/docs/errata/common-mistakes.md

Downloading solution code from the GitHub repository

If you just want to download all the solution files without using Git, click the green Code button and then select Download ZIP, as shown in Figure 1.14:

Good Practice: It is best to clone or download the code solutions to a short folder path, like C:\cs12dotnet8\ or C:\book\, to avoid build-generated files exceeding the maximum path length. You should also avoid special characters like #. For example, do not use a folder name like C:\C# projects\. That folder name might work for a simple console app project but once you start adding features that automatically generate code, you are likely to have strange issues. Keep your folder names short and simple.

Using Git with Visual Studio Code and the command prompt

Visual Studio Code has integrations with Git, but it will use your operating system's Git installation, so you must install Git 2.0 or later first before you get these features.You can install Git from the following link: https://git-scm.com/download.If you like to use a GUI, you can download GitHub Desktop from the following link: https://desktop.github.com.

Cloning the book solution code repository

Let's clone the book solution code repository. In the steps that follow, you will use the Visual Studio Code terminal, but you could enter the commands at any command prompt or terminal window:

1. Create a folder named Repos-vscode in your user or Documents folder, or wherever you want to store your Git repositories.
2. Open the Repos-vscode folder at the command prompt or terminal, and then enter the following command:

git clone https://github.com/markjprice/cs12dotnet8.git

Note that cloning all the solutions for all the chapters will take a minute or so, so please be patient.

Reading the documentation on Microsoft Learn

The definitive resource for getting help with Microsoft developer tools and platforms is in the technical documentation on Microsoft Learn, and you can find it at the following link: https://learn.microsoft.com/en-us/docs.

Documentation links in this book

The official Microsoft documentation for .NET needs to cover all versions. The default version shown in the documentation is always the most recent general availability (GA) version.For example, between November 2023 and November 2024, the default version of .NET shown in documentation pages will be 8.0. Between November 2024 and November 2025, the default version of .NET will be 9.0. The following link will automatically direct to the current version depending on the current date:https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.stringsyntaxattributeTo view the documentation page specifically for .NET 7, append ?view=net-7.0 to the end of a link. For example, use the following link:https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.stringsyntaxattribute?view=net-7.0All documentation links in this book do not specify a version, so after November 2024, they will show the documentation pages for .NET 9.0. If you want to force the documentation to show the version for .NET 8.0, then append ?view=net-8.0 to the end of a link.You can check what versions a .NET feature supports by appending #applies-to to the end of a link, for example:https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.codeanalysis.stringsyntaxattribute#applies-toWe can therefore see that the StringSyntax attribute is only available in .NET 7 or later.

Getting help for the dotnet tool

At the command prompt, you can ask the dotnet tool for help with its commands. The syntax is:

dotnet help <command>

This will cause your web browser to open a page in the documentation about the specified command. Common dotnet commands include new, build, run, and many more.

Warning! The dotnet help new command worked with .NET Core 3.1 to .NET 6, but it returns an error with .NET 7 or later: Specified command 'new' is not a valid SDK command. Specify a valid SDK command. For more information, run dotnet help. Hopefully, they will fix that bug soon!

Another type of help is command-line documentation. It follows this syntax:

dotnet <command> -?|-h|--help

For example, dotnet new -? or dotnet new -h or dotnet new --help outputs documentation about the new command at the command prompt.

As you should now expect, dotnet help help opens a web browser for the help command, and dotnet help -h outputs documentation for the help command at the command prompt!

Let's try some examples:

1. To open the official documentation in a web browser window for the dotnet build command, enter the following at the command prompt or in the Visual Studio Code terminal, and note the page opened in your web browser, as shown in Figure 1.15:

dotnet help build

1. To get help output at the command prompt, use the -? or -h or --help flag, as shown in the following command:

dotnet build -?

1. You will see the following partial output:

Description:
  .NET Builder
Usage:
  dotnet build [<PROJECT | SOLUTION>...] [options]
Arguments:
  <PROJECT | SOLUTION>  The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.
Options:
  --ucr, --use-current-runtime         Use current runtime as the target runtime.
  -f, --framework <FRAMEWORK>          The target framework to build for. The target framework must also be specified in the project file.
...
  -?, -h, --help                       Show command line help.

1. Repeat both types of help request for the following commands: add, help, list, new, and run, remembering that new might not show its web page due to a bug introduced in .NET 7.

Getting definitions of types and their members

One of the most useful features of a code editor is Go To Definition (F12). It is available in Visual Studio Code, Visual Studio 2022, and JetBrains Rider. It will show what the public definition of the type or member looks like by reading the metadata in the compiled assembly.Some tools, such as ILSpy .NET Decompiler, will even reverse-engineer from the metadata and IL code back into C# or another language for you.A similar and related feature is named Go To Implementation (Ctrl + F12). Instead of reading the metadata or decompiling, this will show the actual source code if that is embedded using the optional source link feature.

Warning! Go To Definition should go to the decompiled metadata for a member or type. But if you have previously viewed source link, then it goes to source link. Go To Implementation should go to the source link implementation for a member or type. But if you have disabled source link, then it goes to the decompiled metadata.

Let's see how to use the Go To Definition feature:

1. In your preferred code editor, open the solution/folder named Chapter01.

• If you are using Visual Studio 2022:
  • Navigate to Tools | Options.
  • In the search box, enter navigation to source.
  • Select Text Editor | C# | Advanced.
  • Clear the Enable navigation to Source Link and Embedded sources check box, and then click OK, as shown in Figure 1.16:

Definitions can be either reverse-engineered from metadata or loaded from the original source code if that is enabled. Personally, I find the code from metadata more useful, as you are about to see. At the end of this section, try switching the Source Link option back on to see the difference.

1. In the HelloCS project, at the bottom of Program.cs, enter the following statement to declare an integer variable named z:

int z;

1. Click on int, right-click on int, and then choose Go To Definition in Visual Studio 2022 or Visual Studio Code. In JetBrains Rider, choose Go to | Go to Declaration or Usages.
2. In the code window that appears, you can see how the int data type is defined, as shown in Figure 1.17:

You can see that int:

• Is defined using the struct keyword.
• Is in the System.Runtime assembly.
• Is in the System namespace.
• Is named Int32.
• Is therefore an alias for the System.Int32 type.
• Implements interfaces such as IComparable.
• Has constant values for its maximum and minimum values.
• Has methods such as Parse. (Not visible in Figure 1.17.)

Right now, the Go To Definition feature is not that useful to you because you do not yet know what all of this information means. By the end of the first part of this book, which consists of Chapters 2 to 6 and teaches you about the C# language, you will know enough for this feature to become very handy.

1. In the code editor window, scroll down to find the Parse method with a single string parameter, as shown in the following code:

public static Int32 Parse(string s)

1. Expand the code and review the comments that document this method, as shown in Figure 1.18:

In the comments, you will see that Microsoft has documented the following:

• A summary that describes the method.
• Parameters like the string value that can be passed to the method.
• The return value of the method, including its data type.
• Three exceptions that might occur if you call this method, including ArgumentNullException, FormatException, and OverflowException. Now, we know that we could choose to wrap a call to this method in a try statement and which exceptions to catch.

Hopefully, you are getting impatient to learn what all this means!Be patient for a little longer. You are almost at the end of this chapter, and in the next chapter, you will dive into the details of the C# language. But first, let's see where else you can look for help.

Configuring inline aka inlay hints

Throughout the code in this book, when calling a method, I often explicitly specify named parameters to help the reader learn what is going on. For example, I have specified the names of the parameters format and arg0 in the following code:

Console.WriteLine(format: "Value is {0}.", arg0: 19.8);

Inline hints aka inlay hints show the names of parameters without you having to type them, as shown in Figure 1.19:

Most code editors have this feature that you can enable permanently or only when a key combination like Alt + F1 or Ctrl is held down:

• In Visual Studio 2022, navigate to Tools | Options, navigate to Text Editor | C# | Advanced, scroll down to the Inline Hints section, and select the Display inline parameter hint names check box, and then click OK.
• In Visual Studio Code, navigate to File | Preferences | Settings, search for inlay, select the C# filter, and then select the Display inline parameter name hints check box.
• In JetBrains Rider, in Settings, navigate to Editor | Inlay Hints | C# | Parameter Name Hints.

Looking for answers on Stack Overflow

Stack Overflow is the most popular third-party website for getting answers to difficult programming questions. Let's see an example:

1. Start your favorite web browser.
2. Navigate to stackoverflow.com; in the search box, enter securestring and note the search results, which are shown in Figure 1.20:

Searching for answers using Google

You can search Google with advanced search options to increase the likelihood of finding what you need:

1. Navigate to Google at the following link: https://www.google.com/.
2. Search for information about garbage collection using a simple Google query and note that you will probably see a lot of ads for garbage collection services in your local area before you see the Wikipedia definition of garbage collection in computer science.
3. Improve the search by restricting it to a useful site such as Stack Overflow, and by removing languages that we might not care about, such as C++, Rust, and Python, or by adding C# and .NET explicitly, as shown in the following search query:

garbage collection site:stackoverflow.com +C# -Java

Searching the .NET source code

Sometimes you can learn a lot from seeing how the Microsoft teams have implemented .NET. The source for the entire code base for .NET is available in public GitHub repositories. For example, you might know that there is a built-in attribute to validate an email address. Let's search the repositories for the word "email" and see if we can find out how it works:

1. Use your preferred web browser to navigate to: https://github.com/search.
2. Click advanced search.
3. In the search box, type email.
4. In the In these respositories box, type dotnet/runtime. (Other repositories you might want to search include dotnet/core, dotnet/aspnetcore, dotnet/wpf, dotnet/winforms).
5. In the Written in this language box, select C#.

6. In the top right of the page, note how the advanced query has been written for you, click Search, and then click the Code filter and note the results include the EmailAddressAttribute, as shown in Figure 1.21:

   

7. Click the source file and note it implements email validation by checking that the string value contains an @ symbol but not as the first or last character, as shown in the following code:

// only return true if there is only 1 '@' character
// and it is neither the first nor the last character
int index = valueAsString.IndexOf('@');
return
    index > 0 &&
    index != valueAsString.Length - 1 &&
    index == valueAsString.LastIndexOf('@');

1. Close the browser.

For your convenience, you can do a quick search for other terms by replacing the search term email in the following link: https://github.com/search?q=%22email%22+repo%3Adotnet%2Fruntime+language%3AC%23&type=code&ref=advsearch.

Subscribing to the official .NET blog

To keep up to date with .NET, an excellent blog to subscribe to is the official .NET blog, written by the .NET engineering teams, and you can find it at the following link: https://devblogs.microsoft.com/dotnet/.

Watching Scott Hanselman's videos

Scott Hanselman from Microsoft has an excellent YouTube channel about computer stuff they didn't teach you: http://computerstufftheydidntteachyou.com/.I recommend it to everyone working with computers.

AI tools like ChatGPT and GitHub Copilot

One of the biggest changes in coding and development in the past year is the emergence of generative artificial intelligence (AI) tools that can help with coding tasks like completing a code statement, implementing an entire function, writing unit tests, and suggesting debugging fixes for existing code.

You can read what developers say about AI tools in the 2023 Stack Overflow Developer Survey. "44% of them use AI tools in their development process now, and 26% plan to soon.": https://stackoverflow.blog/2023/06/14/hype-or-not-developers-have-something-to-say-about-ai/.

ChatGPT currently has two models: 3.5 (free) and 4.0 ($20 per month). Let's say you need to write a C# function to validate an email address. You might go to ChatGPT and enter the following prompt:

write a c# function to validate an email address

It responds with a complete class with methods, as shown in Figure 1.22:

It then provides an explanation of the code and examples of how to call the function, as shown in the following code:

bool isValid = EmailValidator.IsValidEmail("test@example.com");
Console.WriteLine(isValid ? "Valid" : "Invalid");

But is a general-purpose generative AI like ChatGPT the best partner for a C# programmer?Microsoft has a service specifically for programmers, named GitHub Copilot, that can help autocomplete code directly in your code editor. It is being enhanced with more intelligence using GPT-4. It has plugins for code editors including Visual Studio 2022, Visual Studio Code, and JetBrains IntelliJ-based IDEs.

Personally, I really like the Copilot branding. It makes it clear that you are the pilot. You are ultimately responsible for "flying the plane." But for the easy or boring bits, you can hand it over to your co-pilot for a bit, while being actively ready to take back control if needed.

GitHub Copilot is free for students, teachers, and some open source project maintainers. For everyone else, it has a 30-day free trial and then it costs $10 per month or $100 per year for individuals. Once you have an account, you can then sign up for waiting lists to get the more advanced experimental GitHub Copilot X features. You should check online for which Copilot features are available for various code editors. As you can imagine, this is a fast-changing world and a lot of what I might write in the book today will be out-of-date by the time you read it: https://github.com/features/copilot.

JetBrains has its own equivalent, named AI Assistant, that you can read about at the following link: https://blog.jetbrains.com/idea/2023/06/ai-assistant-in-jetbrains-ides/.

So, what can GitHub Copilot do for you today?Imagine that you have just added a new class file named Product.cs. You click inside the Product class, press Enter to insert a blank line, and then pause for a second as you think about what you need to type…and GitHub Copilot generates some sample code in gray, as shown in Figure 1.23:

At this point, you can glance over the code and, if it is close to what you want, just press Tab to insert it all, or press Alt + . (dot) to toggle between other suggestions.Sometimes it is too far off what you need, and you'll be better off ignoring its suggestion completely and just writing it yourself. But usually, there's something there that's usable or reminds you of the syntax you need to use. And sometimes, it feels like magic, writing dozens of lines of exactly what you need.Microsoft feeds its AI tools with code from public GitHub repositories, including all the repositories I have created since 2016 for all the editions of this book. This means that it can suggest code completions for the readers of this book that are surprisingly accurate predictions including my frequent use of pop culture references in my code. It's like I, Mark J. Price, am the "ghost in the machine" guiding your coding.It's easy to imagine a custom ChatGPT that has ingested all the official Microsoft .NET documentation, every public blog article written about .NET, and perhaps even hundreds of books about .NET, and having a conversation about it to find a bug or suggest how to solve a programming problem.

You can sign up for GitHub Copilot at the following link: https://github.com/github-copilot/signup/.

Disabling tools when they get in the way

Although these tools can be helpful, they can also get in your way, especially when learning, because they sometimes do work for you without telling you. If you do not do that work for yourself at least a few times, you won't learn fully.To configure IntelliSense for C# in Visual Studio 2022:

1. Navigate to Tools | Options.
2. In the Options dialog box tree view, navigate to Text Editor | C# | IntelliSense.
3. Click the ? button in the caption bar to view the documentation.

To configure GitHub Copilot X in Visual Studio 2022:

1. Navigate to Tools | Options.
2. In the Options dialog box tree view, navigate to GitHub | Copilot.
3. Set Enable Globally to True or False, and then click OK.

To disable GitHub Copilot X in Visual Studio Code:

1. In the status bar, on the right, to the left of the notification icon, click the GitHub Copilot icon.
2. In the popup, click Disable Globally.
3. To enable, click the GitHub Copilot icon again and then click Enable Globally.

For help with JetBrains Rider IntelliSense, please see the following link: https://www.jetbrains.com/help/rider/Auto-Completing_Code.xhtml.

Exercise 1.1 – Test your knowledge

Try to answer the following questions, remembering that although most answers can be found in this chapter, you should do some online research or code writing to answer others:

1. Is Visual Studio 2022 better than Visual Studio Code?
2. Is .NET 5 and later better than .NET Framework?
3. What is .NET Standard and why is it still important?
4. Why can a programmer use different languages, for example, C# and F#, to write applications that run on .NET?
5. What is a top-level program and how do you access any command-line arguments?
6. What is the name of the entry point method of a .NET console app and how should it be explicitly declared if you are not using the top-level program feature?
7. What namespace is the Program class defined in with a top-level program?
8. Where would you look for help for a C# keyword?
9. Where would you look first for solutions to common programming problems?
10. What should you do after getting an AI to write code for you?

Appendix, Answers to the Test Your Knowledge Questions, is available to download from a link in the README in the GitHub repository: https://github.com/markjprice/cs12dotnet8.

Exercise 1.2 – Practice C# anywhere with a browser

You don't need to download and install Visual Studio Code or even Visual Studio 2022 to write C#. You can start coding online at any of the following links:

• Visual Studio Code for Web: https://vscode.dev/
• SharpLab: https://sharplab.io/
• C# Online Compiler | .NET Fiddle: https://dotnetfiddle.net/
• W3Schools C# Online Compiler: https://www.w3schools.com/cs/cs_compiler.php

Exercise 1.3 – Explore topics

A book is a curated experience. I have tried to find the right balance of topics to include in the printed book. Other content that I have written can be found in the GitHub repository for this book.I believe that this book covers all the fundamental knowledge and skills a C# and .NET developer should have or be aware of. Some longer examples are best included as links to Microsoft documentation or third-party article authors.Use the links on the following page to learn more details about the topics covered in this chapter:https://github.com/markjprice/cs12dotnet8/blob/main/docs/book-links.md#chapter-1---hello-c-welcome-net

Exercise 1.4 – Explore Polyglot Notebooks

Complete the following online-only section to explore how you can use Polyglot Notebooks with its .NET Interactive engine:https://github.com/markjprice/cs12dotnet8/blob/main/docs/ch01-polyglot-notebooks.md

Exercise 1.5 – Explore themes of modern .NET

Microsoft has created a website using Blazor that shows the major themes of modern .NET: https://themesof.net/

Exercise 1.6 – Free Code Camp and C# Certification

For many years, Microsoft had an exam for C# 5, Exam 70-483: Programming in C#. I taught hundreds of developers the skills needed to get qualified and pass it. Sadly, that exam was retired a few years ago.In August 2023, Microsoft announced a new foundational certification for C# alongside a free 35-hour online course. You can read more about how to qualify for the certification at the following link:https://www.freecodecamp.org/learn/foundational-c-sharp-with-microsoft/

Exercise 1.7 – Alpha versions of .NET

You can (but probably shouldn't) download future versions of .NET including alpha versions from the following link:https://github.com/dotnet/installer#tableFor example, in August 2023, you could download .NET SDK 9 alpha, which included an early release candidate of the .NET 8 runtime, although so few people do that Edge gives a warning and tries to stop you, as shown in Figure 1.24:

Warning! Alpha versions are designed to be used only internally by Microsoft employees. Beta versions (official previews) are designed to be used externally and are publicized in Microsoft blog posts. Personally, I would not download an alpha of .NET 9 until December 2023 when it might have some new features compared to .NET 8. Once official previews of .NET 9 become available in February 2024, I recommend using those instead.

For more about using .NET 9 or 10 with this book, please see the following link: https://github.com/markjprice/cs12dotnet8/blob/main/docs/dotnet9.md.

C# language versions and features

This part of the book covers the C# programming language and is written primarily for beginners, so it covers the fundamental topics that all developers need to know, including declaring variables, storing data, and how to define your own custom data types.This book covers features of the C# language from version 1 up to the latest version, 12.If you already have some familiarity with older versions of C# and are excited to find out about the new features in the most recent versions of C#, I have made it easier for you to jump around by listing language versions and their important new features below, along with the chapter number and topic title where you can learn about them.

Understanding C# standards

Over the years, Microsoft has submitted a few versions of C# to standards bodies, as shown in Table 2.14:

Table 2.14: ECMA standards for C#

The ECMA standard for C# 7.3 is still a draft. So don't even think about when C# versions 8 to 12 might be ECMA standards! Microsoft made C# open source in 2014. You can read the latest C# standard document at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/specifications.

More practically useful than the ECMA standards are the public GitHub repositories for making the work on C# and related technologies as open as possible, as shown in Table 2.15:

Table 2.15: Public GitHub repositories for C#

How to output the SDK version

Let's see what .NET SDK and C# language compiler versions you have available:

1. On Windows, start Windows Terminal or Command Prompt. On macOS, start Terminal.
2. To determine which version of the .NET SDK you have available, enter the following command:

dotnet --version

1. Note that the version at the time of publishing is 8.0.100, indicating that it is the initial version of the SDK without any bug fixes or new features yet, as shown in the following output:

8.0.100

Enabling a specific language version compiler

Developer tools like Visual Studio and the dotnet command-line interface assume that you want to use the latest major version of a C# language compiler by default. Before C# 8 was released, C# 7 was the latest major version and was used by default. To use the improvements in a C# point release like 7.1, 7.2, or 7.3, you had to add a <LangVersion> configuration element to the project file, as shown in the following markup:

<LangVersion>7.3</LangVersion>

After the release of C# 12 with .NET 8, if Microsoft releases a C# 12.1 compiler and you want to use its new language features, then you will have to add a configuration element to your project file, as shown in the following markup:

<LangVersion>12.1</LangVersion>

Potential values for the <LangVersion> are shown in Table 2.18:

Table 2.18: LangVersion settings for a project file

Using future C# compiler versions

In February 2024, Microsoft is likely to release the first preview of .NET 9 with a C# 13 compiler. You will be able to install its SDK from the following link:https://dotnet.microsoft.com/en-us/download/dotnet/9.0The link will give a 404 Missing resource error until February 2024, so do not bother using it until then!After you've installed a .NET 9 SDK preview, you will be able to use it to create new projects and explore the new language features in C# 13. After creating a new project, you can edit the .csproj file and add the <LangVersion> element set to preview to use the preview C# 13 compiler, as shown highlighted in the following markup:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <LangVersion>preview</LangVersion>
  </PropertyGroup>
</Project>

Switching the C# compiler for .NET 8 to a future version

.NET 8 is an LTS release, so Microsoft must support developers who continue to use .NET 8 for three years. But that does not mean that you are stuck with the C# 12 compiler for three years!In November 2024, Microsoft is likely to release .NET 9, including a C# 13 compiler with new features. Although future versions of .NET 8 are likely to include preview versions of the C# 13 compiler, to be properly supported by Microsoft, you should only set <LangVersion> to preview for exploration, not production projects, because it is not supported by Microsoft, and it is more likely to have bugs. Microsoft makes previews available because they want to hear feedback. You can be a part of C#'s development and improvement.Once .NET 9 SDK is made generally available in November 2024, you will be able to get the best of both worlds. You can use the .NET 9 SDK and its C# 13 compiler while your projects continue to target .NET 8. To do so, set the target framework to net8.0 and add a <LangVersion> element set to 13, as shown highlighted in the following markup:

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

The preceding project targets net8.0 so it is supported until November 2026 when run on a monthly patched version of the .NET 8 runtime. If the preceding project is built using .NET 9 SDK, then it can have the <LangVersion> set to 13 meaning C# 13.If you target net9.0, which new projects will by default if you have installed the .NET 9 SDK, then the default language will be C# 13 so it would not need to be explicitly set.In February 2025, Microsoft is likely to release the first preview of .NET 10, and, in November 2025, it will likely release .NET 10 for general availability in production. You will be able to install its SDK from the following link and explore C# 14 in the same way as described above for C# 13 with .NET 9:https://dotnet.microsoft.com/en-us/download/dotnet/10.0Again, the preceding link is for future use! It will give a 404 Missing resource error until February 2025, so do not bother using it until then.

Warning! Some C# language features depend on changes in the underlying .NET libraries. Even if you use the latest SDK with the latest compiler, you might not be able to use all the new language features while targeting an older version of .NET. For example, C# 11 introduced the required keyword, but it cannot be used in a project that targets .NET 6 because that language feature requires new attributes that are only available in .NET 7. Luckily, the compiler will warn you if you try to use a C# feature that is not supported. Just be prepared for that eventuality.

Showing the compiler version

We will start by writing code that shows the compiler version:

1. If you've completed Chapter 1, Hello, C#! Welcome, .NET!, then you will already have a cs12dotnet8 folder. If not, then you'll need to create it.

2. Use your preferred code editor to create a new project, as defined in the following list:

   • Project template: Console App [C#] / console
   • Project file and folder: Vocabulary
   • Solution file and folder: Chapter02
   • Do not use top-level statements: Cleared
   • Enable native AOT publish: Cleared

   Good Practice: If you have forgotten how, or did not complete the previous chapter, then step-by-step instructions for creating a solution with multiple projects are given in Chapter 1, Hello, C#! Welcome, .NET!.

3. In the Vocabulary project, in Program.cs, after the comment, add a statement to show the C# version as an error, as shown in the following code:

#error version

1. Run the console app:
   • If you are using Visual Studio 2022, then navigate to Debug | Start Without Debugging. When prompted to continue and run the last successful build, click No.
   • If you are using Visual Studio Code, then in a terminal for the Vocabulary folder, enter the command dotnet run. Note that we are expecting a compiler error, so do not panic when you see it!
2. Note that the compiler version and the language version appear as a compiler error message number CS8304, as shown in Figure 2.1:

The error message in the Visual Studio Code PROBLEMS window or Visual Studio Error List window says Compiler version: '4.8.0...' with language version default (12.0).

1. Comment out the statement that causes the error, as shown in the following code:

// #error version

1. Note that the compiler error messages disappear.

Understanding C# grammar

The grammar of C# includes statements and blocks. To document your code, you can use comments.

Good Practice: Comments should not be the only way that you document your code. Choosing sensible names for variables and functions, writing unit tests, and creating actual documents are other ways to document your code.

Statements

In English, we indicate the end of a sentence with a full stop. A sentence can be composed of multiple words and phrases, with the order of words being part of the grammar. For example, in English, we say "the black cat."The adjective, black, comes before the noun, cat. Whereas French grammar has a different order; the adjective comes after the noun: "le chat noir." What's important to take away from this is that the order matters.C# indicates the end of a statement with a semicolon. A statement can be composed of multiple types, variables, and expressions made up of tokens. Each token is separated by white space or some other recognizably different token like an operator, for example, = or +. For example, in the following statement, decimal is a type, totalPrice is a variable, and subtotal + salesTax is an expression:

decimal totalPrice = subtotal + salesTax;

The expression is made up of an operand named subtotal, an operator +, and another operand named salesTax. The order of operands and operators matters because the order affects the meaning and result.

Comments

Comments are the primary method of documenting your code to increase an understanding of how it works, for other developers to read, or for you to read even when you come back to it months later.

In Chapter 4, Writing, Debugging, and Testing Functions, you will learn about XML comments that start with three slashes /// and work with a tool to generate web pages to document your code.

You can add comments to explain your code using a double slash, //. The compiler will ignore everything after the // until the end of the line, as shown in the following code:

// Sales tax must be added to the subtotal.
var totalPrice = subtotal + salesTax;

To write a multiline comment, use /* at the beginning and */ at the end of the comment, as shown in the following code:

/*
This is a 
multi-line comment.
*/

Although /* */ is mostly used for multiline comments, it is also useful for commenting in the middle of a statement, as shown in the following code:

decimal totalPrice = subtotal /* for this item */ + salesTax;

Good Practice: Well-designed code, including function signatures with well-named parameters and class encapsulation, can be somewhat self-documenting. When you find yourself putting too many comments and explanations in your code, ask yourself: can I rewrite, aka refactor, this code to make it more understandable without long comments?

Your code editor has commands to make it easier to add and remove comment characters, as shown in the following list:

• Visual Studio 2022: Navigate to Edit | Advanced | Comment Selection or Uncomment Selection.
• Visual Studio Code: Navigate to Edit | Toggle Line Comment or Toggle Block Comment.
• JetBrains Rider: Navigate to Code | Comment with Line Comment or Comment with Block Comment.

Good Practice: You comment code by adding descriptive text above or after code statements. You comment out code by adding comment characters before or around statements to make them inactive. Uncommenting means removing the comment characters.

Blocks

In English, we indicate a new paragraph by starting a new line. C# indicates a block of code with the use of curly brackets, { }.Blocks start with a declaration to indicate what is being defined. For example, a block can define the start and end of many language constructs including namespaces, classes, methods, or statements like foreach.You will learn more about namespaces, classes, and methods later in this chapter and subsequent chapters, but to briefly introduce some of those concepts now:

• A namespace contains types like classes to group them together.
• A class contains the members of an object, including methods.
• A method contains statements that implement an action that an object can take.

Code editors like Visual Studio 2022 and Visual Studio Code provide a handy feature to collapse and expand blocks by toggling the [-] or [+] or an arrow symbol pointing down or left when you move your mouse cursor over the left margin of the code, as shown in Figure 2.2:

Regions

You can define your own labeled regions around any statements you want and then most code editors will allow you to collapse and expand them in the same way as blocks, as shown in the following code:

#region Three variables that store the number 2 million.
int decimalNotation = 2_000_000;
int binaryNotation = 0b_0001_1110_1000_0100_1000_0000; 
int hexadecimalNotation = 0x_001E_8480;
#endregion

In this way, regions can be treated as commented blocks that can be collapsed to show a summary of what the block does. I will use #region blocks throughout the solution code in the GitHub repository, especially for the early chapters before we start defining functions that act as natural collapsible regions, but I won't show them in the print book to save space. Use your own judgment to decide if you want to use regions in your own code.

Examples of statements and blocks

In a simple console app that does not use the top-level program feature, I've added some comments to the statements and blocks, as shown in the following code:

using System; // A semicolon indicates the end of a statement.
namespace Basics
{ // An open brace indicates the start of a block.
  class Program
  {
    static void Main(string[] args)
    {
      Console.WriteLine("Hello World!"); // A statement.
    }
  }
} // A close brace indicates the end of a block.

Note that C# uses a brace style where both the open and close braces are on their own line and are at the same indentation level, as shown in the following code:

if (x < 3)
{
  // Do something if x is less than 3.
}

Other languages like JavaScript use curly braces but format them differently. They put the open curly brace at the end of the declaration statement, as shown in the following code:

if (x < 3) {
  // Do something if x is less than 3.
}

You can use whatever style you prefer because the compiler does not care. Sometimes, to save vertical space in a print book, I use the JavaScript brace style, but mostly I stick with the C# brace style. I use two spaces instead of the more common four spaces for indenting because my code will be printed in a book and therefore has narrow width available.

More Information: The official coding style conventions can be found at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions.

Regardless of any official guidelines, I recommend that you conform to whatever standards have been adopted by your development team unless you are a solo developer, in which case as long as your code compiles, you can use any conventions you like. Be kind to your future self though by being consistent one way or the other!

Good Practice: The brace style used in the Microsoft official documentation is the most commonly used for C#. For example, see the for statement, as found at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/statements/iteration-statements.

Formatting code using white space

White space includes the space, tab, and newline characters. You can use white space to format your code however you like because extra white space has no effect on the compiler.The following four statements are all equivalent:

int sum = 1 + 2; // Most developers would prefer this format.
int
sum=1+
2; // One statement over three lines.
int       sum=    1    +2;int sum=1+2; // Two statements on one line.

The only white space characters required in the preceding statements is one between int and sum to tell the compiler they are separate tokens. Any single white space character, for example a space, tab, or newline would be acceptable.

More Information: You can read the formal definition of C# white space at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/lexical-structure#634-white-space.

Understanding C# vocabulary

The C# vocabulary is made up of keywords, symbol characters, and types.Some of the predefined, reserved keywords that you will see in this book and use frequently include using, namespace, class, static, int, string, double, bool, if, switch, break, while, do, for, foreach, this, and true.Some of the symbol characters that you will see include ", ', +, -, *, /, %, @, and $.There are other contextual keywords that only have a special meaning in a specific context like and, or, not, record, and init.However, that still means that there are only about 100 actual C# keywords in the language.

Good Practice: C# keywords use all lowercase. Although you can use all lowercase for your own type names, you should not. With C# 11 and later, the compiler will give a warning if you do, as shown in the following output: Warning CS8981 The type name 'person' only contains lower-cased ascii characters. Such names may become reserved for the language.

Comparing programming languages to human languages

The English language has more than 250,000 distinct words, so how does C# get away with only having about 100 keywords? Moreover, why is C# so difficult to learn if it has only 0.0416% of the number of words in the English language?One of the key differences between a human language and a programming language is that developers need to be able to define the new "words" with new meanings. Apart from the (about) 100 keywords in the C# language, this book will teach you about some of the hundreds of thousands of "words" that other developers have defined, but you will also learn how to define your own "words."Programmers all over the world must learn English because most programming languages use English words such as "if" and "break." There are programming languages that use other human languages, such as Arabic, but they are rare. If you are interested in learning more, this YouTube video shows a demonstration of an Arabic programming language: https://youtu.be/dkO8cdwf6v8.

Changing the color scheme for C# syntax

By default, Visual Studio 2022 and Visual Studio Code show C# keywords in blue to make them easier to differentiate from other code, which defaults to black. Both tools allow you to customize the color scheme.In Visual Studio 2022:

1. Navigate to Tools | Options.
2. In the Options dialog box, in the Environment section, select Fonts and Colors, and then select the display items that you would like to customize. You can also search for the section instead of browsing for it.

In Visual Studio Code:

1. Navigate to File | Preferences | Theme | Color Theme. It is in the Code menu on macOS.
2. Select a color theme. For reference, I'll use the Light+ (default light) color theme so that the screenshots look better in a printed book.

In JetBrains Rider:

1. Navigate to File | Settings | Editor | Color Scheme.

Help for writing correct code

Plain text editors such as Notepad don't help you write correct English. Likewise, Notepad won't help you write the correct C# either.Microsoft Word can help you write English by highlighting spelling mistakes with red squiggles, with Word saying that "icecream" should be ice-cream or ice cream, and grammatical errors with blue squiggles, such as a sentence should have an uppercase first letter.Similarly, Visual Studio 2022 and Visual Studio Code's C# extension help you write C# code by highlighting spelling mistakes, such as the method name needing to be WriteLine with an uppercase L, and grammatical errors, such as statements that must end with a semicolon.The C# extension constantly watches what you type and gives you feedback by highlighting problems with colored squiggly lines, like that of Microsoft Word.Let's see it in action:

1. In Program.cs, change the L in the WriteLine method to lowercase.
2. Delete the semicolon at the end of the statement.

3. In Visual Studio Code, navigate to View | Problems; in Visual Studio 2022, navigate to View | Error List; or in JetBrains Rider, navigate to View | Tool Windows | Problems, and note that a red squiggle appears under the code mistakes and details are shown, as you can see in Figure 2.3:

   

4. Fix the two coding errors.

Importing namespaces

System is a namespace, which is like an address for a type. To refer to someone's location exactly, you might use Oxford.HighStreet.BobSmith, which tells us to look for a person named Bob Smith on the High Street in the city of Oxford.System.Console.WriteLine tells the compiler to look for a method named WriteLine in a type named Console in a namespace named System. To simplify our code, the Console App project template for every version of .NET before 6.0 added a statement at the top of the code file to tell the compiler to always look in the System namespace for types that haven't been prefixed with their namespace, as shown in the following code:

using System; // Import the System namespace.

We call this importing the namespace. The effect of importing a namespace is that all available types in that namespace will be available to your program without needing to enter the namespace prefix. All available types in that namespace will be seen in IntelliSense while you write code.

Implicitly and globally importing namespaces

Traditionally, every .cs file that needs to import namespaces would have to start with using statements to import those namespaces. Namespaces like System and System.Linq are needed in almost all .cs files, so the first few lines of every .cs file often had at least a few using statements, as shown in the following code:

using System;
using System.Linq;
using System.Collections.Generic;

When creating websites and services using ASP.NET Core, there are often dozens of namespaces that each file would have to import.C# 10 introduced a new keyword combination and .NET SDK 6 introduced a new project setting that works together to simplify importing common namespaces.The global using keyword combination means you only need to import a namespace in one .cs file and it will be available throughout all .cs files instead of having to import the namespace at the top of every file that needs it. You could put global using statements in the Program.cs file, but I recommend creating a separate file for those statements named something like GlobalUsings.cs with the contents being all your global using statements, as shown in the following code:

global using System;
global using System.Linq;
global using System.Collections.Generic;

Good Practice: As developers get used to this new C# feature, I expect one naming convention for this file to become the de facto standard. As you are about to see, the related .NET SDK feature uses a similar naming convention.

Any projects that target .NET 6 or later, and therefore use the C# 10 or later compiler, generate a <ProjectName>.GlobalUsings.g.cs file in the obj\Debug\net8.0 folder to implicitly globally import some common namespaces like System. The specific list of implicitly imported namespaces depends on which SDK you target, as shown in Table 2.19:

Table 2.19: .NET SDKs and their implicitly imported namespaces

Let's see the current autogenerated implicit imports file:

1. In Solution Explorer, toggle on the Show All Files button, and note the compiler-generated bin and obj folders are now visible.

2. In the Vocabulary project, expand the obj folder, expand the Debug folder, expand the net8.0 folder, and then open the file named Vocabulary.GlobalUsings.g.cs.

   The naming convention for this file is <ProjectName>.GlobalUsings.g.cs. Note the g for generated to differentiate it from developer-written code files.

3. Remember that this file is automatically created by the compiler for projects that target .NET 6 and later, and that it imports some commonly used namespaces including System.Threading, as shown in the following code:

// <autogenerated />
global using global::System;
global using global::System.Collections.Generic;
global using global::System.IO;
global using global::System.Linq;
global using global::System.Net.Http;
global using global::System.Threading;
global using global::System.Threading.Tasks;

1. Close the Vocabulary.GlobalUsings.g.cs file.
2. In Solution Explorer, open the Vocabulary.csproj project file, and then add additional entries to the project file to control which namespaces are implicitly imported, as shown highlighted in the following markup:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <Using Remove="System.Threading" />
    <Using Include="System.Numerics" />
    <Using Include="System.Console" Static="true" />
    <Using Include="System.Environment" Alias="Env" />
  </ItemGroup>
</Project>

Note that <ItemGroup> is different from <ImportGroup>. Be sure to use the correct one! Also, note that the order of elements in a project group or item group does not matter. For example, <Nullable> can be before or after <ImplicitUsings>.

1. Save the changes to the project file.
2. Expand the obj folder, expand the Debug folder, expand the net8.0 folder, and open the file named Vocabulary.GlobalUsings.g.cs.
3. Note this file now imports System.Numerics instead of System.Threading, the Environment class has been imported and aliased to Env, and we have statically imported the Console class, as shown highlighted in the following code:

// <autogenerated />
global using global::System;
global using global::System.Collections.Generic;
global using global::System.IO;
global using global::System.Linq;
global using global::System.Net.Http;
global using global::System.Numerics;
global using global::System.Threading.Tasks;
global using Env = global::System.Environment;
global using static global::System.Console;

1. In Program.cs, add a statement to output a message from the computer and note that because we statically imported the Console class, we can call its methods like WriteLine without prefixing them with Console, and we can reference the Environment class using its alias Env, as shown in the following code:

WriteLine($"Computer named {Env.MachineName} says \"No.\"");

1. Run the project and note the message, as shown in the following output:

Computer named DAVROS says "No."

Your computer name will be different unless you name your computers after characters from Doctor Who like I do.

You can disable the implicitly imported namespaces feature for all SDKs by removing the <ImplicitUsings> element completely from the project file, or changing its value to disable, as shown in the following markup:

<ImplicitUsings>disable</ImplicitUsings>

Good Practice: You might choose to do this if you want to manually create a single file with all the global using statements instead of potentially having one generated automatically and others created manually. But my recommendation is to leave the feature enabled and modify the project file to change what is included in the auto-generated class file in the obj folder hierarchy.

Verbs are methods

In English, verbs are doing or action words, like "run" and "jump." In C#, doing or action words are called methods. There are hundreds of thousands of methods available to C#. In English, verbs change how they are written based on when in time the action happens. For example, Amir was jumping in the past, Beth jumps in the present, they jumped in the past, and Charlie will jump in the future.In C#, methods such as WriteLine change how they are called or executed based on the specifics of the action. This is called overloading, which we'll cover in more detail in Chapter 5, Building Your Own Types with Object-Oriented Programming. But for now, consider the following example:

// Outputs the current line terminator.
// By default, this is a carriage-return and line feed.
Console.WriteLine();
// Outputs the greeting and the current line terminator.
Console.WriteLine("Hello Ahmed");
// Outputs a formatted number and date and the current line terminator.
Console.WriteLine( 
  "Temperature on {0:D} is {1}°C.", DateTime.Today, 23.4);

When I show code snippets without numbered step-by-step instructions, I do not expect you to enter them as code, so they won’t execute out of context .

A different and not-quite-exact analogy is that some verbs are spelled the same but have different effects depending on the context, for example, you can lose a game, lose your place in a book, or lose your keys.

Nouns are types, variables, fields, and properties

In English, nouns are names that refer to things. For example, Fido is the name of a dog. The word "dog" tells us the type of thing that Fido is, and so to order Fido to fetch a ball, we would use his name.In C#, their equivalents are types, variables, fields, and properties. For example:

• Animal and Car are types; they are nouns for categorizing things.
• Head and Engine might be fields or properties; they are nouns that belong to Animal and Car.
• Fido and Bob are variables; they are nouns for referring to a specific object.

There are tens of thousands of types available to C#, though have you noticed how I didn't say, "There are tens of thousands of types in C#?" The difference is subtle but important. The language of C# only has a few keywords for types, such as string and int, and strictly speaking, C# doesn't define any types. Keywords such as string that look like types are aliases, which represent types provided by the platform on which C# runs.It's important to know that C# cannot exist alone; after all, it's a language that runs on variants of .NET. In theory, someone could write a compiler for C# that uses a different platform, with different underlying types. In practice, the platform for C# is .NET, which provides tens of thousands of types to C#, including System.Int32, which is the C# keyword alias int maps to, as well as many more complex types, such as System.Xml.Linq.XDocument.It's worth taking note that the term type is often confused with class. Have you ever played the parlor game Twenty Questions, also known as Animal, Vegetable, or Mineral? In the game, everything can be categorized as an animal, vegetable, or mineral. In C#, every type can be categorized as a class, struct, enum, interface, or delegate. You will learn what these mean in Chapter 6, Implementing Interfaces and Inheriting Classes. As an example, the C# keyword string is a class, but int is a struct. So, it is best to use the term type to refer to both.

Revealing the extent of the C# vocabulary

We know that there are more than 100 keywords in C#, but how many types are there? Let's write some code to find out how many types (and their methods) are available to C# in our simple console app.Don't worry about exactly how this code works for now, but know that it uses a technique called reflection:

1. Comment out all the existing statements in Program.cs.
2. We'll start by importing the System.Reflection namespace at the top of the Program.cs file so that we can use some of the types in that namespace like Assembly and TypeName, as shown in the following code:

using System.Reflection; // To use Assembly, TypeName, and so on.

Good Practice: We could use the implicit imports and global using features to import this namespace for all .cs files in this project, but since there is only one file, it is better to import the namespace in the one file in which it is needed.

1. Write statements to get the compiled console app and loop through all the types that it has access to, outputting the names and number of methods each has, as shown in the following code:

// Get the assembly that is the entry point for this app.
Assembly? myApp = Assembly.GetEntryAssembly();
// If the previous line returned nothing then end the app.
if (myApp is null) return;
// Loop through the assemblies that my app references.
foreach (AssemblyName name in myApp.GetReferencedAssemblies())
{
  // Load the assembly so we can read its details.
  Assembly a = Assembly.Load(name);
  // Declare a variable to count the number of methods.
  int methodCount = 0;
  // Loop through all the types in the assembly.
  foreach (TypeInfo t in a.DefinedTypes)
  {
    // Add up the counts of all the methods.
    methodCount += t.GetMethods().Length;
  }
  // Output the count of types and their methods.
  WriteLine("{0:N0} types with {1:N0} methods in {2} assembly.",
    arg0: a.DefinedTypes.Count(),
    arg1: methodCount, 
    arg2: name.Name);
}

N0 is uppercase N followed by the digit zero. It is not uppercase N followed by uppercase O. It means “format a number (N) with zero (0) decimal places”.

1. Run the project. You will see the actual number of types and methods that are available to you in the simplest application when running on your operating system (OS). The number of types and methods displayed will be different depending on the OS that you are using, as shown in the following output on Windows:

0 types with 0 methods in System.Runtime assembly.
41 types with 639 methods in System.Console assembly.
112 types with 1,190 methods in System.Linq assembly.

Why does the System.Runtime assembly contain zero types? This assembly is special because it contains only type-forwarders rather than actual types. A type-forwarder represents a type that has been implemented outside of .NET or for some other advanced reason.

1. Add statements to the top of the file (after importing the System.Reflection namespace) to declare some variables, as shown in the following code:

// Declare some unused variables using types in
// additional assemblies to make them load too.
System.Data.DataSet ds = new();
HttpClient client = new();

1. Run the console app again and view the results, which should look like the following outputs:

0 types with 0 methods in System.Runtime assembly.
406 types with 7,139 methods in System.Data.Common assembly.
425 types with 4,681 methods in System.Net.Http assembly.
41 types with 639 methods in System.Console assembly.
112 types with 1,190 methods in System.Linq assembly.

Now, you have a better sense of why learning C# is a challenge – because there are so many types and methods to learn. Methods are only one category of a member that a type can have, and you and other programmers are constantly defining new types and members!

Example of asking ChatGPT to explain code

The code we wrote in the Vocabulary project is a good example of when you might want to ask ChatGPT to explain something. If you enter a prompt of "Explain the following code:" followed by the code, here's what it responded with at the time of writing in July 2023:"This C# code performs an analysis of the assemblies (essentially libraries or modules) referenced by the current application. It tallies up the total number of types and methods in each referenced assembly.Let's break down the code in more detail:

1. System.Reflection namespace is used to work with assemblies, modules, types, methods, and so on, at runtime.
2. The System.Data.DataSet and HttpClient instances are declared but not used. The comment implies that these are declared to ensure their respective assemblies are loaded for the subsequent analysis. Creating instances of classes from certain assemblies can cause those assemblies to be loaded into memory.
3. Assembly.GetEntryAssembly() gets the assembly that is the entry point of the application.
4. If myApp is null (meaning there's no entry assembly, which should be impossible in a normally running .NET app), the application exits.
5. The foreach loop iterates over each assembly name in the referenced assemblies of the entry point assembly.
6. Assembly.Load(name) loads an assembly given the assembly name. This allows you to interact with the assembly programmatically.
7. A counter variable methodCount is declared and initialized to 0. This is used to count the total number of methods in the assembly.
8. Another nested foreach loop then iterates over each type in the assembly.
9. For each type, it gets the number of methods (t.GetMethods().Length) and adds it to the methodCount.
10. Finally, the number of types and their methods in the assembly are output to the console using WriteLine(). The {0:N0} format specifier in the string is a placeholder for a number (0 refers to the argument index, N is for number format, and 0 after N specifies the number of decimal places).

So, in essence, this script counts how many types and methods exist in each assembly referenced by the application. This might be useful to understand the complexity or size of the dependencies the application has."And now back to the flesh and blood Mark: That's a pretty good explanation with no mistakes or hallucinations!

Good Practice: Tools like GitHub Copilot and ChatGPT are especially useful for programmers when they are learning new things. And a good programmer is always learning new things! These tools are not just for writing code for you. They can explain existing code written by others and even suggest improvements.

Naming things and assigning values

There are naming conventions for things, and it is a good practice to follow them, as shown in Table 2.20:

Table 2.20: Naming conventions and what they should be used for

Some C# programmers like to prefix the names of private fields with an underscore, for example, _dateOfBirth instead of dateOfBirth. The naming of private members of all kinds is not formally defined because they will not be visible outside the class, so writing them with or without an underscore prefix are both valid.

Good Practice: Following a consistent set of naming conventions will enable your code to be easily understood by other developers (and yourself in the future!).

The following code block shows an example of declaring a named local variable and assigning a value to it with the = symbol. You should note that you can output the name of a variable using a keyword introduced in C# 6, nameof:

// Let the heightInMetres variable become equal to the value 1.88.
double heightInMetres = 1.88;
Console.WriteLine($"The variable {nameof(heightInMetres)} has the value
{heightInMetres}.");

Warning! The message in double quotes in the preceding code wraps onto a second line because the width of a printed page is too narrow. When entering a statement like this in your code editor, type it all in a single line.

In C# 12, nameof can now access instance data from a static context. You will learn the difference between instance and static data in Chapter 5, Building Your Own Types with Object-Oriented Programming.

Literal values

When you assign to a variable, you often, but not always, assign a literal value. But what is a literal value? A literal is a notation that represents a fixed value. Data types have different notations for their literal values, and over the next few sections, you will see examples of using literal notation to assign values to variables.

More Information: You can read the formal definition of literals in the C# language specification: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/lexical-structure#645-literals.

Storing text

For text, a single letter, such as an A, is stored as a char type.

Good Practice: Actually, it can be more complicated than that. Egyptian Hieroglyph A002 (U+13001) needs two System.Char values (known as surrogate pairs) to represent it: \uD80C and \uDC01. Do not always assume one char equals one letter or you could introduce hard-to-notice bugs into your code.

A char is assigned using single quotes around the literal value, or assigning the return value of a function call, as shown in the following code:

char letter = 'A'; // Assigning literal characters.
char digit = '1'; 
char symbol = '$';
char userChoice = GetChar(); // Assigning from a fictitious function.

For text, multiple letters, such as Bob, are stored as a string type and are assigned using double quotes around the literal value, or by assigning the return value of a function call or constructor, as shown in the following code:

string firstName = "Bob"; // Assigning literal strings.
string lastName = "Smith";
string phoneNumber = "(215) 555-4256";
// Assigning a string returned from the string class constructor.
string horizontalLine = new('-', count: 74); // 74 hyphens.
// Assigning a string returned from a fictitious function.
string address = GetAddressFromDatabase(id: 563);
// Assigning an emoji by converting from Unicode.
string grinningEmoji = char.ConvertFromUtf32(0x1F600);

Console.OutputEncoding = System.Text.Encoding.UTF8;
string grinningEmoji = char.ConvertFromUtf32(0x1F600);
Console.WriteLine(grinningEmoji);

string fullNameWithTabSeparator = "Bob\tSmith";

string filePath = "C:\televisions\sony\bravia.txt";

string filePath = @"C:\televisions\sony\bravia.txt";

string xml = """
             <person age="50">
               <first_name>Mark</first_name>
             </person>
             """;

<person age="50">
  <first_name>Mark</first_name>
</person>

string xml = """
             <person age="50">
               <first_name>Mark</first_name>
             </person>
""";

             <person age="50">
               <first_name>Mark</first_name>
             </person>

var person = new { FirstName = "Alice", Age = 56 };
string json = $$"""
              {
                "first_name": "{{person.FirstName}}",
                "age": {{person.Age}},
                "calculation": "{{{ 1 + 2 }}}"
              }
              """;
Console.WriteLine(json);

{
  "first_name": "Alice",
  "age": 56,
  "calculation": "{3}"
}

Storing numbers

Numbers are data that we want to perform an arithmetic calculation on, for example, multiplying. A telephone number is not a number. To decide whether a variable should be stored as a number or not, ask yourself whether you need to perform arithmetic operations on the number or whether the number includes non-digit characters such as parentheses or hyphens to format the number, such as (414) 555-1234. In this case, the "number" is a sequence of characters, so it should be stored as a string.Numbers can be natural numbers, such as 42, used for counting (also called whole numbers); they can also be negative numbers, such as -42 (called integers); or they can be real numbers, such as 3.9 (with a fractional part), which are called single- or double-precision floating-point numbers in computing.Let's explore numbers:

1. Use your preferred code editor to add a new Console App / console project named Numbers to the Chapter02 solution.
   • For Visual Studio 2022, configure the startup project to the current selection.
2. In Program.cs, delete the existing code, and then type statements to declare some number variables using various data types, as shown in the following code:

// An unsigned integer is a positive whole number or 0.
uint naturalNumber = 23;
// An integer is a negative or positive whole number or 0.
int integerNumber = -23;
// A float is a single-precision floating-point number.
// The F or f suffix makes the value a float literal.
// The suffix is required to compile.
float realNumber = 2.3f;
// A double is a double-precision floating-point number.
// double is the default for a number value with a decimal point.
double anotherRealNumber = 2.3; // A double literal value.

Storing whole numbers

You might know that computers store everything as bits. The value of a bit is either 0 or 1. This is called a binary number system. Humans use a decimal number system.The decimal number system, also known as Base 10, has 10 as its base, meaning there are 10 digits, from 0 to 9. Although it is the number base most used by human civilizations, other number base systems are popular in science, engineering, and computing. The binary number system, also known as Base 2, has two as its base, meaning there are two digits, 0 and 1.The following image shows how computers store the decimal number 10. Take note of the bits with the value 1 in the 8 and 2 columns; 8 + 2 = 10:

So, 10 in decimal is 00001010 in a binary byte (8 bits).

int decimalNotation = 2_000_000;
int binaryNotation = 0b_0001_1110_1000_0100_1000_0000; 
int hexadecimalNotation = 0x_001E_8480;
// Check the three variables have the same value.
Console.WriteLine($"{decimalNotation == binaryNotation}"); 
Console.WriteLine(
  $"{decimalNotation == hexadecimalNotation}");
// Output the variable values in decimal.
Console.WriteLine($"{decimalNotation:N0}");
Console.WriteLine($"{binaryNotation:N0}");
Console.WriteLine($"{hexadecimalNotation:N0}");
// Output the variable values in hexadecimal.
Console.WriteLine($"{decimalNotation:X}");
Console.WriteLine($"{binaryNotation:X}");
Console.WriteLine($"{hexadecimalNotation:X}");

True
True
2,000,000
2,000,000
2,000,000
1E8480
1E8480
1E8480

Storing real numbers

Computers cannot always represent real, aka decimal or non-integer, numbers precisely. The float and double types store real numbers using single- and double-precision floating points.Most programming languages implement the Institute of Electrical and Electronics Engineers (IEEE) Standard for Floating-Point Arithmetic. IEEE 754 is a technical standard for floating-point arithmetic established in 1985 by the IEEE.The following image shows a simplification of how a computer represents the number 12.75 in binary notation. Note the bits with the value 1 in the 8, 4, ½, and ¼ columns.8 + 4 + ½ + ¼ = 12¾ = 12.75.

So, 12.75 in decimal is 00001100.1100 in binary. As you can see, the number 12.75 can be exactly represented using bits. However, most numbers can’t, which is something that we’ll be exploring shortly.

Writing code to explore number sizes

C# has an operator named sizeof() that returns the number of bytes that a type uses in memory. Some types have members named MinValue and MaxValue, which return the minimum and maximum values that can be stored in a variable of that type. We are now going to use these features to create a console app to explore number types:

1. In Program.cs, at the bottom of the file, type statements to show the size of three number data types, as shown in the following code:

Console.WriteLine($"int uses {sizeof(int)} bytes and can store numbers in the range {int.MinValue:N0} to {int.MaxValue:N0}."); 
Console.WriteLine($"double uses {sizeof(double)} bytes and can store numbers in the range {double.MinValue:N0} to {double.MaxValue:N0}."); 
Console.WriteLine($"decimal uses {sizeof(decimal)} bytes and can store numbers in the range {decimal.MinValue:N0} to {decimal.MaxValue:N0}.");

Warning! The width of the printed pages in this book makes the string values (in double quotes) wrap over multiple lines. You must type them on a single line, or you will get compile errors.

1. Run the code and view the output, as shown in Figure 2.6:

An int variable uses four bytes of memory and can store positive or negative numbers up to about 2 billion. A double variable uses 8 bytes of memory and can store much bigger values! A decimal variable uses 16 bytes of memory and can store big numbers, but not as big as a double type.But you may be asking yourself, why might a double variable be able to store bigger numbers than a decimal variable, yet it’s only using half the space in memory? Well, let’s now find out!

Comparing double and decimal types

You will now write some code to compare double and decimal values. Although it isn’t hard to follow, don’t worry about understanding the syntax right now:

1. Type statements to declare two double variables, add them together, and compare them to the expected result. Then, write the result to the console, as shown in the following code:

Console.WriteLine("Using doubles:"); 
double a = 0.1;
double b = 0.2;
if (a + b == 0.3)
{
  Console.WriteLine($"{a} + {b} equals {0.3}");
}
else
{
  Console.WriteLine($"{a} + {b} does NOT equal {0.3}");
}

1. Run the code and view the result, as shown in the following output:

Using doubles:
0.1 + 0.2 does NOT equal 0.3

In cultures that use a comma for the decimal separator, the result will look slightly different, as shown in the following output: 0,1 + 0,2 does NOT equal 0,3.

The double type is not guaranteed to be accurate because most numbers like 0.1, 0.2, and 0.3 literally cannot be exactly represented as floating-point values.If you were to try different values like 0.1 + 0.3 == 0.4 it would happen to return true because with double values, some imprecise values happen to be exactly equal in their current representation even though they might not actually be equal mathematically. So, some numbers can be directly compared but some cannot. I deliberately picked 0.1 and 0.2 to compare to 0.3 because they cannot be compared, as proven by the result.You could compare real numbers stored in the float type, which is less accurate than the double type, but the comparison would actual appear to be true because of that lower accuracy!

float a = 0.1F;
float b = 0.2F;
if (a + b == 0.3F) // True because float is less "accurate" than double.
...

As a rule of thumb, you should only use double when accuracy, especially when comparing the equality of two numbers, is not important. An example of this might be when you're measuring a person's height; you will only compare values using greater than or less than, but never equals.The problem with the preceding code is illustrated by how the computer stores the number 0.1, or multiples of it. To represent 0.1 in binary, the computer stores 1 in the 1/16 column, 1 in the 1/32 column, 1 in the 1/256 column, 1 in the 1/512 column, and so on.The number 0.1 in decimal is 0.00011001100110011… in binary, repeating forever:

Good Practice: Never compare double values using ==. During the First Gulf War, an American Patriot missile battery used double values in its calculations. The inaccuracy caused it to fail to track and intercept an incoming Iraqi Scud missile, and 28 soldiers were killed; you can read about this at https://www.ima.umn.edu/~arnold/disasters/patriot.xhtml. The Patriot missile system has improved since then. "Forty years after it was brought into service, the Patriot air-defense system is finally doing what it was designed for." "No one was 100% sure that the Patriot was capable of destroying a Kh-47 hypersonic missile," said Col. Serhiy Yaremenko, commander of the 96th Anti-Aircraft Missile Brigade, which defends Kyiv. "Ukrainians proved it.": https://archive.ph/2023.06.11-132200/https://www.wsj.com/amp/articles/u-s-patriot-missile-is-an-unsung-hero-of-ukraine-war-db6053a0.

Now let's see the same code using the decimal number type:

1. Copy and paste the statements that you wrote before (which used the double variables).
2. Modify the statements to use decimal and rename the variables to c and d, as shown in the following code:

Console.WriteLine("Using decimals:");
decimal c = 0.1M; // M suffix means a decimal literal value
decimal d = 0.2M;
if (c + d == 0.3M)
{
  Console.WriteLine($"{c} + {d} equals {0.3M}");
}
else
{
  Console.WriteLine($"{c} + {d} does NOT equal {0.3M}");
}

1. Run the code and view the result, as shown in the following output:

Using decimals:
0.1 + 0.2 equals 0.3

The decimal type is accurate because it stores the number as a large integer and shifts the decimal point. For example, 0.1 is stored as 1, with a note to shift the decimal point one place to the left. 12.75 is stored as 1275, with a note to shift the decimal point two places to the left.

Good Practice: Use int for whole numbers. Use double for real numbers that will not be compared for equality to other values; it is okay to compare double values being less than or greater than, and so on. Use decimal for money, CAD drawings, general engineering, and wherever the accuracy of a real number is important.

The float and double types have some useful special values: NaN represents not-a-number (for example, the result of dividing by zero), Epsilon represents the smallest positive number that can be stored in a float or double, and PositiveInfinity and NegativeInfinity represent infinitely large positive and negative values. They also have methods for checking for these special values like IsInfinity and IsNaN.

unsafe
{
  Console.WriteLine($"Half uses {sizeof(Half)} bytes and can store numbers in the range {Half.MinValue:N0} to {Half.MaxValue:N0}."); 
  Console.WriteLine($"Int128 uses {sizeof(Int128)} bytes and can store numbers in the range {Int128.MinValue:N0} to {Int128.MaxValue:N0}.");
}

<PropertyGroup>
  <OutputType>Exe</OutputType>
  <TargetFramework>net8.0</TargetFramework>
  <ImplicitUsings>enable</ImplicitUsings>
  <Nullable>enable</Nullable>
  <AllowUnsafeBlocks>True</AllowUnsafeBlocks>
</PropertyGroup>

Half uses 2 bytes and can store numbers in the range -65,504 to 65,504.
Int128 uses 16 bytes and can store numbers in the range -170,141,183,460,469,231,731,687,303,715,884,105,728 to 170,141,183,460,469,231,731,687,303,715,884,105,727.

Storing Booleans

Booleans can only contain one of the two literal values true or false, as shown in the following code:

bool happy = true; 
bool sad = false;

They are most used to branch and loop. You don't need to fully understand them yet, as they are covered more in Chapter 3, Controlling Flow, Converting Types, and Handling Exceptions.

Storing any type of object

There is a special type named object that can store any type of data, but its flexibility comes at the cost of messier code and possibly poor performance. Because of those two reasons, you should avoid it whenever possible. The following steps show you how to use object types if you need to use them because you must use a Microsoft or third-party library that uses them:

1. Use your preferred code editor to add a new Console App / console project named Variables to the Chapter02 solution.
2. In Program.cs, delete the existing statements and then type statements to declare and use some variables using the object type, as shown in the following code:

object height = 1.88; // Storing a double in an object.
object name = "Amir"; // Storing a string in an object.
Console.WriteLine($"{name} is {height} metres tall.");
int length1 = name.Length; // This gives a compile error!
int length2 = ((string)name).Length; // Cast name to a string.
Console.WriteLine($"{name} has {length2} characters.");

1. Run the code and note that the fourth statement cannot compile because the data type of the name variable is not known by the compiler, as shown in Figure 2.8:

   

2. Add double slashes to the beginning of the statement that cannot compile to comment out the statement, making it inactive.
3. Run the code again and note that the compiler can access the length of a string if the programmer explicitly tells the compiler that the object variable contains a string by prefixing name variable with a cast expression like (string)name. The results can then successfully be written to the console, as shown in the following output:

Amir is 1.88 meters tall.
Amir has 4 characters.

You will learn about cast expressions in Chapter 3, Controlling Flow, Converting Types, and Handling Exceptions.The object type has been available since the first version of C#, but C# 2 and later have a better alternative called generics, which we will cover in Chapter 6, Implementing Interfaces and Inheriting Classes. This will provide us with the flexibility we want but without the performance overhead.

Storing dynamic types

There is another special type named dynamic that can also store any type of data, but even more than object, its flexibility comes at the cost of performance. The dynamic keyword was introduced in C# 4. However, unlike object, the value stored in the variable can have its members invoked without an explicit cast. Let's make use of a dynamic type:

1. Add statements to declare a dynamic variable. Assign a string literal value, and then an integer value, and then an array of integer values. Finally, add a statement to output the length of the dynamic variable, as shown in the following code:

dynamic something;
// Storing an array of int values in a dynamic object.
// An array of any type has a Length property.
something = new[] { 3, 5, 7 };
// Storing an int in a dynamic object.
// int does not have a Length property.
something = 12;
// Storing a string in a dynamic object.
// string has a Length property.
something = "Ahmed";
// This compiles but might throw an exception at run-time.
Console.WriteLine($"The length of something is {something.Length}");
// Output the type of the something variable.
Console.WriteLine($"something is a {something.GetType()}");

You will learn about arrays in Chapter 3, Controlling Flow, Converting Types, and Handling Exceptions.

1. Run the code and note it works because a string value does have a Length property, as shown in the following output:

The length of something is 5
something is a System.String

1. Comment out the statement that assigns a string value to the something variable by prefixing the statement with two slashes //.
2. Run the code and note the runtime error because the last value assigned to something is an int that does not have a Length property, as shown in the following output:

Unhandled exception. Microsoft.CSharp.RuntimeBinder.RuntimeBinderException: 'int' does not contain a definition for 'Length'

1. Comment out the statement that assigns an int to the something variable.
2. Run the code and note the output because an array of three int values does have a Length property, as shown in the following output:

The length of something is 3
something is a System.Int32[]

One limitation of dynamic is that code editors cannot show IntelliSense to help you write the code. This is because the compiler cannot check what the type is during build time. Instead, the CLR checks for the member at runtime and throws an exception if it is missing.Exceptions are a way to indicate that something has gone wrong at runtime. You will learn more about them and how to handle them in Chapter 3, Controlling Flow, Converting Types, and Handling Exceptions.Dynamic types are most useful when interoperating with non-.NET systems. For example, you might need to work with a class library written in F#, Python, or some JavaScript. You might also need to interop with technologies like the Component Object Model (COM), for example, when automating Excel or Word.

Declaring local variables

Local variables are declared inside methods, and they only exist during the execution of that method. Once the method returns, the memory allocated to any local variables is released.Strictly speaking, value types are released while reference types must wait for garbage collection. You will learn about the difference between value types and reference types and how to make sure that only one garbage collection is needed rather than two when releasing unmanaged resources in Chapter 6, Implementing Interfaces and Inheriting Classes.

int population = 67_000_000; // 67 million in UK.
double weight = 1.88; // in kilograms.
decimal price = 4.99M; // in pounds sterling.
string fruit = "Apples"; // string values use double-quotes.
char letter = 'Z'; // char values use single-quotes.
bool happy = true; // Booleans can only be true or false.

var population = 67_000_000; // 67 million in UK.
var weight = 1.88; // in kilograms.
var price = 4.99M; // in pounds sterling.
var fruit = "Apples"; // string values use double-quotes.
var letter = 'Z'; // char values use single-quotes.
var happy = true; // Booleans can only be true or false.

using System.Xml; // To use XmlDocument.

// Good use of var because it avoids the repeated type
// as shown in the more verbose second statement.
var xml1 = new XmlDocument(); // Works with C# 3 and later.
XmlDocument xml2 = new XmlDocument(); // Works with all C# versions.
// Bad use of var because we cannot tell the type, so we
// should use a specific type declaration as shown in
// the second statement.
var file1 = File.CreateText("something1.txt"); 
StreamWriter file2 = File.CreateText("something2.txt");

XmlDocument xml3 = new(); // Target-typed new in C# 9 or later.

// In Program.cs.
Person kim = new();
kim.BirthDate = new(1967, 12, 26); // i.e. new DateTime(1967, 12, 26)
// In a separate Person.cs file or at the bottom of Program.cs.
class Person
{
  public DateTime BirthDate;
}

List<Person> people = new() // Instead of: new List<Person>()
{
  new() { FirstName = "Alice" }, // Instead of: new Person() { ... }
  new() { FirstName = "Bob" },
  new() { FirstName = "Charlie" }
};

Getting and setting the default values for types

Most of the primitive types except string are value types, which means that they must have a value. You can determine the default value of a type by using the default() operator and passing the type as a parameter. You can assign the default value of a type by using the default keyword.The string type is a reference type. This means that string variables contain the memory address of a value, not the value itself. A reference type variable can have a null value, which is a literal that indicates that the variable does not reference anything (yet). null is the default for all reference types.You'll learn more about value types and reference types in Chapter 6, Implementing Interfaces and Inheriting Classes.Let's explore default values:

1. Add statements to show the default values of an int, a bool, a DateTime, and a string, as shown in the following code:

Console.WriteLine($"default(int) = {default(int)}"); 
Console.WriteLine($"default(bool) = {default(bool)}"); 
Console.WriteLine($"default(DateTime) = {default(DateTime)}"); 
Console.WriteLine($"default(string) = {default(string)}");

1. Run the code and view the result. Note that your output for the date and time might be formatted differently if you are not running it in the UK because date and time values are formatted using the current culture of your computer, and that null values output as an empty string, as shown in the following output:

default(int) = 0 
default(bool) = False
default(DateTime) = 01/01/0001 00:00:00 
default(string) =

1. Add statements to declare a number, assign a value, and then reset it to its default value, as shown in the following code:

int number = 13;
Console.WriteLine($"number set to: {number}");
number = default;
Console.WriteLine($"number reset to its default: {number}");

1. Run the code and view the result, as shown in the following output:

number set to: 13
number reset to its default: 0

Displaying output to the user

The two most common tasks that a console app performs are writing and reading data. We have already used the WriteLine method to output, but if we didn't want a carriage return at the end of a line, for example, if we later wanted to continue to write more text at the end of that line, we could have used the Write method.If you want to write three letters to the console without carriage returns after them, then call the Write method, as shown in the following code:

Write("A");
Write("B");
Write("C");

This would write the three characters on a single line and leave the cursor at the end of the line, as shown in the following output:

ABC

If you want to write three letters to the console with carriage returns after them, then call the WriteLine method, as shown in the following code:

WriteLine("A");
WriteLine("B");
WriteLine("C");

This would write three lines and leave the cursor on the fourth line:

A
B
C

int numberOfApples = 12; 
decimal pricePerApple = 0.35M;
Console.WriteLine(
  format: "{0} apples cost {1:C}", 
  arg0: numberOfApples,
  arg1: pricePerApple * numberOfApples);
string formatted = string.Format(
  format: "{0} apples cost {1:C}",
  arg0: numberOfApples,
  arg1: pricePerApple * numberOfApples);
//WriteToFile(formatted); // Writes the string into a file.

// Three parameter values can use named arguments.
Console.WriteLine("{0} {1} lived in {2}.", 
  arg0: "Roger", arg1: "Cevung", arg2: "Stockholm");
// Four or more parameter values cannot use named arguments.
Console.WriteLine(
  "{0} {1} lived in {2} and worked in the {3} team at {4}.", 
  "Roger", "Cevung", "Stockholm", "Education", "Optimizely");

// The following statement must be all on one line when using C# 10
// or earlier. If using C# 11 or later, we can include a line break
// in the middle of an expression but not in the string text.
Console.WriteLine($"{numberOfApples} apples cost {pricePerApple 
  * numberOfApples:C}");

12 apples cost £4.20

private const string firstname = "Omar";
private const string lastname = "Rudberg";
private const string fullname = firstname + " " + lastname;

private const string fullname = $"{firstname} {lastname}";

{ index [, alignment ] [ : formatString ] }

string applesText = "Apples"; 
int applesCount = 1234;
string bananasText = "Bananas"; 
int bananasCount = 56789;
Console.WriteLine();
Console.WriteLine(format: "{0,-10} {1,6}",
  arg0: "Name", arg1: "Count");
Console.WriteLine(format: "{0,-10} {1,6:N0}",
  arg0: applesText, arg1: applesCount);
Console.WriteLine(format: "{0,-10} {1,6:N0}",
  arg0: bananasText, arg1: bananasCount);

Name          Count
Apples        1,234
Bananas      56,789

Getting text input from the user

We can get text input from the user using the ReadLine method. This method waits for the user to type some text. Then, as soon as the user presses Enter, whatever the user has typed is returned as a string value.Let's get input from the user:

1. Type statements to ask the user for their name and age and then output what they entered, as shown in the following code:

Console.Write("Type your first name and press ENTER: "); 
string firstName = Console.ReadLine();
Console.Write("Type your age and press ENTER: "); 
string age = Console.ReadLine();
Console.WriteLine($"Hello {firstName}, you look good for {age}.");

By default, with .NET 6 and later, nullability checks are enabled, so the C# compiler gives two warnings because the ReadLine method could return a null value instead of a string value. But there is no scenario where this method would actually return null, so instead we will see how to switch off these specific warnings in this scenario.

1. For the firstName variable, append a ? after string, as shown highlighted in the following code:

string? firstName = Console.ReadLine();

This tells the compiler that we are expecting a possible null value, so it does not need to warn us. If the variable is null then when it is later output with WriteLine, it will just be blank, so that works fine in this case. If we were going to access any of the members of the firstName variable, then we would need to handle the case where it is null.

1. For the age variable, append a ! before the semi-colon at the end of the statement, as shown highlighted in the following code:

string age = Console.ReadLine()!;

This is called the null-forgiving operator because it tells the compiler that, in this case, ReadLine will not return null, so it can stop showing the warning. It is now our responsibility to ensure this is the case. Luckily, the Console type's implementation of ReadLine always returns a string even if it is just an empty string value.

1. Run the code, and then enter a name and age, as shown in the following output:

Type your name and press ENTER: Gary 
Type your age and press ENTER: 34 
Hello Gary, you look good for 34.

You have now seen two common ways to handle nullability warnings from the compiler. We will cover nullability and how to handle it in more detail in Chapter 6, Implementing Interfaces and Inheriting Classes.

Simplifying the usage of the console

In C# 6 and later, the using statement can be used not only to import a namespace but also to further simplify our code by importing a static class. Then, we won't need to enter the Console type name throughout our code.

using static System.Console;

<ItemGroup>
  <Using Include="System.Console" Static="true" />
</ItemGroup>

Getting key input from the user

We can get key input from the user using the ReadKey method. This method waits for the user to press a key or key combination, which is then returned as a ConsoleKeyInfo value.Let's explore reading key presses:

1. Type statements to ask the user to press any key combination and then output information about it, as shown in the following code:

Write("Press any key combination: "); 
ConsoleKeyInfo key = ReadKey(); 
WriteLine();
WriteLine("Key: {0}, Char: {1}, Modifiers: {2}",
  arg0: key.Key, arg1: key.KeyChar, arg2: key.Modifiers);

1. Run the code, press the K key, and note the result, as shown in the following output:

Press any key combination: k 
Key: K, Char: k, Modifiers: 0

1. Run the code, hold down Shift and press the K key, and note the result, as shown in the following output:

Press any key combination: K  
Key: K, Char: K, Modifiers: Shift

1. Run the code, press the F12 key, and note the result, as shown in the following output:

Press any key combination: 
Key: F12, Char: , Modifiers: 0

Warning! When running a console app in a terminal within Visual Studio Code, some keyboard combinations will be captured by the code editor before they can be processed by your console app. For example, Ctrl + Shift + X in Visual Studio Code activates the Extensions view in the sidebar. To fully test this console app, open a command prompt or terminal in the project folder and run the console app from there.

Passing arguments to a console app

When you run a console app, you often want to change its behavior by passing arguments. For example, with the dotnet command-line tool, you can pass the name of a new project template, as shown in the following commands:

dotnet new console
dotnet new mvc

You might have been wondering how to get any arguments that might be passed to a console app.In every version of .NET prior to version 6, the console app project template made it obvious, as shown in the following code:

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

The string[] args arguments are declared and passed in the Main method of the Program class. They're an array used to pass arguments into a console app. But in top-level programs, as used by the console app project template in .NET 6 and later, the Program class and its Main method are hidden, along with the declaration of the args array. The trick is that you must know it still exists.Command-line arguments are separated by spaces. Other characters like hyphens and colons are treated as part of an argument value.To include spaces in an argument value, enclose the argument value in single or double quotes.Imagine that we want to be able to enter the names of some colors for the foreground and background and the dimensions of the terminal window at the command line. We would be able to read the colors and numbers by reading them from the args array, which is always passed into the Main method, aka the entry point of a console app:

1. Use your preferred code editor to add a new Console App / console project named Arguments to the Chapter02 solution.
2. Open Arguments.csproj, and after the <PropertyGroup> section, add a new <ItemGroup> section to statically import System.Console for all C# files using the implicit usings .NET SDK feature, as shown in the following markup:

<ItemGroup>
  <Using Include="System.Console" Static="true" />
</ItemGroup>

Good Practice: Remember to use the implicit usings .NET SDK feature to statically import the System.Console type in all future console app projects to simplify your code, as these instructions will not be repeated every time.

1. In Program.cs, delete the existing statements, and then add a statement to output the number of arguments passed to the application, as shown in the following code:

WriteLine($"There are {args.Length} arguments.");

1. Run the console app and view the result, as shown in the following output:

There are 0 arguments.

If you are using Visual Studio 2022 for Windows:

1. Navigate to Project | Arguments Properties.

2. Select the Debug tab, click Open debug launch profiles UI, and in the Command line arguments box, enter the following arguments: firstarg second-arg third:arg "fourth arg", as shown in Figure 2.10:

   

3. Close the Launch Profiles window.
4. In Solution Explorer, in the Properties folder, open the launchSettings.json file and note it defines the command-line arguments when you run the project, as shown highlighted in the following configuration:

{
  "profiles": {
    "Arguments": {
      "commandName": "Project",
      "commandLineArgs": "firstarg second-arg third:arg \"fourth arg\""
    }
  }
}

The launchSettings.json file can also be used by JetBrains Rider. The equivalent for Visual Studio Code is the .vscode/launch.json file.

1. Run the console app project.

If you are using JetBrains Rider:

1. Right-click the Arguments project.
2. In the popup menu, select More Run/Debug | Modify Run Configuration….

3. In the Edit Run Configuration: 'Arguments' dialog box, in the Program arguments box, enter firstarg second-arg third:arg "fourth arg", as shown in Figure 2.11:

   

4. Click OK.
5. Run the console app.

If you are using Visual Studio Code:

• In Terminal, enter some arguments after the dotnet run command, as shown in the following command:

dotnet run firstarg second-arg third:arg "fourth arg"

For all code editors:

1. Note the result indicates four arguments, as shown in the following output:

There are 4 arguments.

1. In Program.cs, to enumerate or iterate (that is, loop through) the values of those four arguments, add the following statements after outputting the length of the array:

foreach (string arg in args)
{
  WriteLine(arg);
}

1. Run the code again and note the result shows the details of the four arguments, as shown in the following output:

There are 4 arguments. 
firstarg
second-arg 
third:arg 
fourth arg

Setting options with arguments

We will now use these arguments to allow the user to pick a color for the background, foreground, and cursor size of the output window. The cursor size can be an integer value from 1, meaning a line at the bottom of the cursor cell, up to 100, meaning a percentage of the height of the cursor cell.We have statically imported the System.Console class. It has properties like ForegroundColor, BackgroundColor, and CursorSize that we can now set just by using their names without needing to prefix them with Console. The System namespace is already imported so that the compiler knows about the ConsoleColor and Enum types:

1. Add statements to warn the user if they do not enter three arguments, and then parse those arguments and use them to set the color and dimensions of the console window, as shown in the following code:

if (args.Length < 3)
{
  WriteLine("You must specify two colors and cursor size, e.g.");
  WriteLine("dotnet run red yellow 50");
  return; // Stop running.
}
ForegroundColor = (ConsoleColor)Enum.Parse(
  enumType: typeof(ConsoleColor),
  value: args[0], ignoreCase: true);
BackgroundColor = (ConsoleColor)Enum.Parse(
  enumType: typeof(ConsoleColor),
  value: args[1], ignoreCase: true);
CursorSize = int.Parse(args[2]);

Note the compiler warning that setting the CursorSize is only supported on Windows. For now, do not worry about most of this code like (ConsoleColor), Enum.Parse, or typeof, as it will all be explained in the next few chapters.

• If you are using Visual Studio 2022, change the arguments to red yellow 50. Run the console app and note the cursor is half the size and the colors have changed in the window, as shown in Figure 2.12:

  

• If you are using Visual Studio Code, then run the code with arguments to set the foreground color to red, the background color to yellow, and the cursor size to 50%, as shown in the following command:

dotnet run red yellow 50

On macOS or Linux, you'll see an unhandled exception, as shown in Figure 2.13:

Although the compiler did not give an error or warning, at runtime, some API calls may fail on some platforms. Although a console app running on Windows can change its cursor size, on macOS, it cannot, and it complains if you try.

Handling platforms that do not support an API

So how do we solve this problem? We can solve this by using an exception handler. You will learn more details about the try-catch statement in Chapter 3, Controlling Flow, Converting Types, and Handling Exceptions, so for now, just enter the code:

1. Modify the code to wrap the lines that change the cursor size in a try statement, as shown in the following code:

try
{
  CursorSize = int.Parse(args[2]);
}
catch (PlatformNotSupportedException)
{
  WriteLine("The current platform does not support changing the size of the cursor.");
}

If you were to run the code on macOS, then you would see the exception is caught, and a friendlier message is shown to the user.Another way to handle differences in operating systems is to use the OperatingSystem class in the System namespace, as shown in the following code:

if (OperatingSystem.IsWindows())
{
  // Execute code that only works on Windows.
}
else if (OperatingSystem.IsWindowsVersionAtLeast(major: 10))
{
  // Execute code that only works on Windows 10 or later.
}
else if (OperatingSystem.IsIOSVersionAtLeast(major: 14, minor: 5))
{
  // Execute code that only works on iOS 14.5 or later.
}
else if (OperatingSystem.IsBrowser())
{
  // Execute code that only works in the browser with Blazor.
}

The OperatingSystem class has equivalent methods for other common operating systems like Android, iOS, Linux, macOS, and even the browser, which is useful for Blazor web components.A third way to handle different platforms is to use conditional compilation statements.There are four preprocessor directives that control conditional compilation: #if, #elif, #else, and #endif.You define symbols using #define, as shown in the following code:

#define MYSYMBOL

Many symbols are automatically defined for you, as shown in Table 2.23:

Table 2.23: Predefined compiler symbols

You can then write statements that will compile only for the specified platforms, as shown in the following code:

#if NET7_0_ANDROID
// Compile statements that only work on Android.
#elif NET7_0_IOS
// Compile statements that only work on iOS.
#else
// Compile statements that work everywhere else.
#endif

Improving responsiveness for console apps

One of the limitations with console apps is that you can only use the await keyword inside methods that are marked as async, but C# 7 and earlier do not allow the Main method to be marked as async! Luckily, a new feature introduced in C# 7.1 was support for async in Main.Let's see it in action:

1. Use your preferred code editor to add a new Console App / console project named AsyncConsole to the Chapter02 solution.
2. Open AsyncConsole.csproj, and after the <PropertyGroup> section, add a new <ItemGroup> section to statically import System.Console for all C# files using the implicit usings .NET SDK feature, as shown in the following markup:

<ItemGroup>
  <Using Include="System.Console" Static="true" />
</ItemGroup>

1. In Program.cs, delete the existing statements, and then add statements to create an HttpClient instance, make a request for Apple's home page, and output how many bytes it has, as shown in the following code:

HttpClient client = new();
HttpResponseMessage response =
  await client.GetAsync("http://www.apple.com/");
WriteLine("Apple's home page has {0:N0} bytes.",
  response.Content.Headers.ContentLength);

1. Navigate to Build | Build AsyncConsole and note that the project builds successfully.

   In .NET 5 and earlier, you would have seen an error message, as shown in the following output:

   Program.cs(14,9): error CS4033: The 'await' operator can only be used within an async method. Consider marking this method with the 'async' modifier and changing its return type to 'Task'. [/Users/markjprice/Code/ Chapter02/AsyncConsole/AsyncConsole.csproj]

   You would have had to add the async keyword to your Main method and change its return type from void to Task. With .NET 6 and later, the console app project template uses the top-level program feature to automatically define the Program class with an asynchronous <Main>$ method for you.

2. Run the code and view the result, which is likely to have a different number of bytes since Apple changes its home page frequently, as shown in the following output:

Apple's home page has 170,688 bytes.

Exercise 2.1 – Test your knowledge

To get the best answer to some of these questions, you will need to do your own research. I want you to "think outside the book," so I have deliberately not provided all the answers in the book.I want to encourage you to get into the good habit of looking for help elsewhere, following the principle of "teach a person to fish."

1. What statement can you type in a C# file to discover the compiler and language version?
2. What are the two types of comments in C#?
3. What is the difference between a verbatim string and an interpolated string?
4. Why should you be careful when using float and double values?
5. How can you determine how many bytes a type like double uses in memory?
6. When should you use the var keyword?
7. What is the newest syntax to create an instance of a class like XmlDocument?
8. Why should you be careful when using the dynamic type?
9. How do you right-align a format string?
10. What character separates arguments for a console app?

Appendix, Answers to the Test Your Knowledge Questions, is available to download from a link in the README on the GitHub repository: https://github.com/markjprice/cs12dotnet8.

Exercise 2.2 – Test your knowledge of number types

What type would you choose for the following "numbers"?

• A person's telephone number
• A person's height
• A person's age
• A person's salary
• A book's ISBN
• A book's price
• A book's shipping weight
• A country's population
• The number of stars in the universe
• The number of employees in each of the small or medium businesses in the UK (up to about 50,000 employees per business)

Exercise 2.3 – Practice number sizes and ranges

In the Chapter02 solution, create a console app project named Ch02Ex03Numbers that outputs the number of bytes in memory that each of the following number types uses and the minimum and maximum values they can have: sbyte, byte, short, ushort, int, uint, long, ulong, Int128, UInt128, Half, float, double, and decimal.The result of running your console app should look something like Figure 2.14:

Code solutions for all exercises are available to download or clone from the GitHub repository at the following link: https://github.com/markjprice/cs12dotnet8.

Exercise 2.4 – Explore topics

Use the links on the following page to learn more details about the topics covered in this chapter:https://github.com/markjprice/cs12dotnet8/blob/main/docs/book-links.md#chapter-2---speaking-c

Exercise 2.5 – Explore Spectre

No, not the villainous organization from the James Bond films! Spectre is a package that enhances console apps. You can read about it at the following link: https://spectreconsole.net/.

Understanding binary operators

Most operators are binary, meaning that they work on two operands, as shown in the following pseudocode:

var resultOfOperation = firstOperand operator secondOperand;

Examples of binary operators include adding and multiplying, as shown in the following code:

int x = 5;
int y = 3;
int resultOfAdding = x + y;
int resultOfMultiplying = x * y;

Understanding unary operators

Some operators are unary, meaning they work on a single operand and can be applied before or after the operand, as shown in the following pseudocode:

var resultOfOperationAfter = onlyOperand operator; 
var resultOfOperationBefore = operator onlyOperand;

Examples of unary operators include incrementors and retrieving a type or its size in bytes, as shown in the following code:

int x = 5;
int postfixIncrement = x++;
int prefixIncrement = ++x;
Type theTypeOfAnInteger = typeof(int);
string nameOfVariable = nameof(x);
int howManyBytesInAnInteger = sizeof(int);

Understanding ternary operators

A ternary operator works on three operands, as shown in the following pseudocode:

var resultOfOperation = firstOperand firstOperator 
  secondOperand secondOperator thirdOperand;

An example of a ternary operator is the conditional operator ?:, which acts like a simplified if statement. The first operand is a Boolean expression, the second operand is a value to return if it is true, and the third operand is a value to return if it is false, as shown in the following code:

// Syntax of conditional operator.
var result = boolean_expression ? value_if_true : value_if_false;
// Example of conditional operator.
string result = x > 3 ? "Greater than 3" : "Less than or equal to 3";
// Equivalent using an if statement.
string result;
if (x > 3)
{
  result = "Greater than 3";
}
else
{
  result = "Less than or equal to 3";
}

More experienced C# developers adopt ternary operators as much as possible because they are concise and can result in cleaner code once you are used to reading them.

Exploring unary operators

Two common unary operators are used to increment, ++, and decrement, --, a number. Let us write some example code to show how they work:

1. If you've completed the previous chapters, then you will already have a cs12dotnet8 folder. If not, then you'll need to create it.
2. Use your preferred coding tool to create a new solution and project, as defined in the following list:
   • Project template: Console App / console
   • Project file and folder: Operators
   • Solution file and folder: Chapter03
   • Do not use top-level statements: Cleared
   • Enable native AOT publish: Cleared
3. In Operators.csproj, add a new <ItemGroup> section to statically import System.Console for all C# files using the implicit usings .NET SDK feature, as shown in the following markup:

<ItemGroup>
  <Using Include="System.Console" Static="true" />
</ItemGroup>

1. In Program.cs, delete the existing statements and then declare two integer variables named a and b, set a to 3, increment a while assigning the result to b, and then output their values, as shown in the following code:

#region Exploring unary operators
int a = 3; 
int b = a++;
WriteLine($"a is {a}, b is {b}");
#endregion

Good Practice: I recommend wrapping the statements for each section in #region and #endregion as shown in the preceding code so that you can easily collapse the sections. But I will not show this in future code tasks to save space.

1. Before running the console app, ask yourself a question: what do you think the value of b will be when output? Once you've thought about that, run the code and compare your prediction against the actual result, as shown in the following output:

a is 4, b is 3

The variable b has the value 3 because the ++ operator executes after the assignment; this is known as a postfix operator. If you need to increment before the assignment, then use the prefix operator.

1. Copy and paste the statements, and then modify them to rename the variables and use the prefix operator, as shown in the following code:

int c = 3;
int d = ++c; // Prefix means increment c before assigning it.
WriteLine($"c is {c}, d is {d}");

1. Rerun the code and note the result, as shown in the following output:

a is 4, b is 3
c is 4, d is 4

Good Practice: Due to the confusion between the prefix and postfix for the increment and decrement operators when combined with an assignment, the Swift programming language designers decided to drop support for this operator in version 3. My recommendation for usage in C# is to never combine the use of the ++ and -- operators with an assignment operator, =. Perform the operations as separate statements.

Exploring binary arithmetic operators

Increment and decrement are unary arithmetic operators. Other arithmetic operators are usually binary and allow you to perform arithmetic operations on two numbers, as the following shows:

1. Add statements to declare and assign values to two integer variables named e and f, and then apply the five common binary arithmetic operators to the two numbers, as shown in the following code:

int e = 11; 
int f = 3;
WriteLine($"e is {e}, f is {f}"); 
WriteLine($"e + f = {e + f}"); 
WriteLine($"e - f = {e - f}"); 
WriteLine($"e * f = {e * f}"); 
WriteLine($"e / f = {e / f}"); 
WriteLine($"e % f = {e % f}");

1. Run the code and note the result, as shown in the following output:

e is 11, f is 3 
e + f = 14
e - f = 8 
e * f = 33 
e / f = 3 
e % f = 2

To understand the divide / and modulo % operators when applied to integers, you need to think back to primary school. Imagine you have eleven sweets and three friends.How can you divide the sweets between your friends? You can give three sweets to each of your friends, and there will be two left over. Those two sweets are the modulus, also known as the remainder after dividing. If you had twelve sweets, then each friend would get four of them, and there would be none left over, so the remainder would be 0.

1. Add statements to declare and assign a value to a double variable named g to show the difference between whole-number and real-number divisions, as shown in the following code:

double g = 11.0;
WriteLine($"g is {g:N1}, f is {f}"); 
WriteLine($"g / f = {g / f}");

1. Run the code and note the result, as shown in the following output:

g is 11.0, f is 3
g / f = 3.6666666666666665

If the first operand is a floating-point number, such as g with the value 11.0, then the divide operator returns a floating-point value, such as 3.6666666666665, rather than a whole number.

Assignment operators

You have already been using the most common assignment operator, =.To make your code more concise, you can combine the assignment operator with other operators like arithmetic operators, as shown in the following code:

int p = 6;
p += 3; // Equivalent to: p = p + 3;
p -= 3; // Equivalent to: p = p - 3;
p *= 3; // Equivalent to: p = p * 3;
p /= 3; // Equivalent to: p = p / 3;

Null-coalescing operators

Related operators to the assignment operators are the null-coalescing operators. Sometimes, you want to either assign a variable to a result or if the variable is null, then assign an alternative value. You can do this using the null-coalescing operators, ?? or ??=, as shown in the following code:

string? authorName = ReadLine(); // Prompt user to enter an author name.
// The maxLength variable will be the length of authorName if it is 
// not null, or 30 if authorName is null.
int maxLength = authorName?.Length ?? 30;
// The authorName variable will be "unknown" if authorName was null.
authorName ??= "unknown";

Exploring logical operators

Logical operators operate on Boolean values, so they return either true or false. Let's explore binary logical operators that operate on two Boolean values, traditionally named p and q in mathematics:

1. In Program.cs, add statements to declare two Boolean variables p and q with values of true and false, and then output truth tables showing the results of applying AND, OR, and XOR (exclusive OR) logical operators, as shown in the following code:

bool p = true;
bool q = false;
WriteLine($"AND  | p     | q    ");
WriteLine($"p    | {p & p,-5} | {p & q,-5} ");
WriteLine($"q    | {q & p,-5} | {q & q,-5} ");
WriteLine();
WriteLine($"OR   | p     | q    ");
WriteLine($"p    | {p | p,-5} | {p | q,-5} ");
WriteLine($"q    | {q | p,-5} | {q | q,-5} ");
WriteLine();
WriteLine($"XOR  | p     | q    ");
WriteLine($"p    | {p ^ p,-5} | {p ^ q,-5} ");
WriteLine($"q    | {q ^ p,-5} | {q ^ q,-5} ");

Remember that ,-5 means left-align within a five-width column.

1. Run the code and note the results, as shown in the following output:

AND  | p     | q
p    | True  | False
q    | False | False
OR   | p     | q
p    | True  | True
q    | True  | False
XOR  | p     | q
p    | False | True
q    | True  | False

For the AND & logical operator, both operands must be true for the result to be true. For the OR | logical operator, either operand can be true for the result to be true. For the XOR ^ logical operator, either operand can be true (but not both!) for the result to be true.

Exploring conditional logical operators

Conditional logical operators are like logical operators, but you use two symbols instead of one, for example, && instead of &, or || instead of |.In Chapter 4, Writing, Debugging, and Testing Functions, you will learn about functions in more detail, but I need to introduce functions now to explain conditional logical operators, also known as short-circuiting Boolean operators.A function executes statements and then returns a value. That value could be a Boolean value like true that is used in a Boolean operation. Let's make use of conditional logical operators:

1. At the bottom of Program.cs, write statements to declare a function that writes a message to the console and returns true, as shown in the following code:

static bool DoStuff()
{
  WriteLine("I am doing some stuff.");
  return true;
}

Local functions can be anywhere within the statements in Program.cs that uses the top-level program feature but it is good practice to put them at the bottom of the file.

1. After the previous WriteLine statements, perform an AND & operation on the p and q variables, and the result of calling the function, as shown in the following code:

WriteLine();
// Note that DoStuff() returns true.
WriteLine($"p & DoStuff() = {p & DoStuff()}"); 
WriteLine($"q & DoStuff() = {q & DoStuff()}");

1. Run the code, view the result, and note that the function was called twice, once for p and once for q, as shown in the following output:

I am doing some stuff. 
p & DoStuff() = True
I am doing some stuff. 
q & DoStuff() = False

1. Copy and paste the three statements and then change the & operators into && operators, as shown in the following code:

WriteLine();
WriteLine($"p && DoStuff() = {p && DoStuff()}"); 
WriteLine($"q && DoStuff() = {q && DoStuff()}");

1. Run the code, view the result, and note that the function does run when combined with the p variable. It does not run when combined with the q variable because the q variable is false so the result will be false anyway, so it does not need to execute the function, as shown in the following output:

I am doing some stuff. 
p && DoStuff() = True
q && DoStuff() = False // DoStuff function was not executed!

Good Practice: Now you can see why the conditional logical operators are described as being short-circuiting. They can make your apps more efficient, but they can also introduce subtle bugs in cases where you assume that the function will always be called. It is safest to avoid them when used in combination with functions that cause side effects.

Exploring bitwise and binary shift operators

Bitwise operators compare the bits in the binary representation of a number. Each bit, either the 0 (zero) or 1 (one) value, is compared individually to the bit in the same column.Binary shift operators can perform some common arithmetic calculations much faster than traditional operators, for example, any multiplication by a factor of 2.Let's explore bitwise and binary shift operators:

1. In Program.cs, add statements to declare two integer variables named x and y with values 10 and 6, and then output the results of applying AND, OR, and XOR bitwise operators, as shown in the following code:

WriteLine();
int x = 10;
int y = 6;
WriteLine($"Expression | Decimal |   Binary");
WriteLine($"-------------------------------");
WriteLine($"x          | {x,7} | {x:B8}");
WriteLine($"y          | {y,7} | {y:B8}");
WriteLine($"x & y      | {x & y,7} | {x & y:B8}");
WriteLine($"x | y      | {x | y,7} | {x | y:B8}");
WriteLine($"x ^ y      | {x ^ y,7} | {x ^ y:B8}");

Remember that ,7 means right-align in a seven-width column and :B8 means format in binary with eight digits.

1. Run the code and note the results, as shown in the following output:

Expression | Decimal |   Binary
-------------------------------
x          |      10 | 00001010
y          |       6 | 00000110
x & y      |       2 | 00000010
x | y      |      14 | 00001110
x ^ y      |      12 | 00001100

For x & y, only the 2-bit column is set. For x | y, the 8, 4 and 2-bit columns are set. For x ^ y, the 8 and 4 columns are set.

1. In Program.cs, add statements to output the results of applying the left-shift operator to move the bits of the variable a by three columns, multiplying a by 8, and right-shifting the bits of the variable b by one column, as shown in the following code:

// Left-shift x by three bit columns.
WriteLine($"x << 3     | {x << 3,7} | {x << 3:B8}");
// Multiply x by 8.
WriteLine($"x * 8      | {x * 8,7} | {x * 8:B8}");
// Right-shift y by one bit column.
WriteLine($"y >> 1     | {y >> 1,7} | {y >> 1:B8}");

1. Run the code and note the results, as shown in the following output:

x << 3     |      80 | 01010000
x * 8      |      80 | 01010000
y >> 1     |       3 | 00000011

The 80 result is because the bits in it were shifted three columns to the left, so the 1 bits moved into the 64- and 16-bit columns, and 64 + 16 = 80. This is the equivalent of multiplying by 8, but CPUs can perform a bit-shift faster. The 3 result is because the 1 bits in b were shifted one column into the 2- and 1-bit columns.

Good Practice: Remember that when operating on integer values, the & and | symbols are bitwise operators, and when operating on Boolean values like true and false, the & and | symbols are logical operators.

Miscellaneous operators

nameof and sizeof are convenient operators when working with types:

• nameof returns the short name (without the namespace) of a variable, type, or member as a string value, which is useful when outputting exception messages.
• sizeof returns the size in bytes of simple types, which is useful for determining the efficiency of data storage. Technically, the sizeof operator requires an unsafe code block but the sizes of value types with a C# alias, like int and double, are hardcoded as constants by the compiler so they do not need an unsafe block.

For example:

int age = 50;
WriteLine($"The {nameof(age)} variable uses {sizeof(int)} bytes of memory.");

There are many other operators; for example, the dot between a variable and its members is called the member access operator and the round brackets at the end of a function or method name are called the invocation operator, as shown in the following code:

int age = 50;
// How many operators in the following statement?
char firstDigit = age.ToString()[0];
// There are four operators:
// = is the assignment operator
// . is the member access operator
// () is the invocation operator
// [] is the indexer access operator

Branching with the if statement

The if statement determines which branch to follow by evaluating a Boolean expression. If the expression is true, then the block executes. The else block is optional, and it executes if the if expression is false. The if statement can be nested.The if statement can be combined with other if statements as else if branches, as shown in the following code:

if (expression1)
{
  // Executes if expression1 is true.
}
else if (expression2)
{
  // Executes if expression1 is false and expression2 is true.
}
else if (expression3)
{
  // Executes if expression1 and expression2 are false
  // and expression3 is true.
}
else
{
  // Executes if all expressions are false.
}

Each if statement's Boolean expression is independent of the others and, unlike switch statements, does not need to reference a single value.Let's write some code to explore selection statements like if:

1. Use your preferred coding tool to add a new Console App / console project named SelectionStatements to the Chapter03 solution.

   Remember to statically import System.Console in your project file. And if you are using Visual Studio 2022, then configure the startup project to be the current selection.

2. In Program.cs, delete the existing statements and then add statements to check if a password is at least eight characters, as shown in the following code:

string password = "ninja";
if (password.Length < 8)
{
  WriteLine("Your password is too short. Use at least 8 chars.");
}
else
{
  WriteLine("Your password is strong.");
}

1. Run the code and note the result, as shown in the following output:

 Your password is too short. Use at least 8 chars.

Why you should always use braces with if statements

As there is only a single statement inside each block, the preceding code could be written without the curly braces, as shown in the following code:

if (password.Length < 8)
  WriteLine("Your password is too short. Use at least 8 chars."); 
else
  WriteLine("Your password is strong.");

This style of if statement should be avoided because it can introduce serious bugs. An infamous example is the #gotofail bug in Apple's iPhone iOS operating system. For 18 months after Apple's iOS 6 was released, in September 2012, it had a bug due to an if statement without braces in its Secure Sockets Layer (SSL) encryption code. This meant that any user running Safari, the device's web browser, who tried to connect to secure websites, such as their bank, was not properly secure because an important check was being accidentally skipped.Just because you can leave out the curly braces, doesn't mean you should. Your code is not "more efficient" without them; instead, it is harder to read, less maintainable, and potentially more dangerous.

Pattern matching with the if statement

A feature introduced with C# 7 and later is pattern matching. The if statement can use the is keyword in combination with declaring a local variable to make your code safer:

1. Add statements so that if the value stored in the variable named o is an int, then the value is assigned to the local variable named i, which can then be used inside the if statement. This is safer than using the variable named o because we know for sure that i is an int variable and not something else, as shown in the following code:

// Add and remove the "" to change between string and int.
object o = "3"; 
int j = 4;
if (o is int i)
{
  WriteLine($"{i} x {j} = {i * j}");
}
else
{
  WriteLine("o is not an int so it cannot multiply!");
}

1. Run the code and view the results, as shown in the following output:

o is not an int so it cannot multiply!

1. Delete the double-quote characters around the "3" value so that the value stored in the variable named o is an int type instead of a string type.
2. Rerun the code to view the results, as shown in the following output:

3 x 4 = 12

Branching with the switch statement

The switch statement is different from the if statement because switch compares a single expression against a list of multiple possible case statements. Every case statement is related to the single expression. Every case section must end with one of the following:

• The break keyword (like case 1 in the following code).
• The goto case keywords (like case 2 in the following code).
• They should have no statements (like case 3 in the following code).
• The goto keyword that references a named label (like case 5 in the following code).
• The return keyword to leave the current function (not shown in the code).

Let's write some code to explore the switch statements:

1. Type the following code for a switch statement. You should note that the penultimate statement is a label that can be jumped to, and the first statement generates a random number between 1 and 6 (the number 7 in the code is an exclusive upper bound). The switch statement branches are based on the value of this random number, as shown in the following code:

// Inclusive lower bound but exclusive upper bound.
int number = Random.Shared.Next(minValue: 1, maxValue: 7);
WriteLine($"My random number is {number}");
switch (number)
{
  case 1: 
    WriteLine("One");
    break; // Jumps to end of switch statement.
  case 2:
    WriteLine("Two");
    goto case 1;
  case 3: // Multiple case section.
  case 4:
    WriteLine("Three or four");
    goto case 1;
  case 5:
    goto A_label;
  default:
    WriteLine("Default");
    break;
} // End of switch statement.
WriteLine("After end of switch");
A_label:
WriteLine($"After A_label");

Good Practice: You can use the goto keyword to jump to another case or a label. The goto keyword is frowned upon by most programmers but can be a good solution to code logic in some scenarios. However, you should use it sparingly, if at all. To see how often Microsoft uses goto in the .NET base class libraries, use the following link: https://github.com/search?q=%22goto%20%22+repo%3Adotnet%2Fruntime+language%3AC%23&type=code&ref=advsearch.

1. Run the code multiple times to see what happens in various cases of random numbers, as shown in the following example output:

// First random run.
My random number is 4 
Three or four
One
After end of switch
After A_label
// Second random run.
My random number is 2 
Two
One
After end of switch
After A_label
// Third random run.
My random number is 6
Default
After end of switch
After A_label
// Fourth random run.
My random number is 1 
One
After end of switch
After A_label
// Fifth random run.
My random number is 5
After A_label

Good Practice: The Random class that we used to generate a random number has a Next method that allows you to specify an inclusive lower bound and an exclusive upper bound and will generate a pseudo-random number. Instead of creating a new instance of Random that is not thread-safe, since .NET 6 you can use a Shared instance that is thread-safe so it can be used concurrently from any thread.

Adding a new item to a project using Visual Studio 2022

Visual Studio 2022 version 17.6 or later has an optional simplified dialog box for adding a new item to a project. After navigating to Project | Add New Item…, or right-clicking on a project in Solution Explorer and selecting Add | New Item…, you will see the traditional dialog box, as shown in Figure 3.1:

If you click the Show Compact View button, then it switches to a simplified dialog box, as shown in Figure 3.2:

To revert to the normal dialog box, click the Show All Templates button.

Pattern matching with the switch statement

Like the if statement, the switch statement supports pattern matching in C# 7 and later. The case values no longer need to be literal values; they can be patterns.In C# 7 and later, your code can more concisely branch, based on the subtype of a class, and you can declare and assign a local variable to safely use it. Additionally, case statements can include a when keyword to perform more specific pattern matching.Let's see an example of pattern matching with the switch statement using a custom class hierarchy of animals with different properties:

You will learn more details about defining classes in Chapter 5, Building Your Own Types with Object-Oriented Programming. For now, you should be able to get the idea from reading the code.

1. In the SelectionStatements project, add a new class file named Animals.cs:
   • In Visual Studio 2022, navigate to Project | Add New Item… or press Ctrl + Shift + A, type the name, and then click Add.
   • In Visual Studio Code, click the New File… button and type the name.
   • In JetBrains Rider, right-click on the project and select Add | Class/Interface….
2. In Animals.cs, delete any existing statements, and then define three classes, a base class, Animal, and two inherited classes, Cat and Spider, as shown in the following code:

class Animal // This is the base type for all animals.
{
  public string? Name;
  public DateTime Born;
  public byte Legs;
}
class Cat : Animal // This is a subtype of animal.
{
  public bool IsDomestic;
}
class Spider : Animal // This is another subtype of animal.
{
  public bool IsPoisonous;
}

1. In Program.cs, add statements to declare an array of nullable animals, and then show a message based on what type and attributes each animal has, as shown in the following code:

var animals = new Animal?[]
{
  new Cat { Name = "Karen", Born = new(year: 2022, month: 8,
    day: 23), Legs = 4, IsDomestic = true },
  null,
  new Cat { Name = "Mufasa", Born = new(year: 1994, month: 6,
    day: 12) },
  new Spider { Name = "Sid Vicious", Born = DateTime.Today, 
    IsPoisonous = true},
  new Spider { Name = "Captain Furry", Born = DateTime.Today }
};
foreach (Animal? animal in animals)
{
  string message;
  switch (animal)
  {
    case Cat fourLeggedCat when fourLeggedCat.Legs == 4:
      message = $"The cat named {fourLeggedCat.Name} has four legs.";
      break;
    case Cat wildCat when wildCat.IsDomestic == false:
      message = $"The non-domestic cat is named {wildCat.Name}.";
      break;
    case Cat cat:
      message = $"The cat is named {cat.Name}.";
      break;
    default: // default is always evaluated last.
      message = $"{animal.Name} is a {animal.GetType().Name}.";
      break;
    case Spider spider when spider.IsPoisonous:
      message = $"The {spider.Name} spider is poisonous. Run!";
      break;
    case null:
      message = "The animal is null.";
      break;
  }
  WriteLine($"switch statement: {message}");
}

The case statement shown in the following code:

case Cat fourLeggedCat when fourLeggedCat.Legs == 4:

Can also be written using the more concise property pattern-matching syntax, as shown in the following code:

case Cat { Legs: 4 } fourLeggedCat:

1. Run the code and note that the array named animals is declared to contain the Animal? type, so it could be any subtype of Animal, such as a Cat or a Spider, or a null value. In this code, we create four instances of Animal of different types with different properties, and one null one, so the result will be five messages that describe each of the animals, as shown in the following output:

switch statement: The cat named Karen has four legs.
switch statement: The animal is null.
switch statement: The non-domestic cat is named Mufasa.
switch statement: The Sid Vicious spider is poisonous. Run!
switch statement: Captain Furry is a Spider.

Simplifying switch statements with switch expressions

In C# 8 or later, you can simplify switch statements using switch expressions.Most switch statements are very simple, yet they require a lot of typing. switch expressions are designed to simplify the code you need to type while still expressing the same intent in scenarios where all cases return a value to set a single variable. switch expressions use a lambda, =>, to indicate a return value.Let's implement the previous code that used a switch statement using a switch expression so that you can compare the two styles:

1. In Program.cs, at the bottom and inside the foreach loop, add statements to set the message based on what type and attributes the animal has, using a switch expression, as shown in the following code:

message = animal switch
{
  Cat fourLeggedCat when fourLeggedCat.Legs == 4
    => $"The cat named {fourLeggedCat.Name} has four legs.",
  Cat wildCat when wildCat.IsDomestic == false
    => $"The non-domestic cat is named {wildCat.Name}.",
  Cat cat
    => $"The cat is named {cat.Name}.",
  Spider spider when spider.IsPoisonous
    => $"The {spider.Name} spider is poisonous. Run!",
  null
    => "The animal is null.",
  _
    => $"{animal.Name} is a {animal.GetType().Name}."
};
WriteLine($"switch expression: {message}");

The main differences are the removal of the case and break keywords. The underscore character _ is used to represent the default return value. It is known as a discard and you can read more about it at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/discards.

1. Run the code, and note that the result is the same as before, as shown in the following output:

switch statement: The cat named Karen has four legs.
switch expression: The cat named Karen has four legs.
switch statement: The animal is null.
switch expression: The animal is null.
switch statement: The non-domestic cat is named Mufasa.
switch expression: The non-domestic cat is named Mufasa.
switch statement: The Sid Vicious spider is poisonous. Run!
switch expression: The Sid Vicious spider is poisonous. Run!
switch statement: Captain Furry is a Spider.
switch expression: Captain Furry is a Spider.

Looping with the while statement

The while statement evaluates a Boolean expression and continues to loop while it is true. Let's explore iteration statements:

1. Use your preferred coding tool to add a new Console App / console project named IterationStatements to the Chapter03 solution.
2. In Program.cs, delete the existing statements and then add statements to define a while statement that loops while an integer variable has a value less than 10, as shown in the following code:

int x = 0;
while (x < 10)
{
  WriteLine(x);
  x++;
}

1. Run the code and view the results, which should be the numbers 0 to 9, as shown in the following output:

0
1
2
3
4
5
6
7
8
9

Looping with the do statement

The do statement is like while, except the Boolean expression is checked at the bottom of the block instead of the top, which means that the block always executes at least once, as the following shows:

1. Type statements to define a do loop, as shown in the following code:

string? actualPassword = "Pa$$w0rd";
string? password;
do
{
  Write("Enter your password: "); 
  password = ReadLine();
}
while (password != actualPassword);
WriteLine("Correct!");

1. Run the code, and note that you are prompted to enter your password repeatedly until you enter it correctly, as shown in the following output:

Enter your password: password 
Enter your password: 12345678 
Enter your password: ninja
Enter your password: correct horse battery staple 
Enter your password: Pa$$w0rd
Correct!

1. As an optional challenge, add statements so that the user can only make three attempts before an error message is displayed.
2. At this point, you might want to comment out the code for this section so you do not have to keep entering a password every time you run the console app!

Looping with the for statement

The for statement is like while, except that it is more succinct. It combines:

• An optional initializer expression, which executes once at the start of the loop.
• An optional conditional expression, which executes on every iteration at the start of the loop to check whether the looping should continue. If the expression returns true or it is missing, the loop will execute again.
• An optional iterator expression, which executes on every loop at the bottom of the statement. This is often used to increment a counter variable.

The for statement is commonly used with an integer counter. Let's explore some code:

1. Type a for statement to output the numbers 1 to 10, as shown in the following code:

for (int y = 1; y <= 10; y++)
{
  WriteLine(y);
}

1. Run the code to view the result, which should be the numbers 1 to 10.
2. Add another for statement to output the numbers 0 to 10, incrementing by 3, as shown in the following code:

for (int y = 0; y <= 10; y += 3)
{
  WriteLine(y);
}

1. Run the code to view the result, which should be the numbers 0, 3, 6, and 9.
2. Optionally, experiment with changing the initializer expression, conditional expression, or iterator expression to see their effects. Only change one thing at a time so that you can clearly see the effect produced.

Looping with the foreach statement

The foreach statement is a bit different from the previous three iteration statements.It is used to perform a block of statements on each item in a sequence, for example, an array or collection. Each item is usually read-only, and if the sequence structure is modified during iteration, for example, by adding or removing an item, then an exception will be thrown.Try the following example:

1. Type statements to create an array of string variables and then output the length of each one, as shown in the following code:

string[] names = { "Adam", "Barry", "Charlie" };
foreach (string name in names)
{
  WriteLine($"{name} has {name.Length} characters.");
}

1. Run the code and view the results, as shown in the following output:

Adam has 4 characters. 
Barry has 5 characters. 
Charlie has 7 characters. 

Understanding how foreach works internally

A developer who defines a type that represents multiple items, like an array or collection, should make sure that a programmer can use the foreach statement to enumerate through the type's items.Technically, the foreach statement will work on any type that follows these rules:

• The type must have a method named GetEnumerator that returns an object.
• The returned object must have a property named Current and a method named MoveNext.
• The MoveNext method must change the value of Current and return true if there are more items to enumerate through or return false if there are no more items.

There are interfaces named IEnumerable and IEnumerable<T> that formally define these rules, but technically the compiler does not require the type to implement these interfaces.The compiler turns the foreach statement in the preceding example into something like the following pseudocode:

IEnumerator e = names.GetEnumerator();
while (e.MoveNext())
{
  string name = (string)e.Current; // Current is read-only!
  WriteLine($"{name} has {name.Length} characters.");
}

Due to the use of an iterator and its read-only Current property, the variable declared in a foreach statement cannot be used to modify the value of the current item.

Working with single-dimensional arrays

The code that you will write next will allocate memory for an array for storing four string values. It will then store string values at index positions 0 to 3 (arrays usually have a lower bound of zero, so the index of the last item is one less than the length of the array).We could visualize the array like this:

Table 3.1: Visualization of an array of four string values

Good Practice: Do not assume that all arrays count from zero. The most common type of array in .NET is an szArray, a single-dimension zero-indexed array, and these use the normal [] syntax. But .NET also has mdArray, a multi-dimensional array, and they do not have to have a lower bound of zero. These are rarely used, but you should know they exist.

Finally, it will loop through each item in the array using a for statement.Let's look at how to use an array:

1. Use your preferred code editor to add a new Console App / console project named Arrays to the Chapter03 solution.
2. In Program.cs, delete the existing statements and then type statements to declare and use an array of string values, as shown in the following code:

string[] names; // This can reference any size array of strings.
// Allocate memory for four strings in an array.
names = new string[4];
// Store items at these index positions.
names[0] = "Kate";
names[1] = "Jack"; 
names[2] = "Rebecca"; 
names[3] = "Tom";
// Loop through the names.
for (int i = 0; i < names.Length; i++)
{
  // Output the item at index position i.
  WriteLine($"{names[i]} is at position {i}.");
}

1. Run the code and note the result, as shown in the following output:

Kate is at position 0.
Jack is at position 1.
Rebecca is at position 2.
Tom is at position 3.

Arrays are always of a fixed size at the time of memory allocation, so you need to decide how many items you want to store before instantiating them.An alternative to defining the array in three steps as above is to use array initializer syntax:

1. Before the for loop, add a statement to declare, allocate memory, and instantiate the values of a similar array, as shown in the following code:

// Alternative syntax for creating and initializing an array.
string[] names2 = { "Kate", "Jack", "Rebecca", "Tom" };

1. Change the for loop to use names2, run the console app, and note that the results are the same.

Working with multi-dimensional arrays

Instead of a single-dimension array for storing a row of string values (or any other data type), what if we want to store a grid of values? Or a cube? Or even higher dimensions?We could visualize a two-dimensional array, aka grid, of string values like this:

Table 3.2: Visualization of a two-dimensional array

Let's look at how to use multi-dimensional arrays:

1. At the bottom of Program.cs, add statements to declare and instantiate a two-dimensional array of string values, as shown in the following code:

string[,] grid1 = // Two dimensional array.
{
  { "Alpha", "Beta", "Gamma", "Delta" },
  { "Anne", "Ben", "Charlie", "Doug" },
  { "Aardvark", "Bear", "Cat", "Dog" }
};

1. We can discover the lower and upper bounds of this array using helpful methods, as shown in the following code:

WriteLine($"1st dimension, lower bound: {grid1.GetLowerBound(0)}");
WriteLine($"1st dimension, upper bound: {grid1.GetUpperBound(0)}");
WriteLine($"2nd dimension, lower bound: {grid1.GetLowerBound(1)}");
WriteLine($"2nd dimension, upper bound: {grid1.GetUpperBound(1)}");

1. Run the code and note the result, as shown in the following output:

1st dimension, lower bound: 0
1st dimension, upper bound: 2
2nd dimension, lower bound: 0
2nd dimension, upper bound: 3

1. We can then use these values in nested for statements to loop through the string values, as shown in the following code:

for (int row = 0; row <= grid1.GetUpperBound(0); row++)
{
  for (int col = 0; col <= grid1.GetUpperBound(1); col++)
  {
    WriteLine($"Row {row}, Column {col}: {grid1[row, col]}");
  }
}

1. Run the code and note the result, as shown in the following output:

Row 0, Column 0: Alpha
Row 0, Column 1: Beta
Row 0, Column 2: Gamma
Row 0, Column 3: Delta
Row 1, Column 0: Anne
Row 1, Column 1: Ben
Row 1, Column 2: Charlie
Row 1, Column 3: Doug
Row 2, Column 0: Aardvark
Row 2, Column 1: Bear
Row 2, Column 2: Cat
Row 2, Column 3: Dog

You must supply a value for every row and every column when it is instantiated, or you will get compile errors. If you need to indicate a missing string value, then use string.Empty. Or if you declare the array to be nullable string values by using string?[], then you can also use null for a missing value. If you cannot use the array initialization syntax, perhaps because you are loading values from a file or database, then you can separate the declaration of the array dimension and the allocation of memory from the assigning of values, as shown in the following code:

// Alternative syntax for declaring and allocating memory
// for a multi-dimensional array.
string[,] grid2 = new string[3,4]; // Allocate memory.
grid2[0, 0] = "Alpha"; // Assign values.
grid2[0, 1] = "Beta";
// And so on.
grid2[2, 3] = "Dog";

When declaring the size of the dimensions, you specify the length, not the upper bound. The expression new string[3,4] means the array can have 3 items in its first dimension (0) with an upper bound of 2, and the array can have 4 items in its second dimension (1) with an upper bound of 3.

Working with jagged arrays

If you need a multi-dimensional array but the number of items stored in each dimension is different, then you can define an array of arrays, aka a jagged array. We could visualize a jagged array as shown in Figure 3.3:

Let's look at how to use a jagged array:

1. At the bottom of Program.cs, add statements to declare and instantiate an array of arrays of string values, as shown in the following code:

string[][] jagged = // An array of string arrays.
{
  new[] { "Alpha", "Beta", "Gamma" },
  new[] { "Anne", "Ben", "Charlie", "Doug" },
  new[] { "Aardvark", "Bear" }
};

1. We can discover the lower and upper bounds of the array of arrays, and then each array with it, as shown in the following code:

WriteLine("Upper bound of the array of arrays is: {0}",
  jagged.GetUpperBound(0));
for (int array = 0; array <= jagged.GetUpperBound(0); array++)
{
  WriteLine("Upper bound of array {0} is: {1}",
    arg0: array,
    arg1: jagged[array].GetUpperBound(0));
}

1. Run the code and note the result, as shown in the following output:

Upper bound of the array of arrays is: 2
Upper bound of array 0 is: 2
Upper bound of array 1 is: 3
Upper bound of array 2 is: 1

1. We can then use these values in nested for statements to loop through the string values, as shown in the following code:

for (int row = 0; row <= jagged.GetUpperBound(0); row++)
{
  for (int col = 0; col <= jagged[row].GetUpperBound(0); col++)
  {
    WriteLine($"Row {row}, Column {col}: {jagged[row][col]}");
  }
}

1. Run the code and note the result, as shown in the following output:

Row 0, Column 0: Alpha
Row 0, Column 1: Beta
Row 0, Column 2: Gamma
Row 1, Column 0: Anne
Row 1, Column 1: Ben
Row 1, Column 2: Charlie
Row 1, Column 3: Doug
Row 2, Column 0: Aardvark
Row 2, Column 1: Bear

List pattern matching with arrays

Earlier in this chapter, you saw how an individual object supports pattern matching against its type and properties. Pattern matching also works with arrays and collections.Introduced with C# 11, list pattern matching works with any type that has a public Length or Count property and has an indexer using an int or System.Index parameter. You will learn about indexers in Chapter 5, Building Your Own Types with Object-Oriented Programming.When you define multiple list patterns in the same switch expression, you must order them so that the more specific one comes first, or the compiler will complain because a more general pattern will match all the more specific patterns too and make the more specific one unreachable.Table 3.3 shows examples of list pattern matching, assuming a list of int values:

Table 3.3: Examples of list pattern matching

Let's see some examples in code:

1. At the bottom of Program.cs, add statements to define some arrays of int values, and then pass them to a method that returns descriptive text depending on the pattern that matches best, as shown in the following code:

int[] sequentialNumbers = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
int[] oneTwoNumbers = { 1, 2 };
int[] oneTwoTenNumbers = { 1, 2, 10 };
int[] oneTwoThreeTenNumbers = { 1, 2, 3, 10 };
int[] primeNumbers = { 2, 3, 5, 7, 11, 13, 17, 19, 23, 29 };
int[] fibonacciNumbers = { 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89 };
int[] emptyNumbers = { }; // Or use Array.Empty<int>()
int[] threeNumbers = { 9, 7, 5 };
int[] sixNumbers = { 9, 7, 5, 4, 2, 10 };
WriteLine($"{nameof(sequentialNumbers)}: {CheckSwitch(sequentialNumbers)}");
WriteLine($"{nameof(oneTwoNumbers)}: {CheckSwitch(oneTwoNumbers)}");
WriteLine($"{nameof(oneTwoTenNumbers)}: {CheckSwitch(oneTwoTenNumbers)}");
WriteLine($"{nameof(oneTwoThreeTenNumbers)}: {CheckSwitch(oneTwoThreeTenNumbers)}");
WriteLine($"{nameof(primeNumbers)}: {CheckSwitch(primeNumbers)}");
WriteLine($"{nameof(fibonacciNumbers)}: {CheckSwitch(fibonacciNumbers)}");
WriteLine($"{nameof(emptyNumbers)}: {CheckSwitch(emptyNumbers)}");
WriteLine($"{nameof(threeNumbers)}: {CheckSwitch(threeNumbers)}");
WriteLine($"{nameof(sixNumbers)}: {CheckSwitch(sixNumbers)}");
static string CheckSwitch(int[] values) => values switch
{
  [] => "Empty array",
  [1, 2, _, 10] => "Contains 1, 2, any single number, 10.",
  [1, 2, .., 10] => "Contains 1, 2, any range including empty, 10.",
  [1, 2] => "Contains 1 then 2.",
  [int item1, int item2, int item3] => 
    $"Contains {item1} then {item2} then {item3}.",
  [0, _] => "Starts with 0, then one other number.",
  [0, ..] => "Starts with 0, then any range of numbers.",
  [2, .. int[] others] => $"Starts with 2, then {others.Length} more numbers.",
  [..] => "Any items in any order.",
};

1. Run the code and note the result, as shown in the following output:

sequentialNumbers: Contains 1, 2, any range including empty, 10.
oneTwoNumbers: Contains 1 then 2.
oneTwoTenNumbers: Contains 1, 2, any range including empty, 10.
oneTwoThreeTenNumbers: Contains 1, 2, any single number, 10.
primeNumbers: Starts with 2, then 9 more numbers.
fibonacciNumbers: Starts with 0, then any range of numbers.
emptyNumbers: Empty array
threeNumbers: Contains 9 then 7 then 5.
sixNumbers: Any items in any order.

You can learn more about list pattern matching at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/patterns#list-patterns.

Understanding inline arrays

Inline arrays were introduced with C# 12, and they are an advanced feature used by the .NET runtime team to improve performance. You are unlikely to use them yourself unless you are a public library author, but you will automatically benefit from others use of them.

More Information: You can learn more about inline arrays at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-12.0/inline-arrays.

Summarizing arrays

We use slightly different syntax to declare different types of arrays, as shown in Table 3.4:

Table 3.4: Summary of array declaration syntax

Arrays are useful for temporarily storing multiple items, but collections are a more flexible option when adding and removing items dynamically. You don't need to worry about collections right now, as we will cover them in Chapter 8, Working with Common .NET Types.You can convert any sequence of items into an array using the ToArray extension method, which we will cover in Chapter 11, Querying and Manipulating Data Using LINQ.

Good Practice: If you do not need to dynamically add and remove items, then you should use an array instead of a collection like List<T> because arrays are more efficient in memory use and the items are stored contiguously, which can improve performance.

Casting numbers implicitly and explicitly

Implicitly casting an int variable into a double variable is safe because no information can be lost, as the following shows:

1. Use your preferred coding tool to add a new Console App / console project named CastingConverting to the Chapter03 solution.
2. In Program.cs, delete the existing statements, then type statements to declare and assign an int variable and a double variable, and then implicitly cast the integer's value when assigning it to the double variable, as shown in the following code:

int a = 10;
double b = a; // An int can be safely cast into a double.
WriteLine($"a is {a}, b is {b}");

1. Type statements to declare and assign a double variable and an int variable, and then implicitly cast the double value when assigning it to the int variable, as shown in the following code:

double c = 9.8;
int d = c; // Compiler gives an error if you do not explicitly cast.
WriteLine($"c is {c}, d is {d}");

1. Run the code and note the error message, as shown in the following output:

Error: (6,9): error CS0266: Cannot implicitly convert type 'double' to 'int'. An explicit conversion exists (are you missing a cast?)

This error message will also appear in the Visual Studio Error List, Visual Studio Code PROBLEMS window, or JetBrains Rider Problems window.You cannot implicitly cast a double variable into an int variable because it is potentially unsafe and could lose data, like the value after the decimal point. You must explicitly cast a double variable into an int variable using a pair of round brackets around the type you want to cast the double type into. The pair of round brackets is the cast operator. Even then, you must beware that the part after the decimal point will be trimmed off without warning because you have chosen to perform an explicit cast and therefore understand the consequences.

1. Modify the assignment statement for the d variable to explicitly cast the variable c into an int, and add a comment to explain what will happen, as shown highlighted in the following code:

double c = 9.8;
int d = (int)c; // Compiler gives an error if you do not explicitly cast.
WriteLine($"c is {c}, d is {d}"); // d loses the .8 part.

1. Run the code to view the results, as shown in the following output:

a is 10, b is 10
c is 9.8, d is 9

We must perform a similar operation when converting values between larger integers and smaller integers. Again, beware that you might lose information because any value too big will have its bits copied and then be interpreted in ways that you might not expect!

1. Enter statements to declare and assign a long (64-bit) integer variable to an int (32-bit) integer variable, both using a small value that will work and a too-large value that will not, as shown in the following code:

long e = 10; 
int f = (int)e;
WriteLine($"e is {e:N0}, f is {f:N0}");
e = long.MaxValue;
f = (int)e;
WriteLine($"e is {e:N0}, f is {f:N0}");

1. Run the code to view the results, as shown in the following output:

e is 10, f is 10
e is 9,223,372,036,854,775,807, f is -1

1. Modify the value of e to 5 billion, as shown in the following code:

e = 5_000_000_000;

1. Run the code to view the results, as shown in the following output:

e is 5,000,000,000, f is 705,032,704

Five billion cannot fit into a 32-bit integer, so it overflows (wraps around) to about 705 million. It is all to do with the binary representation of integer numbers. You will see more examples of integer overflow and how to handle it later in this chapter.

How negative numbers are represented in binary

You might have wondered why f had the value -1 in the previous code. Negative aka signed numbers use the first bit to represent negativity. If the bit is 0 (zero), then it is a positive number. If the bit is 1 (one), then it is a negative number.Let's write some code to illustrate this:

1. Enter statements to output the maximum value for an int in decimal and binary number formats, then output the values 8 to -8, decrementing by one, and finally output the minimum value for an int, as shown in the following code:

WriteLine("{0,12} {1,34}", "Decimal", "Binary");
WriteLine("{0,12} {0,34:B32}", int.MaxValue);
for (int i = 8; i >= -8; i--)
{
  WriteLine("{0,12} {0,34:B32}", i);
}
WriteLine("{0,12} {0,34:B32}", int.MinValue);

Note ,12 and ,34 mean right-align within those column widths. :B32 means format as binary padded with leading zeros to a width of 32.

1. Run the code to view the results, as shown in the following output:

     Decimal                             Binary
  2147483647   01111111111111111111111111111111
           8   00000000000000000000000000001000
           7   00000000000000000000000000000111
           6   00000000000000000000000000000110
           5   00000000000000000000000000000101
           4   00000000000000000000000000000100
           3   00000000000000000000000000000011
           2   00000000000000000000000000000010
           1   00000000000000000000000000000001
           0   00000000000000000000000000000000
          -1   11111111111111111111111111111111
          -2   11111111111111111111111111111110
          -3   11111111111111111111111111111101
          -4   11111111111111111111111111111100
          -5   11111111111111111111111111111011
          -6   11111111111111111111111111111010
          -7   11111111111111111111111111111001
          -8   11111111111111111111111111111000
 -2147483648   10000000000000000000000000000000

1. Note that all the positive binary number representations start with 0 and all the negative binary number representations start with 1. The decimal value -1 is represented by all ones in binary. That is why when you have an integer too large to fit in a 32-bit integer, it becomes -1.

More Information: If you are interested in learning more about how signed numbers can be represented in computer systems, then you can read the following article: https://en.wikipedia.org/wiki/Signed_number_representations.

Converting with the System.Convert type

You can only cast between similar types, for example, between whole numbers like byte, int, and long, or between a class and its subclasses. You cannot cast a long to a string or a byte to a DateTime.An alternative to using the cast operator is to use the System.Convert type. The System.Convert type can convert to and from all the C# number types, as well as Booleans, strings, and date and time values.Let's write some code to see this in action:

1. At the top of Program.cs, statically import the System.Convert class, as shown in the following code:

using static System.Convert; // To use the ToInt32 method.

Alternatively, add an entry to CastingConverting.csproj, as shown in the following markup: <Using Include="System.Convert" Static="true" />

1. At the bottom of Program.cs, type statements to declare and assign a value to a double variable, convert it into an integer, and then write both values to the console, as shown in the following code:

double g = 9.8;
int h = ToInt32(g); // A method of System.Convert.
WriteLine($"g is {g}, h is {h}");

1. Run the code and view the result, as shown in the following output:

g is 9.8, h is 10

An important difference between casting and converting is that converting rounds the double value 9.8 up to 10 instead of trimming the part after the decimal point. Another is that casting can allow overflows while converting will throw an exception.

Rounding numbers and the default rounding rules

You have now seen that the cast operator trims the decimal part of a real number and that the System.Convert methods round up or down. However, what is the rule for rounding?In British primary schools for children aged 5 to 11, pupils are taught to round up if the decimal part is .5 or higher and round down if the decimal part is less. Of course, these terms only make sense because at that age the pupils are only dealing with positive numbers. With negative numbers, these terms become confusing and those terms should be avoided. This is why the .NET API uses the enum values AwayFromZero, ToZero, ToEven, ToPositiveInfinity, and ToNegativeInfinity for improved clarity.Let's explore if C# follows the same primary school rule:

1. Type statements to declare and assign an array of double values, convert each of them into an integer, and then write the result to the console, as shown in the following code:

double[,] doubles = {
  { 9.49, 9.5, 9.51 },
  { 10.49, 10.5, 10.51 },
  { 11.49, 11.5, 11.51 },
  { 12.49, 12.5, 12.51 } ,
  { -12.49, -12.5, -12.51 },
  { -11.49, -11.5, -11.51 },
  { -10.49, -10.5, -10.51 },
  { -9.49, -9.5, -9.51 }
};
WriteLine($"| double | ToInt32 | double | ToInt32 | double | ToInt32 |");
for (int x = 0; x < 8; x++)
{
  for (int y = 0; y < 3; y++)
  {
    Write($"| {doubles[x, y],6} | {ToInt32(doubles[x, y]),7} ");
  }
  WriteLine("|");
}
WriteLine();

1. Run the code and view the result, as shown in the following output:

| double | ToInt32 | double | ToInt32 | double | ToInt32 |
|   9.49 |       9 |    9.5 |      10 |   9.51 |      10 |
|  10.49 |      10 |   10.5 |      10 |  10.51 |      11 |
|  11.49 |      11 |   11.5 |      12 |  11.51 |      12 |
|  12.49 |      12 |   12.5 |      12 |  12.51 |      13 |
| -12.49 |     -12 |  -12.5 |     -12 | -12.51 |     -13 |
| -11.49 |     -11 |  -11.5 |     -12 | -11.51 |     -12 |
| -10.49 |     -10 |  -10.5 |     -10 | -10.51 |     -11 |
|  -9.49 |      -9 |   -9.5 |     -10 |  -9.51 |     -10 |

We have shown that the rule for rounding in C# is subtly different from the primary school rule:

• It always rounds toward zero if the decimal part is less than the midpoint .5.
• It always rounds away from zero if the decimal part is more than the midpoint .5.
• It will round away from zero if the decimal part is the midpoint .5 and the non-decimal part is odd, but it will round toward zero if the non-decimal part is even.

This rule is known as Banker's rounding, and it is preferred because it reduces bias by alternating when it rounds toward or away from zero. Sadly, other languages such as JavaScript use the primary school rule.

Taking control of rounding rules

You can take control of the rounding rules by using the Round method of the Math class:

1. Type statements to round each of the double values using the "away from zero" rounding rule, also known as rounding "up," and then write the result to the console, as shown in the following code:

foreach (double n in doubles)
{
  WriteLine(format:
    "Math.Round({0}, 0, MidpointRounding.AwayFromZero) is {1}",
    arg0: n,
    arg1: Math.Round(value: n, digits: 0,
            mode: MidpointRounding.AwayFromZero));
}

You can use a foreach statement to enumerate all the items in a multi-dimensional array.

1. Run the code and view the result, as shown in the following partial output:

Math.Round(9.49, 0, MidpointRounding.AwayFromZero) is 9
Math.Round(9.5, 0, MidpointRounding.AwayFromZero) is 10
Math.Round(9.51, 0, MidpointRounding.AwayFromZero) is 10
Math.Round(10.49, 0, MidpointRounding.AwayFromZero) is 10
Math.Round(10.5, 0, MidpointRounding.AwayFromZero) is 11
Math.Round(10.51, 0, MidpointRounding.AwayFromZero) is 11
...

Good Practice: For every programming language that you use, check its rounding rules. They may not work the way you expect! You can read more about Math.Round at the following link: https://learn.microsoft.com/en-us/dotnet/api/system.math.round.

Converting from any type to a string

The most common conversion is from any type into a string variable for outputting as human-readable text, so all types have a method named ToString that they inherit from the System.Object class.The ToString method converts the current value of any variable into a textual representation. Some types can't be sensibly represented as text, so they return their namespace and type name instead.Let's convert some types into a string:

1. Type statements to declare some variables, convert them to their string representation, and write them to the console, as shown in the following code:

int number = 12; 
WriteLine(number.ToString());
bool boolean = true; 
WriteLine(boolean.ToString());
DateTime now = DateTime.Now; 
WriteLine(now.ToString());
object me = new(); 
WriteLine(me.ToString());

1. Run the code and view the result, as shown in the following output:

12
True
08/28/2024 17:33:54
System.Object

Passing any object to the WriteLine method implicitly converts it into a string, so it is not necessary to explicitly call ToString. We are doing so here just to emphasize what is happening. Explicitly calling ToString does avoid a boxing operation, so if you are developing games with Unity then that can help you avoid memory garbage collection issues.

Converting from a binary object to a string

When you have a binary object like an image or video that you want to either store or transmit, you sometimes do not want to send the raw bits because you do not know how those bits could be misinterpreted, for example, by the network protocol transmitting them or another operating system that is reading the stored binary object.The safest thing to do is to convert the binary object into a string of safe characters. Programmers call this Base64 encoding.The Convert type has a pair of methods, ToBase64String and FromBase64String, that perform this conversion for you. Let's see them in action:

1. Type statements to create an array of bytes randomly populated with byte values, write each byte nicely formatted to the console, and then write the same bytes converted into Base64 to the console, as shown in the following code:

// Allocate an array of 128 bytes.
byte[] binaryObject = new byte[128];
// Populate the array with random bytes.
Random.Shared.NextBytes(binaryObject); 
WriteLine("Binary Object as bytes:");
for (int index = 0; index < binaryObject.Length; index++)
{
  Write($"{binaryObject[index]:X2} ");
}
WriteLine();
// Convert the array to Base64 string and output as text.
string encoded = ToBase64String(binaryObject);
WriteLine($"Binary Object as Base64: {encoded}");

By default, an int value would output assuming decimal notation, that is, Base10. You can use format codes such as :X2 to format the value using hexadecimal notation.

1. Run the code and view the result, as shown in the following output:

Binary Object as bytes:
EB 53 8B 11 9D 83 E6 4D 45 85 F4 68 F8 18 55 E5 B8 33 C9 B6 F4 00 10 7F CB 59 23 7B 26 18 16 30 00 23 E6 8F A9 10 B0 A9 E6 EC 54 FB 4D 33 E1 68 50 46 C4 1D 5F B1 57 A1 DB D0 60 34 D2 16 93 39 3E FA 0B 08 08 E9 96 5D 64 CF E5 CD C5 64 33 DD 48 4F E8 B0 B4 19 51 CA 03 6F F4 18 E3 E5 C7 0C 11 C7 93 BE 03 35 44 D1 6F AA B0 2F A9 CE D5 03 A8 00 AC 28 8F A5 12 8B 2E BE 40 C4 31 A8 A4 1A
Binary Object as Base64: 61OLEZ2D5k1FhfRo+BhV5bgzybb0ABB/y1kjeyYYFjAAI+aPqRCwqebsVPtNM+FoUEbEHV+xV6Hb0GA00haTOT76CwgI6ZZdZM/lzcVkM91IT+iwtBlRygNv9Bjj5ccMEceTvgM1RNFvqrAvqc7VA6gArCiPpRKLLr5AxDGopBo=

Parsing from strings to numbers or dates and times

The second most common conversion is from strings to numbers or date and time values.The opposite of ToString is Parse. Only a few types have a Parse method, including all the number types and DateTime.Let's see Parse in action:

1. At the top of Program.cs, import the namespace for working with cultures, as shown in the following code:

using System.Globalization; // To use CultureInfo.

1. At the bottom of Program.cs, add statements to parse an integer and a date and time value from strings and then write the result to the console, as shown in the following code:

// Set the current culture to make sure date parsing works.
CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("en-US");
int friends = int.Parse("27");
DateTime birthday = DateTime.Parse("4 June 1980");
WriteLine($"I have {friends} friends to invite to my party."); 
WriteLine($"My birthday is {birthday}."); 
WriteLine($"My birthday is {birthday:D}.");

1. Run the code and view the result, as shown in the following output:

I have 27 friends to invite to my party.
My birthday is 6/4/1980 12:00:00 AM.
My birthday is Wednesday, June 4, 1980.

By default, a date and time value outputs with the short date and time format. You can use format codes such as D to output only the date part using the long date format.

Good Practice: Use the standard date and time format specifiers, as shown at the following link: https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings#table-of-format-specifiers.

Avoiding Parse exceptions by using the TryParse method

One problem with the Parse method is that it gives errors if the string cannot be converted:

1. Type a statement to attempt to parse a string containing letters into an integer variable, as shown in the following code:

int count = int.Parse("abc");

1. Run the code and view the result, as shown in the following output:

Unhandled Exception: System.FormatException: Input string was not in a correct format.

As well as the preceding exception message, you will see a stack trace. I have not included stack traces in this book because they take up too much space.To avoid errors, you can use the TryParse method instead. TryParse attempts to convert the input string and returns true if it can convert it and false if it cannot. Exceptions are a relatively expensive operation so they should be avoided when you can.The out keyword is required to allow the TryParse method to set the count variable when the conversion works.Let's see TryParse in action:

1. Replace the int count declaration with statements to use the TryParse method and ask the user to input a count for a number of eggs, as shown in the following code:

Write("How many eggs are there? "); 
string? input = ReadLine();
if (int.TryParse(input, out int count))
{
  WriteLine($"There are {count} eggs.");
}
else
{
  WriteLine("I could not parse the input.");
}

1. Run the code, enter 12, and view the result, as shown in the following output:

How many eggs are there? 12
There are 12 eggs.

1. Run the code, enter twelve, and view the result, as shown in the following output:

How many eggs are there? twelve
I could not parse the input.

You can also use methods of the System.Convert type to convert string values into other types; however, like the Parse method, it gives an error if it cannot convert.

Understanding the Try method naming convention

.NET uses a standard signature for all methods that follow the Try naming convention. For any method named Something that returns a value of a specific type, its matching TrySomething method must return a bool to indicate success or failure and use an out parameter in place of the return value. For example:

// A method that might throw an exception.
int number = int.Parse("123");
// The Try equivalent of the method.
bool success = int.TryParse("123", out int number);
// Trying to create a Uri for a Web API.
bool success = Uri.TryCreate("https://localhost:5000/api/customers", 
  UriKind.Absolute, out Uri serviceUrl);

Wrapping error-prone code in a try block

When you know that a statement can cause an error, you should wrap that statement in a try block. For example, parsing from text to a number can cause an error. Any statements in the catch block will be executed only if an exception is thrown by a statement in the try block.We don't have to do anything inside the catch block. Let's see this in action:

1. Use your preferred coding tool to add a new Console App / console project named HandlingExceptions to the Chapter03 solution.
2. In Program.cs, delete any existing statements and then type statements to prompt the user to enter their age and then write their age to the console, as shown in the following code:

WriteLine("Before parsing"); 
Write("What is your age? "); 
string? input = ReadLine();
try
{
  int age = int.Parse(input); 
  WriteLine($"You are {age} years old.");
}
catch
{
}
WriteLine("After parsing");

You will see the following compiler message: Warning CS8604 Possible null reference argument for parameter 's' in 'int int.Parse(string s)'. By default, in .NET 6 or later projects, Microsoft enables nullable reference types, so you will see many more compiler warnings like this. In production code, you should add code to check for null and handle that possibility appropriately, as shown in the following code:

if (input is null)
{
  WriteLine("You did not enter a value so the app has ended.");
  return; // Exit the app.
}

In this book, I will not give instructions to add these null checks every time because the code samples are not designed to be production-quality, and having null checks everywhere will clutter the code and use up valuable pages. You will probably see hundreds more examples of potentially null variables throughout the code samples in this book. Those warnings are safe to ignore for the book code examples. You only need to pay attention to similar warnings when you write your own production code. You will see more about null handling in Chapter 6, Implementing Interfaces and Inheriting Classes.In this case, it is impossible for input to be null because the user must press Enter for ReadLine to return, and if they have not typed any characters at that point then the ReadLine method will return an empty string. Let's tell the compiler that it does not need to show us this warning:

1. To disable the compiler warning, change input to input!, as shown highlighted in the following code:

int age = int.Parse(input!);

An exclamation mark ! after an expression is called the null-forgiving operator and it disables the compiler warning. The null-forgiving operator has no effect at runtime. If the expression could evaluate to null at runtime, perhaps because we assigned it in another way, then an exception would be thrown.

This code includes two messages to indicate before parsing and after parsing to make the flow through the code clearer. These will be especially useful as the example code grows more complex.

1. Run the code, enter 49, and view the result, as shown in the following output:

Before parsing
What is your age? 49
You are 49 years old. 
After parsing

1. Run the code, enter Kermit, and view the result, as shown in the following output:

Before parsing
What is your age? Kermit
After parsing

When the code was executed, the error exception was caught, the default message and stack trace were not output, and the console app continued running. This is better than the default behavior, but it might be useful to see the type of error that occurred.

Good Practice: You should never use an empty catch statement like this in production code because it "swallows" exceptions and hides potential problems. You should at least log the exception if you cannot or do not want to handle it properly, or rethrow it so that higher-level code can decide instead. You will learn about logging in Chapter 4, Writing, Debugging, and Testing Functions.

Catching all exceptions

To get information about any type of exception that might occur, you can declare a variable of type System.Exception to the catch block:

1. Add an exception variable declaration to the catch block and use it to write information about the exception to the console, as shown in the following code:

catch (Exception ex)
{
  WriteLine($"{ex.GetType()} says {ex.Message}");
}

1. Run the code, enter Kermit again, and view the result, as shown in the following output:

Before parsing
What is your age? Kermit
System.FormatException says Input string was not in a correct format. 
After parsing

Catching specific exceptions

Now that we know which specific type of exception occurred, we can improve our code by catching just that type of exception and customizing the message that we display to the user. You can think of this as a form of testing:

1. Leave the existing catch block, and above it, add a new catch block for the format exception type, as shown in the following highlighted code:

catch (FormatException)
{
  WriteLine("The age you entered is not a valid number format.");
}
catch (Exception ex)
{
  WriteLine($"{ex.GetType()} says {ex.Message}");
}

1. Run the code, enter Kermit again, and view the result, as shown in the following output:

Before parsing
What is your age? Kermit
The age you entered is not a valid number format. 
After parsing

The reason we want to leave the more general catch below is that there might be other types of exceptions that can occur.

1. Run the code, enter 9876543210, and view the result, as shown in the following output:

Before parsing
What is your age? 9876543210
System.OverflowException says Value was either too large or too small for an Int32.
After parsing

Let's add another catch block for this type of exception.

1. Leave the existing catch blocks, and add a new catch block for the overflow exception type, as shown in the following highlighted code:

catch (OverflowException)
{
  WriteLine("Your age is a valid number format but it is either too big or small.");
}
catch (FormatException)
{
  WriteLine("The age you entered is not a valid number format.");
}

1. Run the code, enter 9876543210, and view the result, as shown in the following output:

Before parsing
What is your age? 9876543210
Your age is a valid number format but it is either too big or small. 
After parsing

The order in which you catch exceptions is important. The correct order is related to the inheritance hierarchy of the exception types. You will learn about inheritance in Chapter 5, Building Your Own Types with Object-Oriented Programming. However, don't worry too much about this—the compiler will give you build errors if you get exceptions in the wrong order anyway.

Good Practice: Avoid over-catching exceptions. They should often be allowed to propagate up the call stack to be handled at a level where more information is known about the circumstances that could change the logic of how they should be handled. You will learn about this in Chapter 4, Writing, Debugging, and Testing Functions.

Catching with filters

You can also add filters to a catch statement using the when keyword, as shown in the following code:

Write("Enter an amount: ");
string amount = ReadLine()!;
if (string.IsNullOrEmpty(amount)) return;
try
{
  decimal amountValue = decimal.Parse(amount);
  WriteLine($"Amount formatted as currency: {amountValue:C}");
}
catch (FormatException) when (amount.Contains("$"))
{
  WriteLine("Amounts cannot use the dollar sign!");
}
catch (FormatException)
{
  WriteLine("Amounts must only contain digits!");
}

Throwing overflow exceptions with the checked statement

The checked statement tells .NET to throw an exception when an overflow happens instead of allowing it to happen silently, which is done by default for performance reasons.We will set the initial value of an int variable to its maximum value minus one. Then, we will increment it several times, outputting its value each time. Once it gets above its maximum value, it overflows to its minimum value and continues incrementing from there.Let's see this in action:

1. In Program.cs, type statements to declare and assign an integer to one less than its maximum possible value, and then increment it and write its value to the console three times, as shown in the following code:

int x = int.MaxValue - 1; 
WriteLine($"Initial value: {x}"); 
x++;
WriteLine($"After incrementing: {x}"); 
x++;
WriteLine($"After incrementing: {x}"); 
x++;
WriteLine($"After incrementing: {x}");

1. Run the code and view the result that shows the value overflowing silently and wrapping around to large negative values, as shown in the following output:

Initial value: 2147483646
After incrementing: 2147483647
After incrementing: -2147483648
After incrementing: -2147483647

1. Now, let's get the compiler to warn us about the overflow by wrapping the statements using a checked statement block, as shown highlighted in the following code:

checked
{
  int x = int.MaxValue - 1; 
  WriteLine($"Initial value: {x}"); 
  x++;
  WriteLine($"After incrementing: {x}"); 
  x++;
  WriteLine($"After incrementing: {x}"); 
  x++;
  WriteLine($"After incrementing: {x}");
}

1. Run the code and view the result that shows the overflow being checked and causing an exception to be thrown, as shown in the following output:

Initial value: 2147483646
After incrementing: 2147483647
Unhandled Exception: System.OverflowException: Arithmetic operation resulted in an overflow.

1. Just like any other exception, we should wrap these statements in a try statement block and display a nicer error message for the user, as shown in the following code:

try
{
  // previous code goes here
}
catch (OverflowException)
{
  WriteLine("The code overflowed but I caught the exception.");
}

1. Run the code and view the result, as shown in the following output:

Initial value: 2147483646
After incrementing: 2147483647
The code overflowed but I caught the exception.

Disabling compiler overflow checks with the unchecked statement

The previous section was about the default overflow behavior at runtime and how to use the checked statement to change that behavior. This section is about compile-time overflow behavior and how to use the unchecked statement to change that behavior.A related keyword is unchecked. This keyword switches off overflow checks performed by the compiler within a block of code. Let's see how to do this:

1. Type the following statement at the end of the previous statements. The compiler will not compile this statement because it knows it would overflow:

int y = int.MaxValue + 1;

1. Hover your mouse pointer over the error, and note that a compile-time check is shown as an error message, as shown in Figure 3.4:

   

2. To disable compile-time checks, wrap the statement in an unchecked block, write the value of y to the console, decrement it, and repeat, as shown in the following code:

unchecked
{
  int y = int.MaxValue + 1; 
  WriteLine($"Initial value: {y}"); 
  y--;
  WriteLine($"After decrementing: {y}"); 
  y--;
  WriteLine($"After decrementing: {y}");
}

1. Run the code and view the results, as shown in the following output:

Initial value: -2147483648
After decrementing: 2147483647
After decrementing: 2147483646

Of course, it would be rare that you would want to explicitly switch off a check like this because it allows an overflow to occur. But perhaps you can think of a scenario where you might want that behavior.

Exercise 3.1 – Test your knowledge

Answer the following questions:

1. What happens when you divide an int variable by 0?
2. What happens when you divide a double variable by 0?
3. What happens when you overflow an int variable, that is, set it to a value beyond its range?
4. What is the difference between x = y++; and x = ++y;?
5. What is the difference between break, continue, and return when used inside a loop statement?
6. What are the three parts of a for statement and which of them are required?
7. What is the difference between the = and == operators?
8. Does the following statement compile?

for ( ; ; ) ;

1. What does the underscore _ represent in a switch expression?
2. What interface must an object "implement" to be enumerated over by using the foreach statement?

Exercise 3.2 – Explore loops and overflow

What will happen if this code executes?

int max = 500;
for (byte i = 0; i < max; i++)
{
  WriteLine(i);
}

Create a console app in Chapter03 named Ch03Ex02LoopsAndOverflow and enter the preceding code. Run the console app and view the output. What happens?What code could you add (don't change any of the preceding code) to warn us about the problem?

Exercise 3.3 – Test your knowledge of operators

What are the values of x and y after the following statements execute? Create a console app in Chapter03 named Ch03Ex03Operators to test your assumptions:

1. Increment and addition operators:

x = 3;
y = 2 + ++x;

1. Binary shift operators:

x = 3 << 2;
y = 10 >> 1;

1. Bitwise operators:

x = 10 & 8;
y = 10 | 7;

Exercise 3.4 – Practice loops and operators

FizzBuzz is a group game for children to teach them about division. Players take turns to count incrementally, replacing any number divisible by 3 with the word fizz, any number divisible by 5 with the word buzz, and any number divisible by both with fizzbuzz.Create a console app in Chapter03 named Ch03Ex04FizzBuzz that outputs a simulated FizzBuzz game that counts up to 100. The output should look something like Figure 3.5:

Exercise 3.5 – Practice exception handling

Create a console app in Chapter03 named Ch03Ex05Exceptions that asks the user for two numbers in the range 0-255 and then divides the first number by the second:

Enter a number between 0 and 255: 100
Enter another number between 0 and 255: 8
100 divided by 8 is 12

Write exception handlers to catch any thrown errors, as shown in the following output:

Enter a number between 0 and 255: apples
Enter another number between 0 and 255: bananas 
FormatException: Input string was not in a correct format.

Exercise 3.6 – Explore C# 101 notebooks

Use the links to notebooks and videos on the following page to see interactive examples of C# using Polyglot Notebooks, as shown in Figure 3.6:https://github.com/dotnet/csharp-notebooks#c-101

Exercise 3.7 – Explore topics

Use the links on the following page to learn about the topics covered in this chapter in more detail:https://github.com/markjprice/cs12dotnet8/blob/main/docs/book-links.md#chapter-3---controlling-flow-converting-types-and-handling-exceptions

Exploring top-level programs, functions, and namespaces

In Chapter 1, Hello, C#! Welcome, .NET!, we learned that since C# 10 and .NET 6, the default project template for console apps uses the top-level program feature introduced with C# 9.Once you start writing functions, it is important to understand how they work with the automatically generated Program class and its <Main>$ method.Let's explore how the top-level program feature works when you define functions:

1. Use your preferred coding tool to create a new solution and project, as defined in the following list:
   • Project template: Console App / console
   • Project file and folder: TopLevelFunctions
   • Solution file and folder: Chapter04
   • Do not use top-level statements: Cleared.
   • Enable native AOT publish: Cleared.
2. In Program.cs, delete the existing statements, define a local function at the bottom of the file, and call it, as shown in the following code:

using static System.Console;
WriteLine("* Top-level functions example");
WhatsMyNamespace(); // Call the function.
void WhatsMyNamespace() // Define a local function.
{
  WriteLine("Namespace of Program class: {0}", 
    arg0: typeof(Program).Namespace ?? "null");
}

Good Practice: Functions do not need to be at the bottom of the file, but it is good practice rather than mixing them up with other top-level statements. Types like classes must be declared at the bottom of the Program.cs file rather than in the middle of the file or you will see compiler error CS8803, as shown at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/cs8803. It would be better to define types like classes in a separate file.

1. Run the console app and note that the namespace for the Program class is null, as shown in the following output:

* Top-level functions example
Namespace of Program class: null

using static System.Console;
partial class Program
{
  static void <Main>$(String[] args)
  {
    WriteLine("* Top-level functions example");
    <<Main>$>g__WhatsMyNamespace|0_0(); // Call the function.
    void <<Main>$>g__WhatsMyNamespace|0_0() // Define a local function.
    {
      WriteLine("Namespace of Program class: {0}", 
        arg0: typeof(Program).Namespace ?? "null");
    }
  }
}

Defining a partial Program class with a static function

A better approach is to write any functions in a separate file and define them as static members of the Program class:

1. Add a new class file named Program.Functions.cs. The name of this file does not actually matter but using this naming convention is sensible. You could name the file Gibberish.cs and it would have the same behavior.
2. In Program.Functions.cs, delete any existing statements and then add statements to define a partial Program class. Cut and paste the WhatsMyNamespace function to move it from Program.cs into Program.Functions.cs, and then add the static keyword to the function, as shown highlighted in the following code:

using static System.Console;
// Do not define a namespace so this class goes in the default empty namespace
// just like the auto-generated partial Program class.
partial class Program
{
  static void WhatsMyNamespace() // Define a static function.
  {
    WriteLine("Namespace of Program class: {0}",
      arg0: typeof(Program).Namespace ?? "null");
  }
}

1. In Program.cs, confirm that its entire content is now just three statements, as shown in the following code:

using static System.Console;
WriteLine("* Top-level functions example");
WhatsMyNamespace(); // Call the function.

1. Run the console app and note that it has the same behavior as before.

What is automatically generated for a static function?

When you use a separate file to define a partial Program class with static functions, the compiler defines a Program class with a <Main>$ function, and merges your function as a member of the Program class, as shown in the following highlighted code:

using static System.Console;
partial class Program
{
  static void <Main>$(String[] args)
  {
    WriteLine("* Top-level functions example");
    WhatsMyNamespace(); // Call the function.
  }
  static void WhatsMyNamespace() // Define a static function.
  {
    WriteLine("Namespace of Program class: {0}",
      arg0: typeof(Program).Namespace ?? "null");
  }
}

Solution Explorer shows that your Program.Functions.cs class file merges its partial Program with the auto-generated partial Program class, as shown in Figure 4.1:

Good Practice: Create any functions that you will call in Program.cs in a separate file and manually define them inside a partial Program class. This will merge them into the automatically generated Program class at the same level as the <Main>$ method, instead of as local functions inside the <Main>$ method.

It is important to note the lack of namespace declarations. Both the automatically generated Program class and the explicitly defined Program class are in the default null namespace.

Warning! Do not define a namespace for your partial Program class. If you do, it will be in a different namespace and therefore will not merge with the auto-generated partial Program class.

Optionally, all the static methods in the Program class could be explicitly declared as private but this is the default anyway. Since all the functions will be called within the Program class itself the access modifier is not important.

Times table example

Let's say that you want to help your child learn their times tables, so you want to make it easy to generate a times table for a number, such as the 7 times table:

1 x 7 = 7
2 x 7 = 14
3 x 7 = 21
...
10 x 7 = 70
11 x 7 = 77
12 x 7 = 84

Most times tables have either 10, 12, or 20 rows, depending on how advanced the child is.You learned about the for statement earlier in this book, so you know that it can be used to generate repeated lines of output when there is a regular pattern, such as a 7 times table with 12 rows, as shown in the following code:

for (int row = 1; row <= 12; row++)
{
  Console.WriteLine($"{row} x 7 = {row * 7}");
}

However, instead of always outputting the 7 times table with 12 rows, we want to make this more flexible so it can output any size times table for any number. We can do this by creating a function.Let's explore functions by creating one to output any times table for numbers 0 to 255 of any size up to 255 rows (but it defaults to 12 rows):

1. Use your preferred coding tool to create a new project, as defined in the following list:
   • Project template: Console App / console
   • Project file and folder: WritingFunctions
   • Solution file and folder: Chapter04
   • In Visual Studio 2022, set the startup project for the solution to the current selection.
2. In WritingFunctions.csproj, after the <PropertyGroup> section, add a new <ItemGroup> section to statically import System.Console for all C# files using the implicit usings .NET SDK feature, as shown in the following markup:

<ItemGroup>
  <Using Include="System.Console" Static="true" />
</ItemGroup>

1. Add a new class file to the project named Program.Functions.cs.
2. In Program.Functions.cs, replace any existing code with new statements to define a function named TimesTable in the partial Program class, as shown in the following code:

partial class Program
{
  static void TimesTable(byte number, byte size = 12)
  {
    WriteLine($"This is the {number} times table with {size} rows:");
    WriteLine();
    for (int row = 1; row <= size; row++)
    {
      WriteLine($"{row} x {number} = {row * number}");
    }
    WriteLine();
  }
}

In the preceding code, note the following:

• TimesTable must have a byte value passed to it as a parameter named number.
• TimesTable can optionally have a byte value passed to it as a parameter named size. If a value is not passed, it defaults to 12.
• TimesTable is a static method because it will be called by the static method <Main>$.
• TimesTable does not return a value to the caller, so it is declared with the void keyword before its name.
• TimesTable uses a for statement to output the times table for the number passed to it with its number of rows equal to size.

1. In Program.cs, delete the existing statements and then call the function. Pass in a byte value for the number parameter, for example, 7, as shown in the following code:

TimesTable(7);

1. Run the code and then view the result, as shown in the following output:

This is the 7 times table with 12 rows:
1 x 7 = 7
2 x 7 = 14
3 x 7 = 21
4 x 7 = 28
5 x 7 = 35
6 x 7 = 42
7 x 7 = 49
8 x 7 = 56
9 x 7 = 63
10 x 7 = 70
11 x 7 = 77
12 x 7 = 84

1. Set the size parameter to 20, as shown in the following code:

TimesTable(7, 20);

1. Run the console app and confirm that the times table now has twenty rows.

   Good Practice: If a function has one or more parameters where just passing the values may not provide enough meaning, then you can optionally specify the name of the parameter as well as its value, as shown in the following code: TimesTable(number: 7, size: 10).

2. Change the number passed into the TimesTable function to other byte values between 0 and 255 and confirm that the output times tables are correct.
3. Note that if you try to pass a non-byte number, for example, an int, double, or string, an error is returned, as shown in the following output:

Error: (1,12): error CS1503: Argument 1: cannot convert from 'int' to 'byte'

A brief aside about arguments and parameters

In daily usage, most developers will use the terms argument and parameter interchangeably. Strictly speaking, the two terms have specific and subtly different meanings. But just like a person can be both a parent and a doctor, the two terms often apply to the same thing.A parameter is a variable in a function definition. For example, startDate is a parameter of the Hire function, as shown in the following code:

void Hire(DateTime startDate)
{
  // Function implementation.
}

When a method is called, an argument is the data you pass into the method's parameters. For example, when is a variable passed as an argument to the Hire function, as shown in the following code:

DateTime when = new(year: 2024, month: 11, day: 5);
Hire(when);

You might prefer to specify the parameter name when passing the argument, as shown in the following code:

DateTime when = new(year: 2024, month: 11, day: 5);
Hire(startDate: when);

When talking about the call to the Hire function, startDate is the parameter, and when is the argument.

If you read the official Microsoft documentation, they use the phrases named and optional arguments and named and optional parameters interchangeably, as shown at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/named-and-optional-arguments.

It gets complicated because a single object can act as both a parameter and an argument, depending on context. For example, within the Hire function implementation, the startDate parameter could be passed as an argument to another function like SaveToDatabase, as shown in the following code:

void Hire(DateTime startDate)
{
  ...
  SaveToDatabase(startDate, employeeRecord);
  ...
}

Naming things is one of the hardest parts of computing. A classic example is the parameter to the most important function in C#, Main. It defines a parameter named args, short for arguments, as shown in the following code:

static void Main(String[] args)
{
  ...
}

To summarize, parameters define inputs to a function, arguments are passed to a function when calling the function.

Good Practice: Try to use the correct term depending on the context, but do not get pedantic with other developers if they "misuse" a term. I must have used the terms parameter and argument thousands of times in this book. I'm sure some of those times I've been imprecise. Please do not @ me about it.

Writing a function that returns a value

The previous function performed actions (looping and writing to the console), but it did not return a value. Let's say that you need to calculate sales or value-added tax (VAT). In Europe, VAT rates can range from 8% in Switzerland to 27% in Hungary. In the United States, state sales taxes can range from 0% in Oregon to 8.25% in California.

Tax rates change all the time, and they vary based on many factors. The values used in this example do not need to be accurate.

Let's implement a function to calculate taxes in various regions around the world:

1. In Program.Functions.cs, in the Program class, write a function named CalculateTax, as shown in the following code:

static decimal CalculateTax(
  decimal amount, string twoLetterRegionCode)
{
  decimal rate = twoLetterRegionCode switch
  {
    "CH" => 0.08M, // Switzerland
    "DK" or "NO" => 0.25M, // Denmark, Norway  
    "GB" or "FR" => 0.2M, // UK, France
    "HU" => 0.27M, // Hungary
    "OR" or "AK" or "MT" => 0.0M, // Oregon, Alaska, Montana
    "ND" or "WI" or "ME" or "VA" => 0.05M,
    "CA" => 0.0825M, // California
    _ => 0.06M // Most other states.
  };
  return amount * rate;
}

In the preceding code, note the following:

• CalculateTax has two inputs: a parameter named amount, which will be the amount of money spent, and a parameter named twoLetterRegionCode, which will be the region the amount is spent in.
• CalculateTax will perform a calculation using a switch expression and then return the sales tax or VAT owed on the amount as a decimal value; so, before the name of the function, we have declared the data type of the return value to be decimal.

1. At the top of Program.Functions.cs, import the namespace to work with cultures, as shown in the following code:

using System.Globalization; // To use CultureInfo.

1. In Program.Functions.cs, in the Program class, write a function named ConfigureConsole, as shown in the following code:

static void ConfigureConsole(string culture = "en-US",
  bool useComputerCulture = false)
{
  // To enable Unicode characters like Euro symbol in the console.
  OutputEncoding = System.Text.Encoding.UTF8;
  if (!useComputerCulture)
  {
    CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo(culture);
  }
  WriteLine($"CurrentCulture: {CultureInfo.CurrentCulture.DisplayName}");
}

This function enables UTF-8 encoding for the console output. This is necessary to output some special symbols like the Euro currency symbol. This function also controls the current culture used to format dates, times, and currency values.

1. In Program.cs, comment out any TimesTable method calls, and then call the ConfigureConsole method and the CalculateTax method, passing values for the amount such as 149 and a valid region code such as FR, as shown in the following code:

// TimesTable(number: 7, size: 10);
ConfigureConsole();
decimal taxToPay = CalculateTax(amount: 149, twoLetterRegionCode: "FR");
WriteLine($"You must pay {taxToPay:C} in tax.");
// Alternatively, call the function in the interpolated string.
// WriteLine($"You must pay {CalculateTax(amount: 149,
//   twoLetterRegionCode: "FR"):C} in tax.");

1. Run the code, view the result, and note that it uses US English culture, meaning US dollars for the currency, as shown in the following output:

CurrentCulture: English (United States)
You must pay $29.80 in tax.

1. In Program.cs, change the ConfigureConsole method to use your local computer culture, as shown in the following code:

ConfigureConsole(useComputerCulture: true);

1. Run the code, view the result, and note that the currency should now show your local currency. For example, for me in the UK, I would see £29.80, as shown in the following output:

CurrentCulture: English (United Kingdom)
You must pay £29.80 in tax.

1. In Program.cs, change the ConfigureConsole method to use French culture, as shown in the following code:

ConfigureConsole(culture: "fr-FR");

1. Run the code, view the result, and note that the currency should now show Euros as used in France, as shown in the following output:

CurrentCulture: French (France)
You must pay 29,80 € in tax.

Can you think of any problems with the CalculateTax function as written? What would happen if the user entered a code such as fr or UK? How could you rewrite the function to improve it? Would using a switch statement instead of a switch expression be clearer?

Converting numbers from cardinal to ordinal

Numbers that are used to count are called cardinal numbers, for example, 1, 2, and 3, whereas numbers used to order are ordinal numbers, for example, 1st, 2nd, and 3rd. Let's create a function to convert cardinals to ordinals:

1. In Program.Functions.cs, write a function named CardinalToOrdinal that converts a cardinal uint value into an ordinal string value; for example, it converts 1 into "1st", 2 into "2nd", and so on, as shown in the following code:

static string CardinalToOrdinal(uint number)
{
  uint lastTwoDigits = number % 100;
  switch (lastTwoDigits)
  {
    case 11: // Special cases for 11th to 13th.
    case 12:
    case 13:
      return $"{number:N0}th";
    default:
      uint lastDigit = number % 10;
      string suffix = lastDigit switch
      {
        1 => "st",
        2 => "nd",
        3 => "rd",
        _ => "th"
      };
      return $"{number:N0}{suffix}";
  }
}

From the preceding code, note the following:

• CardinalToOrdinal has one input, a parameter of the uint type named number because we do not want to allow negative numbers, and one output: a return value of the string type.
• A switch statement is used to handle the special cases of 11, 12, and 13.
• A switch expression then handles all other cases: if the last digit is 1, then use st as the suffix; if the last digit is 2, then use nd as the suffix; if the last digit is 3, then use rd as the suffix; and if the last digit is anything else, then use th as the suffix.

1. In Program.Functions.cs, write a function named RunCardinalToOrdinal that uses a for statement to loop from 1 to 150, calling the CardinalToOrdinal function for each number and writing the returned string to the console, separated by a space character, as shown in the following code:

static void RunCardinalToOrdinal()
{
  for (uint number = 1; number <= 150; number++)
  {
    Write($"{CardinalToOrdinal(number)} ");
  }
  WriteLine();
}

1. In Program.cs, comment out the CalculateTax statements, and call the RunCardinalToOrdinal method, as shown in the following code:

RunCardinalToOrdinal();

1. Run the console app and view the results, as shown in the following output:

1st 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th 13th 14th 15th 16th 17th 18th 19th 20th 21st 22nd 23rd 24th 25th 26th 27th 28th 29th 30th 31st 32nd 33rd 34th 35th 36th 37th 38th 39th 40th 41st 42nd 43rd 44th 45th 46th 47th 48th 49th 50th 51st 52nd 53rd 54th 55th 56th 57th 58th 59th 60th 61st 62nd 63rd 64th 65th 66th 67th 68th 69th 70th 71st 72nd 73rd 74th 75th 76th 77th 78th 79th 80th 81st 82nd 83rd 84th 85th 86th 87th 88th 89th 90th 91st 92nd 93rd 94th 95th 96th 97th 98th 99th 100th 101st 102nd 103rd 104th 105th 106th 107th 108th 109th 110th 111th 112th 113th 114th 115th 116th 117th 118th 119th 120th 121st 122nd 123rd 124th 125th 126th 127th 128th 129th 130th 131st 132nd 133rd 134th 135th 136th 137th 138th 139th 140th 141st 142nd 143rd 144th 145th 146th 147th 148th 149th 150th

1. In the RunCardinalToOrdinal function, change the maximum number to 1500.
2. Run the console app and view the results, as shown partially in the following output:

1,480th 1,481st 1,482nd 1,483rd 1,484th 1,485th 1,486th 1,487th 1,488th 1,489th 1,490th 1,491st 1,492nd 1,493rd 1,494th 1,495th 1,496th 1,497th 1,498th 1,499th 1,500th

Calculating factorials with recursion

The factorial of 5 is 120 because factorials are calculated by multiplying the starting number by one less than itself, and then by one less again, and so on until the number is reduced to 1. An example can be seen here: 5 x 4 x 3 x 2 x 1 = 120.The factorial function is defined for non-negative integers only, i.e., for 0, 1, 2, 3, and so on, and it is defined as:

0! = 1 
n! = n × (n − 1)!, for n ∈ { 1, 2, 3, ... }

We could leave it to the compiler to reject negative numbers by declaring the input parameter as uint as we did for the CardinalToOrdinal function, but this time let's see an alternative way to handle that: throwing an argument exception.Factorials are written like this: 5!, where the exclamation mark is read as “bang,” so 5! = 120, or five bang equals one hundred and twenty. Bang is a good term to use in the context of factorials because they increase in size very rapidly, just like an explosion.We will write a function named Factorial; this will calculate the factorial for an int passed to it as a parameter. We will use a clever technique called recursion, which means a function that calls itself within its implementation, either directly or indirectly:

1. In Program.Functions.cs, write a function named Factorial, as shown in the following code:

static int Factorial(int number)
{
  if (number < 0)
  {
     throw new ArgumentOutOfRangeException(message: 
       $"The factorial function is defined for non-negative integers only. Input: {number}", 
       paramName: nameof(number));
  }
  else if (number == 0)
  {
    return 1;
  }
  else
  {
    return number * Factorial(number - 1);
  }
}

As before, there are several noteworthy elements in the preceding code, including the following:

• If the input parameter number is negative, Factorial throws an exception.
• If the input parameter number is zero, Factorial returns 1.
• If the input parameter number is more than 0 (which it will be in all other cases), Factorial multiplies the number by the result of calling itself and passing one less than number. This makes the function recursive.

More Information: Recursion is clever, but it can lead to problems, such as a stack overflow due to too many function calls because memory is used to store data on every function call, and it eventually uses too much. Iteration is a more practical, if less succinct, solution in languages such as C#. You can read more about this at the following link: https://en.wikipedia.org/wiki/Recursion_(computer_science)#Recursion_versus_iteration.

1. In Program.Functions.cs, write a function named RunFactorial that uses a for statement to output the factorials of numbers from 1 to 15, calls the Factorial function inside its loop, and then outputs the result, formatted using the code N0, which means number format using thousand separators with zero decimal places, as shown in the following code:

static void RunFactorial()
{
  for (int i = 1; i <= 15; i++)
  {
    WriteLine($"{i}! = {Factorial(i):N0}");
  }
}

1. Comment out the RunCardinalToOrdinal method call and call the RunFactorial method.
2. Run the project and view the results, as shown in the following partial output:

1! = 1
2! = 2
3! = 6
4! = 24
...
12! = 479,001,600
13! = 1,932,053,504
14! = 1,278,945,280
15! = 2,004,310,016

It is not immediately obvious in the previous output, but factorials of 13 and higher overflow the int type because they are so big. 12! is 479,001,600, which is about half a billion. The maximum positive value that can be stored in an int variable is about two billion. 13! is 6,227,020,800, which is about six billion, and when stored in a 32-bit integer, it overflows silently without showing any problems.What should you do to get notified when an overflow happens? Of course, we could solve the problem for 13! and 14! by using a long (64-bit integer) instead of an int (32-bit integer), but we will quickly hit the overflow limit again.The point of this section is to understand and show you that numbers can overflow, and not specifically how to calculate factorials higher than 12!. Let’s take a look:

1. Modify the Factorial function to check for overflows in the statement that calls itself, as shown highlighted in the following code:

checked // for overflow
{
  return number * Factorial(number - 1);
}

1. Modify the RunFactorial function to change the starting number to -2 and to handle overflow and other exceptions when calling the Factorial function, as shown highlighted in the following code:

static void RunFactorial()
{
  for (int i = -2; i <= 15; i++)
  {
    try
    {
      WriteLine($"{i}! = {Factorial(i):N0}");
    }
    catch (OverflowException)
    {
      WriteLine($"{i}! is too big for a 32-bit integer.");
    }
    catch (Exception ex)
    {
      WriteLine($"{i}! throws {ex.GetType()}: {ex.Message}");
    }
  }
}

1. Run the code and view the results, as shown in the following partial output:

-2! throws System.ArgumentOutOfRangeException: The factorial function is defined for non-negative integers only. Input: -2 (Parameter 'number')
-1! throws System.ArgumentOutOfRangeException: The factorial function is defined for non-negative integers only. Input: -1 (Parameter 'number')
0! = 1
1! = 1
2! = 2
...
12! = 479,001,600
13! is too big for a 32-bit integer.
14! is too big for a 32-bit integer.
15! is too big for a 32-bit integer.

Documenting functions with XML comments

By default, when calling a function such as CardinalToOrdinal, code editors will show a tooltip with basic information.Let's improve the tooltip by adding extra information:

1. If you are using Visual Studio Code with the C# extension, you should navigate to View | Command Palette | Preferences: Open Settings (UI), and then search for formatOnType and make sure that it is enabled. C# XML documentation comments are a built-in feature of Visual Studio 2022 and JetBrains Rider, so you do not need to do anything to use them.
2. On the line above the CardinalToOrdinal function, type three forward slashes ///, and note that they are expanded into an XML comment that recognizes that the function has a single parameter named number, as shown in the following code:

/// <summary>
/// 
/// </summary>
/// <param name="number"></param>
/// <returns></returns>

1. Enter suitable information for the XML documentation comment for the CardinalToOrdinal function. Add a summary, and describe the input parameter and the return value, as shown highlighted in the following code:

/// <summary>
/// Pass a 32-bit unsigned integer and it will be converted into its ordinal equivalent.
/// </summary>
/// <param name="number">Number as a cardinal value e.g. 1, 2, 3, and so on.</param>
/// <returns>Number as an ordinal value e.g. 1st, 2nd, 3rd, and so on.</returns>

1. Now, when calling the function, you will see more details, as shown in Figure 4.2:

It is worth emphasizing that this feature is primarily designed to be used with a tool that converts the comments into documentation, like Sandcastle, which you can read more about at the following link: https://github.com/EWSoftware/SHFB. The tooltips that appear while entering code or hovering over the function name are a secondary feature.Local functions do not support XML comments because local functions cannot be used outside the member in which they are declared, so it makes no sense to generate documentation from them. Sadly, this also means no tooltip, which would still be useful, but neither Visual Studio 2022 nor Visual Studio Code recognize that.

Good Practice: Add XML documentation comments to all your functions except local functions.

Using lambdas in function implementations

F# is Microsoft's strongly typed functional-first programming language that, like C#, compiles to Intermediate Language (IL) to be executed by .NET. Functional languages evolved from lambda calculus, a computational system based only on functions. The code looks more like mathematical functions than steps in a recipe.Some of the important attributes of functional languages are defined in the following list:

• Modularity: The same benefit of defining functions in C# applies to functional languages. Breaks up a large complex code base into smaller pieces.
• Immutability: Variables in the C# sense do not exist. Any data value inside a function cannot change. Instead, a new data value can be created from an existing one. This reduces bugs.
• Maintainability: Code is cleaner and clearer (for mathematically-inclined programmers!).

Since C# 6, Microsoft has worked to add features to the language to support a more functional approach, for example, adding tuples and pattern matching in C# 7, non-null reference types in C# 8, and improving pattern matching and adding records, that is, potentially immutable objects, in C# 9.In C# 6, Microsoft added support for expression-bodied function members. We will look at an example of this now. In C#, lambdas are the use of the => character to indicate a return value from a function.The Fibonacci sequence of numbers always starts with 0 and 1. Then the rest of the sequence is generated using the rule of adding together the previous two numbers, as shown in the following sequence of numbers:

0 1 1 2 3 5 8 13 21 34 55 ...

The next term in the sequence would be 34 + 55, which is 89.We will use the Fibonacci sequence to illustrate the difference between an imperative and declarative function implementation:

1. In Program.Functions.cs, write a function named FibImperative, which will be written in an imperative style, as shown in the following code:

static int FibImperative(uint term)
{
  if (term == 0)
  {
    throw new ArgumentOutOfRangeException();
  }
  else if (term == 1)
  {
    return 0;
  }
  else if (term == 2)
  {
    return 1;
  }
  else
  {
    return FibImperative(term - 1) + FibImperative(term - 2);
  }
}

1. In Program.Functions.cs, write a function named RunFibImperative that calls FibImperative inside a for statement that loops from 1 to 30, as shown in the following code:

static void RunFibImperative()
{
  for (uint i = 1; i <= 30; i++)
  {
    WriteLine("The {0} term of the Fibonacci sequence is {1:N0}.",
      arg0: CardinalToOrdinal(i),
      arg1: FibImperative(term: i));
  }
}

1. In Program.cs, comment out the other method calls, and call the RunFibImperative method.
2. Run the console app and view the results, as shown in the following partial output:

The 1st term of the Fibonacci sequence is 0.
The 2nd term of the Fibonacci sequence is 1.
The 3rd term of the Fibonacci sequence is 1.
The 4th term of the Fibonacci sequence is 2.
The 5th term of the Fibonacci sequence is 3.
...
The 29th term of the Fibonacci sequence is 317,811.
The 30th term of the Fibonacci sequence is 514,229.

1. In Program.Functions.cs, write a function named FibFunctional written in a declarative style, as shown in the following code:

static int FibFunctional(uint term) => term switch
  {
    0 => throw new ArgumentOutOfRangeException(),
    1 => 0,
    2 => 1,
    _ => FibFunctional(term - 1) + FibFunctional(term - 2)
  };

1. In Program.Functions.cs, write a function to call it inside a for statement that loops from 1 to 30, as shown in the following code:

static void RunFibFunctional()
{
  for (uint i = 1; i <= 30; i++)
  {
    WriteLine("The {0} term of the Fibonacci sequence is {1:N0}.",
      arg0: CardinalToOrdinal(i),
      arg1: FibFunctional(term: i));
  }
}

1. In Program.cs, comment out the RunFibImperative method call, and call the RunFibFunctional method.
2. Run the code and view the results (which will be the same as before).

Now that you have seen some examples of functions, let's see how you can fix them when they have bugs.

Creating code with a deliberate bug

Let's explore debugging by creating a console app with a deliberate bug, which we will then use the debugger tools in your code editor to track down and fix:

1. Use your preferred coding tool to add a new Console App / console project named Debugging to the Chapter04 solution.
2. Modify Debugging.csproj to statically import System.Console for all code files.
3. In Program.cs, delete any existing statements and then, at the bottom of the file, add a function with a deliberate bug, as shown in the following code:

double Add(double a, double b)
{
  return a * b; // Deliberate bug!
}

1. Above the Add function, write statements to declare and set some variables and then add them together using the buggy function, as shown in the following code:

double a = 4.5;
double b = 2.5;
double answer = Add(a, b);
WriteLine($"{a} + {b} = {answer}");
WriteLine("Press Enter to end the app.");
ReadLine(); // Wait for user to press Enter.

1. Run the console application and view the result, as shown in the following output:

4.5 + 2.5 = 11.25
Press Enter to end the app.

But wait, there's a bug! 4.5 added to 2.5 should be 7, not 11.25!We will use the debugging tools to hunt for and squish the bug.

Setting a breakpoint and starting debugging

Breakpoints allow us to mark a line of code that we want to pause at to inspect the program state and find bugs.

Using Visual Studio 2022

Let's set a breakpoint and then start debugging using Visual Studio 2022:

1. Click in line 1, which is the statement that declares the variable named a.
2. Navigate to Debug | Toggle Breakpoint or press F9. A red circle will appear in the margin bar on the left-hand side and the statement will be highlighted in red to indicate that a breakpoint has been set, as shown in Figure 4.3:

Breakpoints can be toggled off with the same action. You can also left-click in the margin to toggle a breakpoint on and off, or right-click a breakpoint to see more options, such as delete, disable, or edit conditions or actions for an existing breakpoint.

1. Navigate to Debug | Start Debugging or press F5. Visual Studio starts the console application and then pauses when it hits the breakpoint. This is known as break mode. Extra windows titled Locals (showing current values of local variables), Watch 1 (showing any watch expressions you have defined), Call Stack, Exception Settings, and Immediate Window may appear. The Debugging toolbar appears. The line that will be executed next is highlighted in yellow, and a yellow arrow points at the line from the margin bar, as shown in Figure 4.4:

If you do not want to see how to use Visual Studio Code to start debugging, then you can skip the Using Visual Studio Code section and continue to the section titled Navigating with the debugging toolbar.

Using Visual Studio Code

Let's set a breakpoint and then start debugging using Visual Studio Code:

1. Click in line 1, which is the statement that declares the variable named a.
2. Navigate to Run | Toggle Breakpoint or press F9. A red circle will appear in the margin bar on the left-hand side to indicate that a breakpoint has been set.

Breakpoints can be toggled off with the same action. You can also left-click in the margin to toggle a breakpoint on and off; right-click to see more options, such as remove, edit, or disable an existing breakpoint; or add a breakpoint, conditional breakpoint, or logpoint when a breakpoint does not yet exist.Logpoints, also known as tracepoints, indicate that you want to record some information without having to stop executing the code at that point.

1. Navigate to View | Run, or in the left navigation bar, you can click the Run and Debug icon (the triangle "play" button and "bug") or press Ctrl + Shift + D (on Windows).

2. At the top of the RUN AND DEBUG window, click the Run and Debug button, and then select the Debugging project, as shown in Figure 4.5:

   

   If you are first prompted to choose a debugger, select C#, not .NET 5+ or .NET Core.

3. Visual Studio Code starts the console app and then pauses when it hits the breakpoint. This is known as break mode. The line that will be executed next is highlighted in yellow, and a yellow block points at the line from the margin bar, as shown in Figure 4.6:

Navigating with the debugging toolbar

Visual Studio 2022 has two debug-related buttons in its Standard toolbar to start or continue debugging and to hot reload changes to the running code, and a separate Debug toolbar for the rest of the tools. Visual Studio Code shows a floating toolbar with buttons to make it easy to access debugging features.Both are shown in Figure 4.7:

The following list describes the most common buttons in the toolbars:

• Start/Continue/F5: This button is context-sensitive. It will either start a project running or continue running the project from the current position until it ends or hits a breakpoint.
• Hot Reload: This button will reload compiled code changes without needing to restart the app.
• Break All: This button will break into the next available line of code in a running app.
• Stop Debugging/Stop/Shift + F5 (red square): This button will stop the debugging session.
• Restart/Ctrl or Cmd + Shift + F5 (circular arrow): This button will stop and then immediately restart the program with the debugger attached again.
• Show Next Statement: This button will move the current cursor to the next statement that will execute.
• Step Into/F11, Step Over/F10, and Step Out/Shift + F11 (blue arrows over dots): These buttons step through the code statements in various ways, as you will see in a moment.
• Show Threads in Source: This button allows you to examine and work with threads in the application that you're debugging.

Debugging windows

While debugging, both Visual Studio 2022 and Visual Studio Code show extra windows that allow you to monitor useful information, such as variables, while you step through your code.The most useful windows are described in the following list:

• VARIABLES, including Locals, which shows the name, value, and type of any local variables automatically. Keep an eye on this window while you step through your code.
• WATCH, or Watch 1, which shows the value of variables and expressions that you manually enter.
• CALL STACK, which shows the stack of function calls.
• BREAKPOINTS, which shows all your breakpoints and allows finer control over them.

When in break mode, there is also a useful window at the bottom of the edit area:

• DEBUG CONSOLE or Immediate Window enables live interaction with your code. You can interrogate the program state, for example, by entering the name of a variable. For example, you can ask a question such as "What is 1+2?" by typing 1+2 and pressing Enter.

Stepping through code

Let's explore some ways to step through the code using either Visual Studio 2022 or Visual Studio Code:

The menu commands for debugging are on the Debug menu in Visual Studio 2022 or the Run menu in Visual Studio Code and JetBrains Rider.

1. Navigate to Run or Debug | Step Into, click on the Step Into button in the toolbar, or press F11. The yellow highlight steps forward one line.
2. Navigate to Run or Debug | Step Over, click on the Step Over button in the toolbar, or press F10. The yellow highlight steps forward one line. At the moment, you can see that there is no difference between using Step Into or Step Over because we are executing single statements.
3. You should now be on the line that calls the Add method.

The difference between Step Into and Step Over can be seen when you are about to execute a method call:

• If you click on Step Into, the debugger steps into the method so that you can step through every line in that method.
• If you click on Step Over, the whole method is executed in one go; it does not skip over the method without executing it.

1. Click on Step Into to step inside the Add method.
2. Hover your mouse pointer over the a or b parameters in the code editing window and note that a tooltip appears showing their current value.
3. Select the expression a * b, right-click the expression, and select Add to Watch or Add Watch. The expression is added to the WATCH or Watch 1 window, showing that this operator is multiplying a by b to give the result 11.25.
4. In the WATCH or Watch 1 window, right-click the expression and choose Remove Expression or Delete Watch.
5. Fix the bug by changing * to + in the Add function.
6. Restart debugging by clicking the circular arrow Restart button or pressing Ctrl or Cmd + Shift + F5.
7. Step over the function, take a minute to note how it now calculates correctly, and click the Continue button or press F5.
8. With Visual Studio Code, note that when writing to the console during debugging, the output appears in the DEBUG CONSOLE window instead of the TERMINAL window, as shown in Figure 4.8:

Using the Visual Studio Code integrated terminal during debugging

By default, the console is set to use the internal DEBUG CONSOLE during debugging, which does not allow interactions like entering text from the ReadLine method.To improve the experience, we can change a setting to use the integrated terminal instead. First, let's modify the code to require interaction with the user:

1. At the top of Program.cs, add statements to prompt the user to enter a number and parse that as a double into the variable a, as shown highlighted in the following code:

Write("Enter a number: ");
string number = ReadLine()!;
double a = double.Parse(number);

1. Set a breakpoint on line 1 that writes the prompt, Enter a number.
2. At the top of the RUN AND DEBUG window, click the Run and Debug button, and then select the Debugging project.
3. Note that the Enter a number prompt is not written to either TERMINAL or DEBUG CONSOLE and neither window is waiting for the user to enter a number and press Enter.
4. Stop debugging.

5. At the top of the RUN AND DEBUG window, click the create a launch.json file link, and then, when prompted for the debugger, select C#, as shown in Figure 4.9:

   

6. In the launch.json file editor, click the Add Configuration... button, and then select .NET: Launch .NET Core Console App, as shown in Figure 4.10:

   

7. In launch.json, make the following additions and changes, as shown highlighted in the following configuration:
   • Comment out the preLaunchTask setting.
   • In the program path, add the Debugging project folder after the workspaceFolder variable.
   • In the program path, change <target-framework> to net8.0.
   • In the program path, change <project-name.dll> to Debugging.dll.
   • Change the console setting from internalConsole to integratedTerminal:

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": ".NET Core Launch (console)",
      "type": "coreclr",
      "request": "launch",
      //"preLaunchTask": "build",
      "program": "${workspaceFolder}/Debugging/bin/Debug/net8.0/Debugging.dll",
      "args": [],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
      "console": "integratedTerminal"
    }
  ]
}

Remember that with Visual Studio Code, we open the Chapter04 folder to process the solution file, so the workspace folder is Chapter04, not the Debugging project.

1. At the top of the RUN AND DEBUG window, note the dropdown list of launch configurations, and click the Start Debugging button (green triangle), as shown in Figure 4.11.
2. Navigate to View | Terminal and note the TERMINAL window is attached to the Debugging.dll, as shown in Figure 4.11.
3. Step over the statement that writes Enter a number: to the console.
4. Step over the statement that calls ReadLine.
5. Type 5.5 and press Enter.
6. Continue stepping through the statements or press F5 or click Continue, and note the output written to the integrated terminal, as shown in Figure 4.11:

Customizing breakpoints

It is easy to make more complex breakpoints:

1. If you are still debugging, click the Stop button in the debugging toolbar, navigate to Run or Debug | Stop Debugging, or press Shift + F5.
2. Navigate to Run | Remove All Breakpoints or Debug | Delete All Breakpoints.
3. Click on the WriteLine statement that outputs the answer.
4. Set a breakpoint by pressing F9 or navigating to Run or Debug | Toggle Breakpoint.
5. Right-click the breakpoint and choose the appropriate menu for your code editor:
   • In Visual Studio Code, choose Edit Breakpoint....
   • In Visual Studio 2022, choose Conditions....

6. Type an expression, such as the answer variable must be greater than 9, and then press Enter to accept it, and note the expression must evaluate to true for the breakpoint to activate, as shown in Figure 4.12:

   

7. Start debugging and note the breakpoint is not hit.
8. Stop debugging.
9. Edit the breakpoint or its conditions and change its expression to less than 9.
10. Start debugging and note the breakpoint is hit.
11. Stop debugging.

12. Edit the breakpoint or its conditions (in Visual Studio 2022, click Add condition), select Hit Count, then enter a number such as 3, meaning that you would have to hit the breakpoint three times before it activates, as shown in Figure 4.13:

    

13. Hover your mouse over the breakpoint's red circle to see a summary, as shown in Figure 4.14:

You have now fixed a bug using some debugging tools and seen some advanced possibilities for setting breakpoints.

Hot reloading using Visual Studio 2022

If you are using Visual Studio, Hot Reload is built into the user interface:

1. In Visual Studio 2022, start the project and note that the message is output every two seconds.
2. Leave the project running.
3. In Program.cs, change Hello to Goodbye.
4. Navigate to Debug | Apply Code Changes or click the Hot Reload button in the toolbar, as shown in Figure 4.15, and note the change is applied without needing to restart the console app.

5. Drop down the Hot Reload button menu and select Hot Reload on File Save, as shown in Figure 4.15:

   

6. Change the message again, save the file, and note the console app updates automatically.

Hot reloading using Visual Studio Code and dotnet watch

If you are using Visual Studio Code, you must issue a special command when starting the console app to activate Hot Reload:

1. In Visual Studio Code, in TERMINAL, start the console app using dotnet watch, and note the output that shows that hot reload is active, as shown in the following output:

dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload.
  💡 Press "Ctrl + R" to restart.
dotnet watch 🔧 Building...
  Determining projects to restore...
  All projects are up-to-date for restore.
  HotReloading -> C:\cs12dotnet8\Chapter04\HotReloading\bin\Debug\net8.0\HotReloading.dll
dotnet watch 🚀 Started
Hello, Hot Reload!
Hello, Hot Reload!
Hello, Hot Reload!

1. In Visual Studio Code, change Hello to Goodbye, and note that, after a couple of seconds, the change is applied without needing to restart the console app, as shown in the following output:

Hello, Hot Reload!
dotnet watch ⌚ File changed: .\Program.cs.
Hello, Hot Reload!
Hello, Hot Reload!
dotnet watch 🔥 Hot reload of changes succeeded.
Goodbye, Hot Reload!
Goodbye, Hot Reload!

1. Press Ctrl + C to stop it running, as shown in the following output:

Goodbye, Hot Reload!
dotnet watch 🛑 Shutdown requested. Press Ctrl+C again to force exit.

Now that you've seen tools for finding and removing bugs during development, let's see how you can track down less obvious problems that might happen during development and production.

Understanding logging options

.NET includes some built-in ways to instrument your code by adding logging capabilities. We will cover the basics in this book. But logging is an area where third parties have created a rich ecosystem of powerful solutions that extend what Microsoft provides. I cannot make specific recommendations because the best logging framework depends on your needs. But I include some common ones in the following list:

• Apache log4net
• NLog
• Serilog

I introduce structured logging using the third-party logging system Serilog in my companion book, Apps and Services with .NET 8, because the Serilog packages have the most downloads on https://www.nuget.org.

Good Practice: When interviewing for a developer position, the logging system used by an organization is a good thing to ask about to show that you understand the importance of logging and you know that the specifics of the implementation are likely to be different depending on the organization.

Instrumenting with Debug and Trace

You have seen the use of the Console type and its WriteLine method writing out to the console window. There is also a pair of types named Debug and Trace that have more flexibility in where they write out to:

• The Debug class is used to add logging that gets written only during development.
• The Trace class is used to add logging that gets written during both development and runtime.

The Debug and Trace classes write to any trace listener. A trace listener is a type that can be configured to write output anywhere you like when the WriteLine method is called. There are several trace listeners provided by .NET, including one that outputs to the console, and you can even make your own by inheriting from the TraceListener type so you can write to anywhere you want.

Writing to the default trace listener

One trace listener, the DefaultTraceListener class, is configured automatically and writes to Visual Studio Code's DEBUG CONSOLE window or Visual Studio's Debug window. You can configure other trace listeners using code.Let's see trace listeners in action:

1. Use your preferred coding tool to add a new Console App / console project named Instrumenting to the Chapter04 solution.
2. In Program.cs, delete the existing statements and then import the System.Diagnostics namespace, as shown in the following code:

using System.Diagnostics; // To use Debug and Trace.

1. In Program.cs, write messages from the two classes, as shown in the following code:

Debug.WriteLine("Debug says, I am watching!");
Trace.WriteLine("Trace says, I am watching!");

1. If you are using Visual Studio 2022, navigate to View | Output and make sure Show output from: Debug is selected.
2. Start the Instrumenting project with debugging, and note that DEBUG CONSOLE in Visual Studio Code or the Output window in Visual Studio 2022 shows the two messages, mixed with other debugging information, such as loaded assembly DLLs, as shown in Figures 4.16 and 4.17:

Configuring trace listeners

Now, we will configure another trace listener that will write to a text file:

1. Before the Debug and Trace calls to WriteLine, add statements to create a new text file on the desktop and pass it into a new trace listener that knows how to write to a text file, and enable automatic flushing for its buffer during development, as shown in the following code:

string logPath = Path.Combine(Environment.GetFolderPath(
    Environment.SpecialFolder.DesktopDirectory), "log.txt");
Console.WriteLine($"Writing to: {logPath}");
TextWriterTraceListener logFile = new(File.CreateText(logPath));
Trace.Listeners.Add(logFile);
#if DEBUG
// Text writer is buffered, so this option calls
// Flush() on all listeners after writing.
Trace.AutoFlush = true;
#endif

Good Practice: Any type that represents a file usually implements a buffer to improve performance. Instead of writing immediately to the file, data is written to an in-memory buffer, and only once the buffer is full will it be written in one chunk to the file. This behavior can be confusing while debugging because we do not immediately see the results! Enabling AutoFlush means the Flush method is called automatically after every write. This reduces performance, so you should only set it on during debugging and not in production.

1. At the bottom of Program.cs, add statements to flush and close any buffered trace listeners for Debug and Trace, as shown in the following code:

// Close the text file (also flushes) and release resources.
Debug.Close();
Trace.Close();

1. Run the release configuration of the console app:
   • In Visual Studio Code, enter the following command in the TERMINAL window for the Instrumenting project and note that nothing will appear to have happened:

dotnet run --configuration Release

• In Visual Studio 2022, in the standard toolbar, select Release in the Solution Configurations drop-down list, note that any statements in a #if DEBUG region are grayed out to indicate they are not compiled, as shown in Figure 4.18, and then navigate to Debug | Start Without Debugging.

1. On your desktop, open the file named log.txt and note that it contains the message Trace says, I am watching!.
2. Run the debug configuration of the console app:
   • In Visual Studio Code, enter the following command in the TERMINAL window for the Instrumenting project:

dotnet run --configuration Debug

• In Visual Studio, in the standard toolbar, select Debug in the Solution Configurations drop-down list and then navigate to Debug | Start Debugging.

1. On your desktop, open the file named log.txt and note that it contains both the message Debug says, I am watching! and also the message Trace says, I am watching!.

Good Practice: When running with the Debug configuration, both Debug and Trace are active and will write to any trace listeners. When running with the Release configuration, only Trace will write to any trace listeners. You can therefore use Debug.WriteLine calls liberally throughout your code, knowing they will be stripped out automatically when you build the release version of your application and will therefore not affect performance.

Switching trace levels

The Trace.WriteLine calls are left in your code, even after release. So, it would be great to have fine control over when they are output. This is something we can do with a trace switch.The value of a trace switch can be set using a number or a word. For example, the number 3 can be replaced with the word Info, as shown in Table 4.1:

Table 4.1: Trace levels

Let's explore using trace switches. First, we will add some NuGet packages to our project to enable loading configuration settings from a JSON appsettings file.

Adding packages to a project in Visual Studio 2022

Visual Studio has a graphical user interface for adding packages:

1. In Solution Explorer, right-click the Instrumenting project and select Manage NuGet Packages.
2. Select the Browse tab.
3. Search for each of these NuGet packages and click the Install button, as shown in Figure 4.19:
   • Microsoft.Extensions.Configuration.Binder
   • Microsoft.Extensions.Configuration.Json

Good Practice: To use preview packages, for example, back in June 2023 for .NET 8 or during most of 2024 for .NET 9, you must select the Include prerelease checkbox as shown in Figure 4.19. There are also packages for loading configuration from XML files, INI files, environment variables, and the command line. Use the most appropriate technique for setting configuration in your projects.

dotnet add package Microsoft.Extensions.Configuration.Binder

dotnet add package Microsoft.Extensions.Configuration.Json

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference
      Include="Microsoft.Extensions.Configuration.Binder" 
      Version="8.0.0" />
    <PackageReference
      Include="Microsoft.Extensions.Configuration.Json" 
      Version="8.0.0" />
  </ItemGroup>
</Project>

{
  "PacktSwitch": {
    "Value": "Info"
  }
}

<ItemGroup>
  <None Update="appsettings.json">
    <CopyToOutputDirectory>Always</CopyToOutputDirectory>
  </None>
</ItemGroup>

using Microsoft.Extensions.Configuration; // To use ConfigurationBuilder.

string settingsFile = "appsettings.json";
string settingsPath = Path.Combine(
  Directory.GetCurrentDirectory(), settingsFile);
Console.WriteLine("Processing: {0}", settingsPath);
Console.WriteLine("--{0} contents--", settingsFile);
Console.WriteLine(File.ReadAllText(settingsPath));
Console.WriteLine("----");
ConfigurationBuilder builder = new();
builder.SetBasePath(Directory.GetCurrentDirectory());
// Add the settings file to the processed configuration and make it
// mandatory so an exception will be thrown if the file is not found.
builder.AddJsonFile(settingsFile,
  optional: false, reloadOnChange: true);
IConfigurationRoot configuration = builder.Build(); 
TraceSwitch ts = new(
  displayName: "PacktSwitch",
  description: "This switch is set via a JSON config."); 
configuration.GetSection("PacktSwitch").Bind(ts);
Console.WriteLine($"Trace switch value: {ts.Value}");
Console.WriteLine($"Trace switch level: {ts.Level}");
Trace.WriteLineIf(ts.TraceError, "Trace error"); 
Trace.WriteLineIf(ts.TraceWarning, "Trace warning"); 
Trace.WriteLineIf(ts.TraceInfo, "Trace information"); 
Trace.WriteLineIf(ts.TraceVerbose, "Trace verbose");

// Close the text file (also flushes) and release resources.
Debug.Close();
Trace.Close();
Console.WriteLine("Press enter to exit.");
Console.ReadLine();

{
  "PacktSwitch": { 
    "Value": "2"
  }
}

dotnet run --configuration Release

Trace says, I am watching! 
Trace error
Trace warning

Logging information about your source code

When you write to a log, you will often want to include the name of the source code file, the name of the method, and the line number. In C# 10 and later, you can even get any expressions passed as an argument to a function as a string value so you can log them.You can get all this information from the compiler by decorating function parameters with special attributes, as shown in Table 4.2:

Table 4.2: Attributes to get information about the method caller

You must make these parameters optional by assigning default values to them.Let's see some code in action:

1. In the Instrumenting project, add a class file named Program.Functions.cs.
2. Delete any existing statements and then add statements to define a function named LogSourceDetails that uses the four special attributes to log information about the calling code, as shown in the following code:

using System.Diagnostics; // To use Trace.
using System.Runtime.CompilerServices; // To use [CallerX] attributes
partial class Program
{
  static void LogSourceDetails(
    bool condition,
    [CallerMemberName] string member = "",
    [CallerFilePath] string filepath = "", 
    [CallerLineNumber] int line = 0,
    [CallerArgumentExpression(nameof(condition))] string expression = "")
  {
    Trace.WriteLine(string.Format(
      "[{0}]\n  {1} on line {2}. Expression: {3}",
      filepath, member, line, expression));
  }
}

1. In Program.cs, at the bottom of the file, before the calls to close Debug and Trace, add statements to declare and set a variable that will be used in an expression that is passed to the function named LogSourceDetails, as shown highlighted in the following code:

int unitsInStock = 12;
LogSourceDetails(unitsInStock > 10);
// Close the text file (also flushes) and release resources.
Debug.Close();
Trace.Close();

We are just making up an expression in this scenario. In a real project, this might be an expression that is dynamically generated by the user making user interface selections to query a database or so on.

1. Run the console app without debugging, press Enter and close the console app, and then open the log.txt file and note the result, as shown in the following output:

[C:\cs12dotnet8\Chapter04\Instrumenting\Program.cs]
  <Main>$ on line 44. Expression: unitsInStock > 10

Understanding types of testing

Unit testing is just one of many types of testing, as described in Table 4.3:

Table 4.3: Types of testing

Creating a class library that needs testing

First, we will create a function that needs testing. We will create it in a class library project separate from a console app project. A class library is a package of code that can be distributed and referenced by other .NET applications:

1. Use your preferred coding tool to add a new Class Library / classlib project named CalculatorLib to the Chapter04 solution.

At this point, you will have created about a dozen new console app projects and added them to a solution. The only difference when adding a Class Library / classlib is to select a different project template. The rest of the steps are the same as adding a Console App / console project.

• If you are using Visual Studio 2022:

1. Navigate to File | Add | New Project.
2. In the Add a new project dialog, search for and select Class Library [C#] and then click Next.
3. In the Configure your new project dialog, for the Project name, enter CalculatorLib, leave the location as C:\cs12dotnet8\Chapter04, and then click Next.
4. In the Additional information dialog, select .NET 8.0 (Long Term Support), and then click Create.

• If you are using Visual Studio Code:

1. In TERMINAL, switch to a terminal in the Chapter04 folder.
2. Use the dotnet CLI to create a new class library project named CalculatorLib, as shown in the following command: dotnet new classlib -o CalculatorLib
3. Use the dotnet CLI to add the new project folder to the solution, as shown in the following command: dotnet sln add CalculatorLib
4. Note the results, as shown in the following output: Project `CalculatorLib\CalculatorLib.csproj` added to the solution.

1. For all code editors, in the CalculatorLib project, rename the file named Class1.cs to Calculator.cs.
2. In Calculator.cs, modify the file to define a Calculator class (with a deliberate bug!), as shown in the following code:

namespace CalculatorLib;
public class Calculator
{
  public double Add(double a, double b)
  {
    return a * b;
  }
}

1. Compile your class library project:
   • In Visual Studio 2022, navigate to Build | Build CalculatorLib.
   • In Visual Studio Code, in a TERMINAL window for the CalculatorLib folder, enter the command dotnet build. (You could also run this command in the Chapter04 folder but that would build the whole solution, which is unnecessary in this scenario.)
2. Use your preferred coding tool to add a new xUnit Test Project [C#] / xunit project named CalculatorLibUnitTests to the Chapter04 solution. For example, at the command prompt or terminal in the Chapter04 folder, enter the following commands:

dotnet new xunit -o CalculatorLibUnitTests
dotnet sln add CalculatorLibUnitTests

1. In the CalculatorLibUnitTests project, add a project reference to the CalculatorLib project:
   • If you are using Visual Studio 2022, in Solution Explorer, select the CalculatorLibUnitTests project, navigate to Project | Add Project Reference…, check the box to select the CalculatorLib project, and then click OK.
   • If you are using Visual Studio Code, use the dotnet add reference command, or in the file named CalculatorLibUnitTests.csproj, modify the configuration to add an item group with a project reference to the CalculatorLib project, as shown highlighted in the following markup:

<ItemGroup>
  <ProjectReference
    Include="..\CalculatorLib\CalculatorLib.csproj" />
</ItemGroup>

The path for a project reference can use either forward / or back slashes \ because the paths are processed by the .NET SDK and changed if necessary for the current operating system.

1. Build the CalculatorLibUnitTests project.