1. In Program.cs , set Bob's favorite wonder to an invalid enum value like 128, as shown in the following code:

bob.FavoriteAncientWonder = (WondersOfTheAncientWorld)128;

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

Unhandled exception. System.ArgumentException: 128 is not a member of the WondersOfTheAncientWor

1. In Program.cs , set Bob's favorite wonder back to a valid single enum value.

Defining indexers‌

Indexers allow the calling code to use the array syntax to access a property. For example, the string type defines an indexer so that the calling code can access individual characters in the string , as shown in the following code:

string alphabet = "abcdefghijklmnopqrstuvwxyz";

char letterF = alphabet[5]; // 0 is a, 1 is b, and so on.

You can overload indexers so that different types can be used for their parameters. For example, as well as passing an int value, you could also pass a string value.We will define an indexer to simplify access to the children of a person:

1. In PersonAutoGen.cs , add statements to define an indexer to get and set a child using the index of the child, as shown in the following code:

#region Indexers: Properties that use array syntax to access them. public Person this[int index]

{

get

{

return Children[index]; // Pass on to the List indexer.

}

set

{

Children[index] = value;

}

}

#endregion

1. In PersonAutoGen.cs , add statements to define an indexer to get and set a child using the name of the child, as shown in the following code:

// A read-only string indexer. public Person this[string name]

{

get

{

return Children.Find(p => p.Name == name);

}

}

You will learn more about collections like List in Chapter 8, Working with Common

.NET Types, and how to write lambda expressions using => in Chapter 11, Querying and

Manipulating Data Using LINQ.

1. In Program.cs , add statements to add two children to Sam , and then access the first and second child using the longer Children field and the shorter indexer syntax, as shown in the following code:

sam.Children.Add(new() { Name = "Charlie",

Born = new(2010, 3, 18, 0, 0, 0, TimeSpan.Zero) }); sam.Children.Add(new() { Name = "Ella",

Born = new(2020, 12, 24, 0, 0, 0, TimeSpan.Zero) });

// Get using Children list.

WriteLine($"Sam's first child is {sam.Children[0].Name}."); WriteLine($"Sam's second child is {sam.Children[1].Name}.");

// Get using the int indexer.

WriteLine($"Sam's first child is {sam[0].Name}."); WriteLine($"Sam's second child is {sam[1].Name}.");

// Get using the string indexer.

WriteLine($"Sam's child named Ella is {sam["Ella"].Age} years old.");

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

Sam's first child is Charlie. Sam's second child is Ella.

Sam's first child is Charlie. Sam's second child is Ella.

Sam's child named Ella is 3 years old.

Pattern matching with objects‌

In Chapter 3, Controlling Flow, Converting Types, and Handling Exceptions, you were introduced to basic pattern matching. In this section, we will explore pattern matching in more detail.

Pattern-matching flight passengers‌

In this example, we will define some classes that represent various types of passengers on a flight, and then we will use a switch expression with pattern matching to determine the cost of their flight:

In the PacktLibraryNetStandard2 project/folder, add a new file named FlightPatterns.cs .

If you use Visual Studio 2022, in FlightPatterns.cs , delete the existing statements, including the class named FlightPatterns , because we will define multiple classes, and none match the name of the code file.

In FlightPatterns.cs , add statements to define three types of passenger with different properties, as shown in the following code:

// All the classes in this file will be defined in the following namespace. namespace Packt.Shared;

public class Passenger

{

public string? Name { get; set; }

}

public class BusinessClassPassenger : Passenger

{

public override string ToString()

{

return $"Business Class: {Name}";

}

}

public class FirstClassPassenger : Passenger

{

public int AirMiles { get; set; }

public override string ToString()

{

return $"First Class with {AirMiles:N0} air miles: {Name}";

}

}

public class CoachClassPassenger : Passenger

{

public double CarryOnKG { get; set; } public override string ToString()

{

return $"Coach Class with {CarryOnKG:N2} KG carry on: {Name}";

}

}

You will learn about overriding the ToString method in Chapter 6, Implementing Interfaces and Inheriting Classes.

1. In Program.cs , add statements to define an object array containing five passengers of various types and property values, and then enumerate them, outputting the cost of their flight, as shown in the following code:

// An array containing a mix of passenger types. Passenger[] passengers = {

new FirstClassPassenger { AirMiles = 1_419, Name = "Suman" }, new FirstClassPassenger { AirMiles = 16_562, Name = "Lucy" }, new BusinessClassPassenger { Name = "Janice" },

new CoachClassPassenger { CarryOnKG = 25.7, Name = "Dave" }, new CoachClassPassenger { CarryOnKG = 0, Name = "Amit" },

};

foreach (Passenger passenger in passengers)

{

decimal flightCost = passenger switch

{

FirstClassPassenger p when p.AirMiles > 35_000 => 1_500M, FirstClassPassenger p when p.AirMiles > 15_000 => 1_750M, FirstClassPassenger _ => 2_000M,

BusinessClassPassenger _ => 1_000M, CoachClassPassenger p when p.CarryOnKG < 10.0 => 500M, CoachClassPassenger _ => 650M,

_ => 800M

};

WriteLine($"Flight costs {flightCost:C} for {passenger}");

}

While reviewing the preceding code, note the following:

image

Most code editors do not align the lambda symbols => as I have done above.

image

To pattern match on the properties of an object, you must name a local variable, like

p , which can then be used in an expression.

image

To pattern match on a type only, you can use _ to discard the local variable, for example, FirstClassPassenger _ means that you match on the type but you don't care what values any of its properties have, so a named variable like p is not needed. In a moment, you will see how we can improve the code even more.

image

The switch expression also uses _ to represent its default branch.

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

Flight costs $2,000.00 for First Class with 1,419 air miles: Suman Flight costs $1,750.00 for First Class with 16,562 air miles: Lucy Flight costs $1,000.00 for Business Class: Janice

Flight costs $650.00 for Coach Class with 25.70 KG carry on: Dave Flight costs $500.00 for Coach Class with 0.00 KG carry on: Amit

Enhancements to pattern matching in C# 9 or later‌

The previous examples worked with C# 8. Now we will look at some enhancements in C# 9 and later. First, you no longer need to use the underscore to discard the local variable when doing type matching:

1. In Program.cs , comment out the C# 8 syntax, and add C# 9 and later syntax to modify the branches for first-class passengers to use a nested switch expression and the new support for conditionals, like > , as highlighted in the following code:

decimal flightCost = passenger switch

{

/* C# 8 syntax

FirstClassPassenger p when p.AirMiles > 35_000 => 1_500M, FirstClassPassenger p when p.AirMiles > 15_000 => 1_750M, FirstClassPassenger _ => 2_000M, */

// C# 9 or later syntax FirstClassPassenger p => p.AirMiles switch

{

> 35_000 => 1_500M,

> 15_000 => 1_750M,

_ => 2_000M

},

BusinessClassPassenger => 1_000M, CoachClassPassenger p when p.CarryOnKG < 10.0 => 500M, CoachClassPassenger => 650M,

_ => 800M

};

1. Run the PeopleApp project to view the results, and note that they are the same as before.

You could also use the relational pattern in combination with the property pattern to avoid the nested switch expression, as shown in the following code:

FirstClassPassenger { AirMiles: > 35000 } => 1500, FirstClassPassenger { AirMiles: > 15000 } => 1750M, FirstClassPassenger => 2000M,

More Information: There are many more ways to use pattern matching in your projects. I recommend that you review the official documentation at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern- matching.

Working with record types‌

Before we dive into the new record language feature, let us see some other related new features of C# 9 and later.

Init-only properties‌

You have used object initialization syntax to instantiate objects and set initial properties throughout this chapter. Those properties can also be changed after instantiation.Sometimes, you want to treat properties like readonly fields so that they can be set during instantiation but not after. In other words, they are immutable. The init keyword enables this. It can be used in place of the set keyword in a property definition.Since this is a language feature not supported by .NET Standard 2.0, we cannot use it in the PacktLibraryNetStandard2 project. We must use it in the modern project:

In the PacktLibraryModern project, add a new file named Records.cs .

In Records.cs , define a person class with two immutable properties, as shown in the following code:

namespace Packt.Shared; public class ImmutablePerson

{

public string? FirstName { get; init; } public string? LastName { get; init; }

}

1. In Program.cs , add statements to instantiate a new immutable person, and then try to change one of its properties, as shown in the following code:

ImmutablePerson jeff = new()

{

FirstName = "Jeff", LastName = "Winger"

};

jeff.FirstName = "Geoff";

1. Compile the console app and note the compile error, as shown in the following output:

C:\cs12dotnet8\Chapter05\PeopleApp\Program.cs(404,1): error CS8852: Init-only property or indexe

1. Comment out the attempt to set the FirstName property after instantiation.

Even if you do not set FirstName in the object initializer, you still would not be able to set it post-initialization. If you need to force a property to be set, then apply the required keyword that you learned about earlier in this chapter.

Defining record types‌

Init-only properties provide some immutability to C#. You can take the concept further by using record types. These are defined by using the record keyword instead of (or as well as) the class keyword. That can make the whole object immutable, and it acts like a value when compared. We will discuss equality and comparisons of classes, records, and value types in more detail in Chapter 6, Implementing Interfaces and Inheriting Classes.Immutable records should not have any state (properties and fields) that change after instantiation. Instead, the idea is that you create new records from existing ones. The new record has the changed state. This is called non-destructive mutation. To do this, C# 9 introduced the

with keyword:

1. In Records.cs , add a record named ImmutableVehicle after the ImmutablePerson class, as shown in the following code:

public record ImmutableVehicle

{

public int Wheels { get; init; } public string? Color { get; init; } public string? Brand { get; init; }

}

1. In Program.cs , add statements to create a car and then a mutated copy of it, as shown in the following code:

ImmutableVehicle car = new()

{

Brand = "Mazda MX-5 RF",

Color = "Soul Red Crystal Metallic", Wheels = 4

};

ImmutableVehicle repaintedCar = car

with { Color = "Polymetal Grey Metallic" }; WriteLine($"Original car color was {car.Color}."); WriteLine($"New car color is {repaintedCar.Color}.");

1. Run the PeopleApp project to view the results, and note the change to the car color in the mutated copy, as shown in the following output:

Original car color was Soul Red Crystal Metallic. New car color is Polymetal Grey Metallic.

You could also release the memory for the car variable and the repaintedCar would still fully exist.

Equality of record types‌

One of the most important behaviors of record types is their equality. Two records with the same property values are considered equal. This may not sound surprising, but if you used a normal class instead of a record, then they would not be considered equal. Let's see:

In the PacktLibraryModern project, add a new file named Equality.cs .

In Equality.cs , define a class and a record type, as shown in the following code:

namespace Packt.Shared; public class AnimalClass

{

public string? Name { get; set; }

}

public record AnimalRecord

{

public string? Name { get; set; }

}

1. In Program.cs , add statements to create two instances of AnimalClass and two instances of AnimalRecord , and then compare them for equality, as shown in the following code:

AnimalClass ac1 = new() { Name = "Rex" }; AnimalClass ac2 = new() { Name = "Rex" }; WriteLine($"ac1 == ac2: {ac1 == ac2}"); AnimalRecord ar1 = new() { Name = "Rex" }; AnimalRecord ar2 = new() { Name = "Rex" }; WriteLine($"ar1 == ar2: {ar1 == ar2}");

1. Run the PeopleApp project to view the results, and note that two class instances are not equal even if they have the same property values, and two record instances are equal if they have the same property values, as shown in the following output:

ac1 == ac2: False ar1 == ar2: True

Class instances are only equal if they are literally the same object. This is true when their memory addresses are equal. You will learn more about the equality of types in Chapter 6, Implementing Interfaces and Inheriting Classes.

Positional data members in records‌

The syntax for defining a record can be greatly simplified using positional data members. Instead of using object initialization syntax with curly braces, sometimes you might prefer to provide a constructor with positional parameters, as you saw earlier in this chapter. You can also combine this with a deconstructor to split the object into individual parts, as shown in the following code:

public record ImmutableAnimal

{

public string Name { get; init; } public string Species { get; init; }

public ImmutableAnimal(string name, string species)

{

Name = name;

Species = species;

}

public void Deconstruct(out string name, out string species)

{

name = Name; species = Species;

}

}

The properties, constructor, and deconstructor can be generated for you:

1. In Records.cs , add statements to define another record using simplified syntax, known as positional records, as shown in the following code:

// Simpler syntax to define a record that auto-generates the

// properties, constructor, and deconstructor.

public record ImmutableAnimal(string Name, string Species);

1. In Program.cs , add statements to construct and deconstruct immutable animals, as shown in the following code:

ImmutableAnimal oscar = new("Oscar", "Labrador");

var (who, what) = oscar; // Calls the Deconstruct method. WriteLine($"{who} is a {what}.");

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

Oscar is a Labrador.

You will see records again when we look at C# 10 support to create struct records in

Chapter 6, Implementing Interfaces and Inheriting Classes.

More Information: There are many more ways to use records in your projects. I recommend that you review the official documentation at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/tutorials/records.

Defining a primary constructor for a class‌

Introduced with C# 12, you can define one constructor as part of the class definition. This is called the primary constructor. The syntax is the same as for positional data members in records, but the behavior is slightly different.Traditionally, we separate the class definition from any constructors, as shown in the following code:

public class Headset // Class definition.

{

// Constructor.

public Headset(string manufacturer, string productName)

{

// You can reference manufacturer and productName parameters in

// the constructor and the rest of the class.

}

}

With class primary constructors, you combine both into a more succinct syntax, as shown in the following code:

public class Headset(string manufacturer, string productName);

Let's see an example:

In the PacktLibraryModern project, add a class file named Headset.cs .

Modify the code file contents to give the class two parameters for manufacturer and product name respectively, as shown in the following code:

namespace Packt.Shared;

public class Headset(string manufacturer, string productName);

1. In Program.cs , add statements to instantiate a headset, as shown in the following code:

Headset vp = new("Apple", "Vision Pro"); WriteLine($"{vp.ProductName} is made by {vp.Manufacturer}.");

One of the differences between a record and a class type with a primary constructor is that its parameters don't become public properties automatically, so you will see CS1061 compiler errors. Neither ProductName nor productName are accessible outside the class.

1. In Headset.cs , modify the parameter declarations to make their first character lowercase, and then add statements to define two properties and set them using the parameters passed to the primary constructor, as highlighted in the following code:

namespace Packt.Shared;

public class Headset(string manufacturer, string productName)

{

public string Manufacturer { get; set; } = manufacturer; public string ProductName { get; set; } = productName;

}

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

Vision Pro is made by Apple.

1. In Program.cs , add a default parameterless constructor, as highlighted in the following code:

namespace Packt.Shared;

public class Headset(string manufacturer, string productName)

{

public string Manufacturer { get; set; } = manufacturer; public string ProductName { get; set; } = productName;

// Default parameterless constructor calls the primary constructor. public Headset() : this("Microsoft", "HoloLens") { }

}

1. In Program.cs , create an uninitialized instance of a headset and an instance for Meta Quest 3, as shown in the following code:

Headset holo = new();

WriteLine($"{holo.ProductName} is made by {holo.Manufacturer}."); Headset mq = new() { Manufacturer = "Meta", ProductName = "Quest 3" }; WriteLine($"{mq.ProductName} is made by {mq.Manufacturer}.");

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

Vision Pro is made by Apple. HoloLens is made by Microsoft. Quest 3 is made by Meta.

More Information: You can learn more about primary constructors for classes and structs at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/whats- new/tutorials/primary-constructors.

Practicing and exploring‌

Test your knowledge and understanding by answering some questions, getting some hands-on practice, and exploring this chapter's topics with deeper research.

Exercise 5.1 – Test your knowledge‌

Answer the following questions:

What are the seven access modifier keywords and combinations of keywords, and what do they do?

What is the difference between the static , const , and readonly keywords when applied to a type member?

What does a constructor do?

Why should you apply the [Flags] attribute to an enum type when you want to store combined values?

Why is the partial keyword useful?

What is a tuple?

What does the record keyword do?

What does overloading mean?

What is the difference between the following two statements? (Do not just say a ">" character!)

public List Children = new(); public List Children => new();

1. How do you make a method parameter optional?

Exercise 5.2 – Practice with access modifiers‌

Imagine that you are the compiler. What errors would you show when building the following projects? What would need to change to fix it?In a class library project, in Car.cs :

class Car

{

int Wheels { get; set; } public bool IsEV { get; set; } internal void Start()

{

Console.WriteLine("Starting...");

}

}

In a console app project that references the class library project, in Program.cs :

Car fiat = new() { Wheels = 4, IsEV = true }; fiat.Start();

Exercise 5.3 – 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-5--- building-your-own-types-with-object-oriented-programming

Summary‌

In this chapter, you learned about:

image

Making your own types using OOP.

image

Some of the different categories of members that a type can have, including fields to store data and methods to perform actions.

image

OOP concepts, such as aggregation and encapsulation

image

How to use modern C# features, like relational and property pattern matching enhancements, init -only properties, and record types.

In the next chapter, you will take these concepts further by defining operators, delegates, and events, implementing interfaces, and inheriting from existing classes.

Implementing Interfaces and Inheriting Classes‌‌‌

Join our book community on Discord

https://packt.link/EarlyAccess

image

This chapter is about deriving new types from existing ones using object-oriented programming (OOP). You will learn how to use operators as an alternative method to implement simple functionality, and you will learn how to use generics to make your code safer and more performant. You will learn about delegates and events to exchange messages between types. You will see the differences between reference and value types. You will implement interfaces for common functionality. You will create a derived class to inherit from a base class to reuse functionality, override an inherited type member, and use polymorphism. Finally, you will learn how to create extension methods and cast between classes in an inheritance hierarchy.This chapter covers the following topics:

image

image

Setting up a class library and console application Static methods and overloading operators

image

image

Making types safely reusable with generics Raising and handling events

image

Implementing interfaces

image

image

Managing memory with reference and value types Working with null values

image

Inheriting from classes

image

image

image

Casting within inheritance hierarchies Inheriting and extending .NET types Summarizing custom type choices

Setting up a class library and console application‌

We will start by defining a solution with two projects, like the one created in Chapter 5, Building Your Own Types with Object-Oriented Programming. Even if you completed all the exercises in that chapter, follow the instructions below so that you start this chapter with fresh working projects:

Use your preferred coding tool to create a new project, as defined in the following list:

image

image

image

image

Project template: Class Library / classlib Project file and folder: PacktLibrary Solution file and folder: Chapter06 Framework: .NET 8.0 (Long-Term Support)

Add a new project, as defined in the following list:

image

Project template: Console App / console

image

Project file and folder: PeopleApp

image

image

image

image

Solution file and folder: Chapter06 Framework: .NET 8.0 (Long-Term Support) Do not use top-level statements: Cleared. Enable native AOT publish: Cleared.

In this chapter, both projects target .NET 8 and, therefore, use the C# 12 compiler by default.

In the PacktLibrary project, rename the file named Class1.cs to Person.cs .

In both projects, add to globally and statically import the System.Console

class, as shown in the following markup:

1. In Person.cs , delete any existing statements and define a Person class, as shown in the following code:

namespace Packt.Shared; public class Person

{

#region Properties

public string? Name { get; set; }

public DateTimeOffset Born { get; set; } public List Children = new(); #endregion

#region Methods

public void WriteToConsole()

{

WriteLine($"{Name} was born on a {Born:dddd}.");

}

public void WriteChildrenToConsole()

{

string term = Children.Count == 1 ? "child" : "children"; WriteLine($"{Name} has {Children.Count} {term}.");

}

#endregion

}

1. In the PeopleApp project, add a project reference to PacktLibrary , as shown in the following markup:

1. In Program.cs , delete the existing statements, write statements to create an instance of Person , and then write information about it to the console, as shown in the following code:

using Packt.Shared;

Person harry = new()

{

Name = "Harry",

Born = new(year: 2001, month: 3, day: 25,

hour: 0, minute: 0, second: 0, offset: TimeSpan.Zero)

};

harry.WriteToConsole();

If you use Visual Studio 2022, configure the startup project for the solution as the current selection.

Run the PeopleApp project and note the result, as shown in the following output:

Harry was born on a Sunday.

Static methods and overloading operators‌

This section is specifically about methods that apply to two instances of the same type. It is not about the more general case of methods that apply to zero, one, or more than two instances.I wanted to think of some methods that would apply to two Person instances that could also become operators, like + and * . What would adding two people together represent? What would multiplying two people represent? The obvious answers are getting married and having babies.

We will design our methods to enable us to model the story of Lamech and his two wives and their children, as described at the following link: https://www.kingjamesbibleonline.org/Genesis-4-19/.

We might want two instances of Person to be able to marry and procreate. We can implement this by writing methods and overriding operators. Instance methods are actions that an object does to itself; static methods are actions the type does.Which you choose depends on what makes the most sense for the action.

Good Practice: Having both static and instance methods to perform similar actions often makes sense. For example, string has both a Compare static method and a CompareTo instance method. This puts the choice of how to use the functionality in the hands of the programmers using your type, giving them more flexibility.

Implementing functionality using methods‌

Let's start by implementing some functionality by using both static and instance methods:

1. In Person.cs , add properties with private backing storage fields to indicate if that person is married and to whom, as shown in the following code:

// Allow multiple spouses to be stored for a person. public List Spouses = new();

// A read-only property to show if a person is married to anyone. public bool Married => Spouses.Count > 0;

1. In Person.cs , add one instance method and one static method that will allow two Person

objects to marry, as shown in the following code:

// Static method to marry two people.

public static void Marry(Person p1, Person p2)

{

ArgumentNullException.ThrowIfNull(p1); ArgumentNullException.ThrowIfNull(p2);

if (p1.Spouses.Contains(p2) || p2.Spouses.Contains(p1))

{

throw new ArgumentException(

string.Format("{0} is already married to {1}.", arg0: p1.Name, arg1: p2.Name));

}

p1.Spouses.Add(p2); p2.Spouses.Add(p1);

}

// Instance method to marry another person. public void Marry(Person partner)

{

Marry(this, partner); // "this" is the current person.

}

Note the following:

image

In the static method, the Person objects are passed as parameters named p1 and p2 , and guard clauses are used to check for null values. If either is already married to the other an exception is thrown; otherwise, they are each added to each other's list of spouses. You can model this differently if you want to allow two people to have multiple marriage ceremonies. In that case, you might choose to not throw an exception and instead do nothing. Their state of marriage would remain the same. Additional calls to Marry would not change if they are married or not. In this scenario, I want you to see that the code recognizes that they are already married by throwing an exception.

image

In the instance method, a call is made to the static method, passing the current person ( this ) and the partner they want to marry.

1. In Person.cs , add an instance method to the Person class that will output the spouses of a person if they are married, as shown in the following code:

public void OutputSpouses()

{

if (Married)

{

string term = Spouses.Count == 1 ? "person" : "people"; WriteLine($"{Name} is married to {Spouses.Count} {term}:"); foreach (Person spouse in Spouses)

{

WriteLine($" {spouse.Name}");

}

}

else

{

WriteLine($"{Name} is a singleton.");

}

}

1. In Person.cs , add one instance method and one static method to the Person class that will allow two Person objects to procreate if they are married to each other, as shown in the following code:

///

/// Parent 1

/// Parent 2

/// A Person object that is the child of Parent 1 and Parent 2.

/// If p1 or p2 are null.

/// If p1 and p2 are not married. public static Person Procreate(Person p1, Person p2)

{

ArgumentNullException.ThrowIfNull(p1); ArgumentNullException.ThrowIfNull(p2);

if (!p1.Spouses.Contains(p2) && !p2.Spouses.Contains(p1))

{

throw new ArgumentException(string.Format(

"{0} must be married to {1} to procreate with them.", arg0: p1.Name, arg1: p2.Name));

}

Person baby = new()

{

Name = $"Baby of {p1.Name} and {p2.Name}", Born = DateTimeOffset.Now

};

p1.Children.Add(baby); p2.Children.Add(baby); return baby;

}

// Instance method to "multiply".

public Person ProcreateWith(Person partner)

{

return Procreate(this, partner);

}

Note the following:

image

In the static method named Procreate , the Person objects that will procreate are passed as parameters named p1 and p2 .

image

A new Person class named baby is created with a name composed of a combination of the two people who have procreated. This could be changed later by setting the returned baby variable's Name property. Although we could add a third parameter to the Procreate method for the baby name, we will define a binary operator later, and they

cannot have third parameters, so for consistency, we will just return the baby reference and let the calling code set the name of it.

image

The baby object is added to the Children collection of both parents and then returned. Classes are reference types, meaning a reference to the baby object stored in memory is added, not a clone of the baby object. You will learn the difference between reference types and value types later in Chapter 6, Implementing Interfaces and Inheriting Classes.

image

In the instance method named ProcreateWith , the Person object to procreate with is passed as a parameter named partner , and that, along with this , is passed to the static Procreate method to reuse the method implementation. this is a keyword that references the current instance of the class. It is a convention to use a different method name for related static and instance methods, for example, Compare(x, y) for the static method name and x.CompareTo(y) for the instance method name.

Good Practice: A method that creates a new object, or modifies an existing object, should return a reference to that object so that the caller can access the results.

1. In Program.cs , create three people and have them marry and then procreate with each other, noting that to add a double-quote character into a string , you must prefix it with a backslash character like this, \" , as shown in the following code:

// Implementing functionality using methods. Person lamech = new() { Name = "Lamech" }; Person adah = new() { Name = "Adah" }; Person zillah = new() { Name = "Zillah" };

// Call the instance method to marry Lamech and Adah. lamech.Marry(adah);

// Call the static method to marry Lamech and Zillah. Person.Marry(lamech, zillah);

lamech.OutputSpouses(); adah.OutputSpouses(); zillah.OutputSpouses();

// Call the instance method to make a baby. Person baby1 = lamech.ProcreateWith(adah); baby1.Name = "Jabal";

WriteLine($"{baby1.Name} was born on {baby1.Born}");

// Call the static method to make a baby.

Person baby2 = Person.Procreate(zillah, lamech); baby2.Name = "Tubalcain"; adah.WriteChildrenToConsole(); zillah.WriteChildrenToConsole(); lamech.WriteChildrenToConsole();

for (int i = 0; i < lamech.Children.Count; i++) { WriteLine(format: " {0}'s child #{1} is named \"{2}\".", arg0: lamech.Name, arg1: i, arg2: lamech.Children[i].Name); } I used a for instead of a foreach statement so that I could use the i variable with the indexer to access each child. 1. Run the PeopleApp project and view the result, as shown in the following output: Lamech is married to 2 people: Adah Zillah Adah is married to 1 person: Lamech Zillah is married to 1 person: Lamech Jabal was born on 05/07/2023 15:17:03 +01:00 Adah has 1 child. Zillah has 1 child. Lamech has 2 children: Lamech's child #0 is named "Jabal". Lamech's child #1 is named "Tubalcain". As you have just seen, for functionality that applies to two instances of an object type, it is easy to provide both static and instance methods to implement the same functionality. Neither static nor instance methods are best in all scenarios, and you cannot predict how your type might be used. It is best to provide both to allow a developer to use your types in the way that best fits the way they need.Now let's see how we can add a third way to provide the same functionality for two instances of a type. Implementing functionality using operators‌ The System.String class has a static method named Concat that concatenates two string values and returns the result, as shown in the following code: string s1 = "Hello "; string s2 = "World!"; string s3 = string.Concat(s1, s2); WriteLine(s3); // Hello World! Calling a method like Concat works, but it might be more natural for a programmer to use the + symbol operator to "add" two string values together, as shown in the following code: string s3 = s1 + s2; A well-known biblical phrase is Go forth and multiply, meaning to procreate. Let's write code so that the * (multiply) symbol will allow two Person objects to procreate. And we will use the + operator to marry two people.We do this by defining a static operator for the * symbol. The syntax is rather like a method, because in effect, an operator is a method, but it uses a symbol instead of a method name, which makes the syntax more concise: 1. In Person.cs , create a static operator for the + symbol, as shown in the following code: #region Operators // Define the + operator to "marry". public static bool operator +(Person p1, Person p2) { Marry(p1, p2); // Confirm they are both now married. return p1.Married && p2.Married; } #endregion The return type for an operator does not need to match the types passed as parameters to the operator, but the return type cannot be void . 1. In Person.cs , create a static operator for the * symbol, as shown in the following code: // Define the * operator to "multiply". public static Person operator *(Person p1, Person p2) { // Return a reference to the baby that results from multiplying. return Procreate(p1, p2); } Good Practice: Unlike methods, operators do not appear in IntelliSense lists for a type or a type instance when you enter a dot ( . ). For every operator that you define, make a method as well, because it may not be obvious to a programmer that the operator is available. The implementation of the operator can then call the method, reusing the code you have written. A second reason to provide a method is that operators are not supported by every language compiler; for example, although arithmetic operators like * are supported by Visual Basic and F#, there is no requirement that other languages support all operators supported by C#. You have to read the type definition or the documentation to discover if operators are implemented. 1. In Program.cs , comment out the statement that calls that static Marry method to marry Zillah and Lamech, and replace it with an if statement that uses the + operator to marry them, as shown in the following code: // Person.Marry(lamech, zillah); if (lamech + zillah) { WriteLine($"{lamech.Name} and {zillah.Name} successfully got married."); } 1. In Program.cs , after calling the Procreate method and before the statements that write the children to the console, use the * operator for Lamech to make two more babies with his wives Adah and Zillah, as highlighted in the following code: // Use the * operator to "multiply". Person baby3 = lamech * adah; baby3.Name = "Jubal"; Person baby4 = zillah * lamech; baby4.Name = "Naamah"; 1. Run the PeopleApp project and view the result, as shown in the following output: Lamech and Zillah successfully got married. Lamech is married to 2 people: Adah Zillah Adah is married to 1 person: Lamech Zillah is married to 1 person: Lamech Jabal was born on 05/07/2023 15:27:30 +01:00 Adah has 2 children. Zillah has 2 children. Lamech has 4 children: Lamech's child #0 is named "Jabal". Lamech's child #1 is named "Tubalcain". Lamech's child #2 is named "Jubal". Lamech's child #3 is named "Naamah". More Information: To learn more about operator overloading, you can read the documentation at the following link: https://learn.microsoft.com/en- us/dotnet/csharp/language-reference/operators/operator-overloading. Making types safely reusable with generics‌ In 2005, with C# 2 and .NET Framework 2, Microsoft introduced a feature named generics, which enables your types to be more safely reusable and more efficient. It does this by allowing a programmer to pass types as parameters, like how you can pass objects as parameters. This topic is only about types that need to provide flexibility for the types it works with. For example, collection types need to be able to store multiple instances of any type. That flexibility can be provided either by using the System.Object type or generics. For other scenarios that do not need type flexibility, the use of non-generic types is good practice. Working with non-generic types‌ First, let's look at an example of working with a non-generic type so that you can understand the problems that generics are designed to solve, such as weakly typed parameters and values, and performance problems caused by using System.Object . System.Collections.Hashtable can be used to store multiple values, each with a unique key that can later be used to quickly look up its value. Both the key and value can be any object because they are declared as System.Object . Although this provides flexibility, it is slow, and bugs are easier to introduce because no type checks are made when adding items.Let's write some code: 1. In Program.cs , create an instance of the non-generic collection, System.Collections.Hashtable , and then add four items to it, as shown in the following code: // Non-generic lookup collection. System.Collections.Hashtable lookupObject = new(); lookupObject.Add(key: 1, value: "Alpha"); lookupObject.Add(key: 2, value: "Beta"); lookupObject.Add(key: 3, value: "Gamma"); lookupObject.Add(key: harry, value: "Delta"); Note that three items have a unique integer key to look them up. The last item has a Person object as its key to look it up. This is valid in a non-generic collection. 1. Add statements to define a key with the value of 2 and use it to look up its value in the hash table, as shown in the following code: int key = 2; // Look up the value that has 2 as its key. WriteLine(format: "Key {0} has value: {1}", arg0: key, arg1: lookupObject[key]); 1. Add statements to use the harry object to look up its value, as shown in the following code: // Look up the value that has harry as its key. WriteLine(format: "Key {0} has value: {1}", arg0: harry, arg1: lookupObject[harry]); 1. Run the PeopleApp project and note that it works, as shown in the following output: Key 2 has value: Beta Key Packt.Shared.Person has value: Delta Although the code works, there is potential for mistakes because literally any type can be used for the key or value. If another developer used your lookup object and expected all the items to be a certain type, they might cast them to that type and get exceptions because some values might be a different type. A lookup object with lots of items would also give poor performance. Good Practice: Avoid types in the System.Collections namespace. Use types in the System.Collections.Generics and related namespaces instead. If you need to use a library that uses non-generic types, then of course you will have to use non-generic types. This is an example of what is commonly referred to as technical debt. Working with generic types‌ System.Collections.Generic.Dictionary can be used to store multiple values, each with a unique key that can later be used to quickly look up its value. Both the key and value can be any object, but you must tell the compiler what the types of the key and value will be when you first instantiate the collection. You do this by specifying types for the generic parameters in angle brackets <> , TKey , and TValue .

Good Practice: When a generic type has one definable type, it should be named T , for example, List , where T is the type stored in the list. When a generic type has multiple definable types, it should use T as a name prefix and have a sensible name, for example, Dictionary .

This provides flexibility, is faster, and bugs are easier to avoid because type checks are made when adding items at compile time. We will not need to explicitly specify the System.Collections.Generic namespace that contains Dictionary because it is implicitly and globally imported by default.Let's write some code to solve the problem by using generics:

1. In Program.cs , create an instance of the generic lookup collection

Dictionary and then add four items to it, as shown in the following code:

// Define a generic lookup collection. Dictionary lookupIntString = new(); lookupIntString.Add(key: 1, value: "Alpha"); lookupIntString.Add(key: 2, value: "Beta"); lookupIntString.Add(key: 3, value: "Gamma"); lookupIntString.Add(key: harry, value: "Delta");

1. Note the compile error when using harry as a key, as shown in the following output:

/Users/markjprice/Code/Chapter06/PeopleApp/Program.cs(98,32): error CS1503: Argument 1: cannot c

Replace harry with 4 .

Add statements to set the key to 3 , and use it to look up its value in the dictionary, as shown in the following code:

key = 3;

WriteLine(format: "Key {0} has value: {1}", arg0: key,

arg1: lookupIntString[key]);

1. Run the PeopleApp project and note that it works, as shown in the following output:

Key 3 has value: Gamma

You have now seen the difference between non-generic and generic types that need the flexibility to store any type. You know to always use generic collection types if possible. Unless you are unlucky enough to be forced to use a legacy non-generic library, you never need to write code that uses non-generic types that can store any type again.Just because it is good practice to use generic collection types in preference to non-generic collection

types does not mean the more general case is also true. Non-generic non-collection types and other types that do not need the flexibility to work with any type are used all the time.

Collection types just happen to be the most common type that benefits from generics.

Raising and handling events‌

Methods are often described as actions that an object can perform, either on itself or on related objects. For example, List can add an item to itself or clear itself, and File can create or delete a file in the filesystem.Events are often described as actions that happen to an object. For example, in a user interface, Button has a Click event, a click being something that happens to a button, and FileSystemWatcher listens to the filesystem for change notifications and raises events like Created and Deleted , which are triggered when a directory or file changes.Another way to think of events is that they provide a way of exchanging messages between two objects.Events are built on delegates, so let's start by having a look at what delegates are and how they work.

Calling methods using delegates‌

You have already seen the most common way to call or execute a method: using the . operator to access the method using its name. For example, Console.WriteLine tells the Console type to call its WriteLine method.The other way to call or execute a method is to use a delegate. If you have used languages that support function pointers, then think of a delegate as being a type-safe method pointer.In other words, a delegate contains the memory address of a method that must match the same signature as the delegate, enabling it to be called safely with the correct parameter types.

The code in this section is illustrative and not meant to be typed into a project. You will explore code like this in the next section, so for now just read the code and try to understand its meaning.

For example, imagine there is a method in the Person class that must have a string type passed as its only parameter, and it returns an int type, as shown in the following code:

public class Person

{

public int MethodIWantToCall(string input)

{

return input.Length; // It doesn't matter what the method does.

}

I can call this method on an instance of Person named p1 like this:

Person p1 = new();

int answer = p1.MethodIWantToCall("Frog");

Alternatively, I can define a delegate with a matching signature to call the method indirectly. Note that the names of the parameters do not have to match. Only the types of parameters and return values must match, as shown in the following code:

delegate int DelegateWithMatchingSignature(string s);

Good Practice: A delegate is a reference type like a class , so if you define one in Program.cs then it must be at the bottom of the file. It would be best to define it in its own class file, for example, Program.Delegates.cs . If you define a delegate in the middle of Program.cs , then you would see the following compiler error:

CS8803: Top-level statements must precede namespace and type declarations .

Now, I can create an instance of the delegate, point it at the method, and finally, call the delegate (which calls the method), as shown in the following code:

// Create a delegate instance that points to the method. DelegateWithMatchingSignature d = new(p1.MethodIWantToCall);

// Call the delegate, which then calls the method. int answer2 = d("Frog");

Examples of delegate use‌

You are probably thinking, "What's the point of that?" It provides flexibility. For example, we could use delegates to create a queue of methods that need to be called in order. Queuing actions that need to be performed is common in services to provide improved scalability.Another example is to allow multiple actions to execute in parallel. Delegates have built-in support for asynchronous operations that run on a different thread, which can provide improved responsiveness. The most important example is that delegates allow us to implement events to send messages between different objects that do not need to know about each other. Events are an example of loose coupling between components because they do not need to know about each other; they just need to know the event signature.

Status: It's complicated‌

Delegates and events are two of the most confusing features of C# and can take a few attempts to understand, so don't worry if you feel lost as we walk through how they work! Move on to other topics and come back again another day when your brain has had the opportunity to process the concepts while you sleep.

Defining and handling delegates‌

Microsoft has two predefined delegates for use as events. They both have two parameters:

image

object? sender : This parameter is a reference to the object raising the event or sending the message. The ? indicates that this reference could be null .

image

EventArgs e or TEventArgs e : This parameter contains additional relevant information about the event. For example, in a GUI app, you might define MouseMoveEventArgs , which has properties for the X and Y coordinates for the mouse pointer. A bank account might have a WithdrawEventArgs with a property for the Amount to withdraw.

Their signatures are simple, yet flexible, as shown in the following code:

// For methods that do not need additional argument values passed in. public delegate void EventHandler(object? sender, EventArgs e);

// For methods that need additional argument values passed in as

// defined by the generic type TEventArgs.

public delegate void EventHandler(object? sender, TEventArgs e);

Good Practice: When you want to define an event in your own type, you should use one of these two predefined delegates.

Let's explore delegates and events:

1. Add statements to the Person class and note the following points, as shown in the following code:

image

image

It defines an EventHandler delegate field named Shout . It defines an int field to store AngerLevel .

image

It defines a method named Poke .

image

Each time a person is poked, their AngerLevel increments. Once their AngerLevel reaches three, they raise the Shout event, but only if there is at least one event delegate pointing at a method defined somewhere else in the code; that is, it is not null :

#region Events

// Delegate field to define the event.

public EventHandler? Shout; // null initially.

// Data field related to the event. public int AngerLevel;

// Method to trigger the event in certain conditions. public void Poke()

{

AngerLevel++;

if (AngerLevel < 3) return; // If something is listening to the event... if (Shout is not null) { // ...then call the delegate to "raise" the event. Shout(this, EventArgs.Empty); } } #endregion Checking whether an object is not null before calling one of its methods is very common. C# 6 and later allows null checks to be simplified inline using a ? symbol before the . operator, as shown in the following code: Shout?.Invoke(this, EventArgs.Empty); In the PeopleApp project, add a new class file named Program.EventHandlers.cs . In Program.EventHandlers.cs , delete any existing statements, and then add a method with a matching signature that gets a reference to the Person object from the sender parameter and outputs some information about them, as shown in the following code: using Packt.Shared; // To use Person. // No namespace declaration so this extends the Program class // in the null namespace. partial class Program { // A method to handle the Shout event received by the harry object. private static void Harry_Shout(object? sender, EventArgs e) { // If no sender, then do nothing. if (sender is null) return; // If sender is not a Person, then do nothing. if (sender is not Person p) return; WriteLine($"{p.Name} is this angry: {p.AngerLevel}."); } } Good Practice: Microsoft's convention for method names that handle events is ObjectName_EventName . In this project, sender will always be a Person instance, so the null checks are not necessary, and the event handler could be much simpler with just the WriteLine statement. However, it is important to know that these types of null checks make your code more robust in cases of event misuse. 1. In Program.cs , add a statement to assign the method to the delegate field, and then add statements to call the Poke method four times, as shown in the following code: // Assign the method to the Shout delegate. harry.Shout = Harry_Shout; // Call the Poke method that eventually raises the Shout event. harry.Poke(); harry.Poke(); harry.Poke(); harry.Poke(); 1. Run the PeopleApp project and view the result, and note that Harry says nothing the first two times he is poked, and only gets angry enough to shout once he's been poked at least three times, as shown in the following output: Harry is this angry: 3. Harry is this angry: 4. Defining and handling events‌ You've now seen how delegates implement the most important functionality of events: the ability to define a signature for a method that can be implemented by a completely different piece of code, calling that method and any others that are hooked up to the delegate field.But what about events? There is less to them than you might think.When assigning a method to a delegate field, you should not use the simple assignment operator as we did in the preceding example.Delegates are multicast, meaning that you can assign multiple delegates to a single delegate field. Instead of the = assignment, we could have used the += operator so that we could add more methods to the same delegate field. When the delegate is called, all the assigned methods are called, although you have no control over the order in which they are called. Do not use events to implement a queuing system to buy concert tickets; otherwise, the wrath of millions of Swifties will fall upon you.If the Shout delegate field already referenced one or more methods, by assigning another method, that method would replace all the others. With delegates that are used for events, we usually want to make sure that a programmer only ever uses either the += operator or the -= operator to assign and remove methods: 1. To enforce this, in Person.cs , add the event keyword to the delegate field declaration, as highlighted in the following code: public event EventHandler? Shout; 1. Build the PeopleApp project and note the compiler error message, as shown in the following output: Program.cs(41,13): error CS0079: The event 'Person.Shout' can only appear on the left hand side This is (almost) all that the event keyword does! If you will never have more than one method assigned to a delegate field, then technically you do not need "events," but it is still good practice to indicate your meaning and that you expect a delegate field to be used as an event. 1. In Program.cs , modify the comment and the method assignment to use += instead of just = , as highlighted in the following code: // Assign the method to the Shout event delegate. harry.Shout += Harry_Shout; Run the PeopleApp project and note that it has the same behavior as before. In Program.EventHandlers.cs , create a second event handler for Harry's Shout event, as shown in the following code: // Another method to handle the event received by the harry object. private static void Harry_Shout_2(object? sender, EventArgs e) { WriteLine("Stop it!"); } 1. In Program.cs , after the statement that assigns the Harry_Shout method to the Shout event, add a statement to attach the new event handler to the Shout event too, as shown highlighted in the following code: // Assign the method(s) to the Shout event delegate. harry.Shout += Harry_Shout; harry.Shout += Harry_Shout_2; 1. Run the PeopleApp project, view the result, and note that both event handlers execute whenever an event is raised, which only happens once the anger level is three or more, as shown in the following output: Harry is this angry: 3. Stop it! Harry is this angry: 4. Stop it! That's it for events. Now let's look at interfaces. Implementing interfaces‌ Interfaces are a way to implement standard functionality and connect different types to make new things. Think of them like the studs on top of LEGO™ bricks, which allow them to "stick" together, or electrical standards for plugs and sockets.If a type implements an interface, then it makes a promise to the rest of .NET that it supports specific functionality. Therefore, they are sometimes described as contracts. Common interfaces‌ Table 6.1 shows some common interfaces that your types might implement: Interface Method(s) Description IComparable CompareTo(other) This defines a comparison method that a type implements to order or sort its instances. IComparer Compare(first, second) This defines a comparison method that a secondary type implements to order or sort instances of a primary type. IDisposable Dispose() This defines a disposal method to release unmanaged resources more efficiently than waiting for a finalizer. See the Releasing unmanaged resources section later in this chapter for more details. IFormattable ToString(format, culture) This defines a culture-aware method to format the value of an object into a string representation. IFormatter Serialize(stream, object) Deserialize(stream) This defines methods to convert an object to and from a stream of bytes for storage or transfer. IFormatProvider GetFormat(type) This defines a method to format inputs based on a language and region. Table 6.1: Some common interfaces that your types might implement Comparing objects when sorting‌ One of the most common interfaces that you will want to implement in your types that represent data is IComparable . If a type implements one of the IComparable interfaces, then arrays and collections containing instances of that type can be sorted.This is an example of an abstraction for the concept of sorting. To sort any type, the minimum functionality would be the ability to compare two items and decide which goes before the other. If a type implements that minimum functionality, then a sorting algorithm can use it to sort instances of that type in any way the sorting algorithm wants to.The IComparable interface has one method named CompareTo . This has two variations, one that works with a nullable object type and one that works with a nullable generic type T , as shown in the following code: namespace System { public interface IComparable { int CompareTo(object? obj); } public interface IComparable

{

int CompareTo(T? other);

}

}

The in keyword specifies that the type parameter T is contravariant, which means that you can use a less derived type than that specified. For example, if Employee derives from Person , then both can be compared with each other.

For example, the string type implements IComparable by returning -1 if the string should be sorted before the string being compared to, 1 if it should be sorted after, and 0 if they are equal. The int type implements IComparable by returning -1 if the int is less than the int being compared to, 1 if it is greater, and 0 if they are equal. CompareTo return values can be summarized as shown in Table 6.2:

this before other this is equal to other this after other

-1 0 1

Table 6.2: Summary of the CompareTo return values

Before we implement the IComparable interface and its CompareTo method for the Person class, let's see what happens when we try to sort an array of Person instances without implementing this interface, including some that are null or have a null value for their Name property:

In the PeopleApp project, add a new class file named Program.Helpers.cs .

In Program.Helpers.cs , delete any existing statements, and then define a method for the partial Program class that will output all the names of a collection of people passed as a parameter, with a title beforehand, as shown in the following code:

using Packt.Shared; partial class Program

{

private static void OutputPeopleNames( IEnumerable people, string title)

{

WriteLine(title);

foreach (Person? p in people)

{

WriteLine(" {0}",

p is null ? " Person" : p.Name ?? " Name");

/* if p is null then output: Person else output: p.Name

unless p.Name is null then output: Name */

}

}

}

1. In Program.cs , add statements that create an array of Person instances, call the OutputPeopleNames method to write the items to the console, and then attempt to sort the array and write the items to the console again, as shown in the following code:

Person?[] people =

{

null,

new() { Name = "Simon" },

new() { Name = "Jenny" },

new() { Name = "Adam" }, new() { Name = null }, new() { Name = "Richard" }

};

OutputPeopleNames(people, "Initial list of people:"); Array.Sort(people);

OutputPeopleNames(people,

"After sorting using Person's IComparable implementation:");

1. Run the PeopleApp project and an exception will be thrown. As the message explains, to fix the problem, our type must implement IComparable , as shown in the following output:

Unhandled Exception: System.InvalidOperationException: Failed to compare two elements in the arr

1. In Person.cs , after inheriting from object , add a comma and enter IComparable , as highlighted in the following code:

public class Person : IComparable

Your code editor will draw a red squiggle under the new code to warn you that you have not yet implemented the method you promised to. Your code editor can write the skeleton implementation for you.

Click on the light bulb and then click Implement interface.

Scroll down to the bottom of the Person class to find the method that was written for you, as shown in the following code:

public int CompareTo(Person? other)

{

throw new NotImplementedException();

}

Delete the statement that throws the NotImplementedException error.

Add statements to handle variations of input values, including null , and call the CompareTo method of the Name field, which uses the string type's implementation of CompareTo , and return the result, as shown in the following code:

int position;

if (other is not null)

{

if ((Name is not null) && (other.Name is not null))

{

// If both Name values are not null, then

// use the string implementation of CompareTo. position = Name.CompareTo(other.Name);

}

else if ((Name is not null) && (other.Name is null))

{

position = -1; // this Person precedes other Person.

}

else if ((Name is null) && (other.Name is not null))

{

position = 1; // this Person follows other Person.

}

else

{

position = 0; // this and other are at same position.

}

}

else if (other is null)

{

position = -1; // this Person precedes other Person.

}

else

{

position = 0; // this and other are at same position.

}

return position;

We have chosen to compare two Person instances by comparing their Name fields. Person instances will, therefore, be sorted alphabetically by their name. null values will be sorted to the bottom of the collection. Storing the calculated position before returning it is useful when debugging. I've also used more round brackets than the compiler needs to make the code easier for me to read. If you prefer fewer brackets, then feel free to remove them.

1. Run the PeopleApp project, and note that this time it works as it should, sorted alphabetically by name, as shown in the following output:

Initial list of people:

Simon

Person Jenny

Adam

Name Richard

After sorting using Person's IComparable implementation: Adam

Jenny Richard Simon

Name

Person

Good Practice: If you want to sort an array or collection of instances of your type, then implement the IComparable interface.

Comparing objects using a separate class‌

Sometimes, you won't have access to the source code for a type, and it might not implement the IComparable interface. Luckily, there is another way to sort instances of a type. You can create a separate type that implements a slightly different interface, named IComparer :

1. In the PacktLibrary project, add a new class file named PersonComparer.cs , containing a class implementing the IComparer interface that will compare two people, that is, two Person instances. Implement it by comparing the length of their Name fields, or if the names are the same length, then compare the names alphabetically, as shown in the following code:

namespace Packt.Shared;

public class PersonComparer : IComparer

{

public int Compare(Person? x, Person? y)

{

int position;

if ((x is not null) && (y is not null))

{

if ((x.Name is not null) && (y.Name is not null))

{

// If both Name values are not null...

// ...then compare the Name lengths...

int result = x.Name.Length.CompareTo(y.Name.Length);

// ...and if they are equal... if (result == 0)

{

// ...then compare by the Names... return x.Name.CompareTo(y.Name);

}

else

{

// ...otherwise compare by the lengths. position = result;

}

}

else if ((x.Name is not null) && (y.Name is null))

{

position = -1; // x Person precedes y Person.

}

else if ((x.Name is null) && (y.Name is not null))

{

position = 1; // x Person follows y Person.

}

else // x.Name and y.Name are both null.

{

position = 0; // x and y are at same position.

}

}

else if ((x is not null) && (y is null))

{

position = -1; // x Person precedes y Person.

}

else if ((x is null) && (y is not null))

{

position = 1; // x Person follows y Person.

}

else // x and y are both null.

{

position = 0; // x and y are at same position.

}

return position;

}

}

1. In Program.cs , add statements to sort the array using an alternative implementation, as shown in the following code:

Array.Sort(people, new PersonComparer()); OutputPeopleNames(people,

"After sorting using PersonComparer's IComparer implementation:");

1. Run the PeopleApp project, and view the result of sorting the people by the length of their names and then alphabetically, as shown in the following output:

After sorting using PersonComparer's IComparer implementation: Adam

Jenny Simon Richard

Name

Person

This time, when we sort the people array, we explicitly ask the sorting algorithm to use the PersonComparer type instead so that the people are sorted with the shortest names first, like Adam , and the longest names last, like Richard , and when the lengths of two or more names are equal they are sorted alphabetically, like Jenny and Simon .

Implicit and explicit interface implementations‌

Interfaces can be implemented implicitly and explicitly. Implicit implementations are simpler and more common. Explicit implementations are only necessary if a type must have multiple methods with the same name and signature. Personally, the only time I can remember ever having to explicitly implement an interface is when writing the code example for this book.For example, both IGamePlayer and IKeyHolder might have a method called Lose with the same parameters because both a game and a key can be lost. The members of an interface are always and automatically public because they have to be accessible for another type to implement them!In a type that must implement both interfaces, only one implementation of Lose can be the implicit method. If both interfaces can share the same implementation, there is no problem, but if not, then the other Lose method will have to be implemented differently and called explicitly, as shown in the following code:

public interface IGamePlayer

{

void Lose();

}

public interface IKeyHolder

{

void Lose();

}

public class Person : IGamePlayer, IKeyHolder

{

public void Lose() // Implicit implementation.

{

// Implement losing a key.

}

public void IGamePlayer.Lose() // Explicit implementation.

{

// Implement losing a game.

}

}

Person p = new();

p.Lose(); // Calls implicit implementation of losing a key. ((IGamePlayer)p).Lose(); // Calls explicit implementation of losing a game.

// Alternative way to do the same. IGamePlayer player = p as IGamePlayer;

player.Lose(); // Calls explicit implementation of losing a game.

Defining interfaces with default implementations‌

A language feature introduced in C# 8 is default implementations for an interface. This allows an interface to contain implementation. This breaks the clean separation between interfaces that define a contract and classes and other types that implement them. It is considered by some .NET developers to be a perversion of the language.Let's see it in action:

1. In the PacktLibrary project, add a new file named IPlayable.cs , and modify the statements to define a public IPlayable interface with two methods to Play and Pause , as shown in the following code:

namespace Packt.Shared; public interface IPlayable

{

void Play(); void Pause();

}

1. In the PacktLibrary project, add a new class file named DvdPlayer.cs , and modify the statements in the file to implement the IPlayable interface, as shown in the following code:

namespace Packt.Shared;

public class DvdPlayer : IPlayable

{

public void Pause()

{

WriteLine("DVD player is pausing.");

}

public void Play()

{

WriteLine("DVD player is playing.");

}

}

This is useful, but what if we decide to add a third method named Stop ? Before C# 8, this would be impossible once at least one type is implemented in the original interface. One of the main traits of an interface is that it is a fixed contract.C# 8 allows you to add new members to an interface after release if those new members have a default implementation. C# purists do not like the idea, but for practical reasons, such as avoiding breaking changes or having to define a whole new interface, it is useful, and other languages such as Java and Swift enable similar techniques.

Support for default interface implementations requires some fundamental changes to the underlying platform, so they are only supported with C# if the target framework is .NET

5 or later, .NET Core 3 or later, or .NET Standard 2.1. They are, therefore, not supported by .NET Framework.

Let's add a default implementation to the interface:

1. Modify the IPlayable interface to add a Stop method with a default implementation, as highlighted in the following code:

namespace Packt.Shared; public interface IPlayable

{

void Play(); void Pause();

void Stop() // Default interface implementation.

{

WriteLine("Default implementation of Stop.");

}

}

1. Build the PeopleApp project, and note that the projects compile successfully despite the DvdPlayer class not implementing Stop . In the future, we could override the default implementation of Stop by implementing it in the DvdPlayer class.

Although controversial, default implementations in interfaces might be useful in scenarios where the most common implementation is known at the time of defining the interface.

Therefore, it is best if the interface defines that implementation once, and then most types that implement that interface can inherit it without needing to implement their own.

However, if the interface definer does not know how the member should or even could be implemented, then it is a waste of effort to add a default implementation because it will

always be replaced.Think about the IComparable interface that you saw earlier in this chapter. It defines a CompareTo method. What might a default implementation of that method be? Personally, I think it's obvious that there is no default implementation that would make any practical sense. The least-worst implementation that I can think of would be to compare the string values returned from calling ToString on the two objects. However, every type really should implement its own CompareTo method. You are likely to find the same with 99.9% of the interfaces you use.Now let's look at how types are stored in a computer's memory.

Managing memory with reference and value types‌

I mentioned reference types a couple of times. Let's look at them in more detail.

Understanding stack and heap memory‌

There are two categories of memory: stack memory and heap memory. With modern operating systems, the stack and heap can be anywhere in physical or virtual memory.Stack memory is faster to work with but limited in size. It is fast because it is managed directly by the CPU and it uses a last-in, first-out mechanism, so it is more likely to have data in its L1 or L2 cache. Heap memory is slower but much more plentiful.On Windows, for ARM64, x86, and x64 machines, the default stack size is 1 MB. It is 8 MB on a typical modern Linux-based operating system. For example, in a macOS or Linux terminal, I can enter the command

ulimit -a to discover that the stack size is limited to 8,192 KB and that other memory is "unlimited." This limited amount of stack memory is why it is so easy to fill it up and get a "stack overflow."

Defining reference and value types‌

There are three C# keywords that you can use to define object types: class , record , and struct . All can have the same members, such as fields and methods. One difference between them is how memory is allocated:

image

When you define a type using record or class , you define a reference type. This means that the memory for the object itself is allocated on the heap, and only the memory address of the object (and a little overhead) is stored on the stack. Reference types always use a little stack memory.

image

When you define a type using record struct or struct , you define a value type. This means that the memory for the object itself is allocated to the stack.

If a struct uses field types that are not of the struct type, then those fields will be stored on the heap, meaning the data for that object is stored in both the stack and the heap.These are the most common struct types:

image

Number System types: byte , sbyte , short , ushort , int , uint , long , ulong , float ,

double , and decimal

image

Other System types: char , DateTime , DateOnly , TimeOnly , and bool

image

System.Drawing types: Color , Point , PointF , Size , SizeF , Rectangle , and RectangleF

Almost all the other types are class types, including string aka System.String and object

aka System.Object .

Apart from the difference in terms of where in memory the data for a type is stored, the other major differences are that you cannot inherit from a struct , and struct objects are compared for equality using values instead of memory addresses.

How reference and value types are stored in memory‌

Imagine that you have a console app that calls some method that uses some reference and value type variables, as shown in the following code:

void SomeMethod()

{

int number1 = 49; long number2 = 12;

System.Drawing.Point location = new(x: 4, y: 5); Person kevin = new() { Name = "Kevin",

Born = new(1988, 9, 23, 0, 0, 0, TimeSpace.Zero) }; Person sally;

}

Let's review what memory is allocated on the stack and heap when this method is executed, as shown in Figure 6.1 and as described in the following list:

image

The number1 variable is a value type (also known as struct ), so it is allocated on the stack, and it uses 4 bytes of memory since it is a 32-bit integer. Its value, 49 , is stored directly in the variable.

image

The number2 variable is also a value type, so it is also allocated on the stack, and it uses 8 bytes since it is a 64-bit integer.

image

The location variable is also a value type, so it is allocated on the stack, and it uses 8 bytes since it is made up of two 32-bit integers, x and y .

image

The kevin variable is a reference type (also known as class ), so 8 bytes for a 64-bit memory address (assuming a 64-bit operating system) are allocated on the stack, and enough bytes are allocated on the heap to store an instance of a Person .

image

The sally variable is a reference type, so 8 bytes for a 64-bit memory address are allocated on the stack. It is currently unassigned ( null ), meaning no memory has yet been allocated for it on the heap. If we were to later assign kevin to sally , then the memory address of the Person on the heap would be copied into sally , as shown in the following code:

sally = kevin; // Both variables point at the same Person on heap.

image

Figure 6.1: How value and reference types are allocated in the stack and heap

All the allocated memory for a reference type is stored on the heap except for its memory address on the stack. If a value type such as DateTimeOffset is used for a field of a reference type like Person , then the DateTimeOffset value is stored on the heap, as shown in Figure 6.1.If a value type has a field that is a reference type, then that part of the value type is stored on the heap. Point is a value type that consists of two fields, both of which are themselves value types, so the entire object can be allocated on the stack. If the Point value type had a field that was a reference type, like string , then the string bytes would be stored on the heap.When the method completes, all the stack memory is automatically released from the top of the stack. However, heap memory could still be allocated after a method returns. It is the .NET runtime garbage collector's responsibility to release this memory at a future date. Heap memory is not immediately released to improve performance. We will learn about the garbage collector later in this section.The console app might then call another method that needs some more stack memory to be allocated to it, and so on. Stack memory is literally a stack: memory is allocated at the top of the stack and removed from there when it is no longer needed.C# developers do not have control over the allocation or release of memory. Memory is automatically allocated when methods are called, and that memory is automatically released when the method returns. This is known as verifiably safe code.C# developers can allocate and access raw memory using unsafe code.

The stackalloc keyword is used to allocate a block of memory on the stack. Memory allocated is released automatically when the method that allocated it returns. This is an advanced feature not covered in this book. You can read about unsafe code and stackalloc at the following links: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/unsafe- code and https://learn.microsoft.com/en-us/dotnet/csharp/language- reference/operators/stackalloc.

Understanding boxing‌

Boxing is nothing to do with being punched in the face, although for Unity game developers struggling to manage limited memory it can sometimes feel like it.Boxing in C# is when a value type is moved to heap memory and wrapped inside a System.Object instance. Unboxing is when that value is moved back onto the stack. Unboxing happens explicitly. Boxing happens implicitly, so it can happen without the developer realizing. Boxing can take up to 20 times longer than without boxing.For example, an int value can be boxed and then unboxed, as shown in the following code:

int n = 3;

object o = n; // Boxing happens implicitly.

n = (int)o; // Unboxing only happens explicitly.

A common scenario is passing value types to formatted strings, as shown in the following code:

string name = "Hilda";

DateTime hired = new(2024, 2, 21); int days = 5;

// hired and days are value types that will be boxed. Console.WriteLine("{0} hired on {1} for {2} days.", name, hired, days);

The name variable is not boxed because string is a reference type and is therefore already on the heap.Boxing and unboxing operations have a negative impact on performance. Although it can be useful for a .NET developer to be aware of and to avoid boxing, for most .NET project types and for many scenarios, boxing is not worth worrying too much about because the overhead is dwarfed by other factors like making a network call or updating the user interface.But for games developed for the Unity platform, its garbage collector does not release boxed values as quickly or automatically and therefore it is more critical to avoid boxing as much as possible. For this reason, JetBrains Rider with its Unity Support plugin will complain about boxing operations whenever they occur in your code. Unfortunately, it does not differentiate between Unity and other project types.

More Information: You can learn more about boxing at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/types/boxing-and- unboxing.

Equality of types‌

It is common to compare two variables using the == and != operators. The behavior of these two operators is different for reference types and value types.When you check the equality of two value type variables, .NET literally compares the values of those two variables on the stack and returns true if they are equal.

1. In Program.cs , add statements to declare two integers with equal values and then compare them, as shown in the following code:

int a = 3; int b = 3;

WriteLine($"a: {a}, b: {b}"); WriteLine($"a == b: {a == b}");

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

a: 3, b: 3

a == b: True

When you check the equality of two reference type variables, .NET compares the memory addresses of those two variables and returns true if they are equal.

1. In Program.cs , add statements to declare two Person instances with equal names, and then compare the variables and their names, as shown in the following code:

Person p1 = new() { Name = "Kevin" }; Person p2 = new() { Name = "Kevin" }; WriteLine($"p1: {p1}, p2: {p2}");

WriteLine($"p1.Name: {p1.Name}, p2.Name: {p2.Name}"); WriteLine($"p1 == p2: {p1 == p2}");

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

p1: Packt.Shared.Person, p2: Packt.Shared.Person p1.Name: Kevin, p2.Name: Kevin

p1 == p2: False

This is because they are not the same object. If both variables literally pointed to the same object on the heap, then they would be equal.

1. Add statements to declare a third Person object and assign p1 to it, as shown in the following code:

Person p3 = p1;

WriteLine($"p3: {p3}");

WriteLine($"p3.Name: {p3.Name}"); WriteLine($"p1 == p3: {p1 == p3}");

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

p3: Packt.Shared.Person p3.Name: Kevin

p1 == p3: True

The one exception to this behavior of reference types is the string type. It is a reference type, but the equality operators have been overridden to make them behave as if they were value types.

1. Add statements to compare the Name properties of two Person instances, as shown in the following code:

// string is the only class reference type implemented to

// act like a value type for equality. WriteLine($"p1.Name: {p1.Name}, p2.Name: {p2.Name}"); WriteLine($"p1.Name == p2.Name: {p1.Name == p2.Name}");

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

p1.Name: Kevin, p2.Name: Kevin p1.Name == p2.Name: True

You can do the same as string with your classes to override the equality operator == to return true , even if the two variables are not referencing the same object (the same memory address on the heap) but, instead, their fields have the same values. However, that is beyond the scope of this book.

Good Practice: Alternatively, use a record class because one of its benefits is that it implements this equality behavior for you.

Defining struct types‌

Let's explore defining your own value types:

In the PacktLibrary project, add a file named DisplacementVector.cs .

image

Modify the file, as shown in the following code, and note the following: The type is declared using struct instead of class .

image

It has two int properties, named X and Y , that will auto-generate two private fields with the same data type, which will be allocated on the stack.

image

It has a constructor to set initial values for X and Y .

image

It has an operator to add two instances together that returns a new instance of the type, with X added to X , and Y added to Y :

namespace Packt.Shared;

public struct DisplacementVector

{

public int X { get; set; } public int Y { get; set; }

public DisplacementVector(int initialX, int initialY)

{

X = initialX;

Y = initialY;

}

public static DisplacementVector operator +( DisplacementVector vector1, DisplacementVector vector2)

{

return new(

vector1.X + vector2.X, vector1.Y + vector2.Y);

}

}

1. In Program.cs , add statements to create two new instances of DisplacementVector , add them together, and output the result, as shown in the following code:

DisplacementVector dv1 = new(3, 5); DisplacementVector dv2 = new(-2, 7); DisplacementVector dv3 = dv1 + dv2;

WriteLine($"({dv1.X}, {dv1.Y}) + ({dv2.X}, {dv2.Y}) = ({dv3.X}, {dv3.Y})");

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

(3, 5) + (-2, 7) = (1, 12)

Value types always have a default constructor even if an explicit one is not defined because the values on the stack must be initialized, even if they are initialized to default values. For the two integer fields in DisplacementVector , they will be initialized to 0 .

1. In Program.cs , add statements to create a new instance of DisplacementVector , and output the object's properties, as shown in the following code:

DisplacementVector dv4 = new(); WriteLine($"({dv4.X}, {dv4.Y})");

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

(0, 0)

1. In Program.cs , add statements to create a new instance of DisplacementVector , and compare it to dv1 , as shown in the following code:

DisplacementVector dv5 = new(3, 5); WriteLine($"dv1.Equals(dv5): {dv1.Equals(dv5)})"); WriteLine($"dv1 == dv5: {dv1 == dv5})");

1. Note that you cannot compare struct variables using == , but you can call the Equals method, which has a default implementation that compares all fields within the struct for equality. We could now make our struct overload the == operator ourselves, but an easier way is to use a feature introduced with C# 10: record struct types.

Good Practice: If the total memory used by all the fields in your type is 16 bytes or less, your type only uses value types for its fields, and you will never want to derive from your type, then Microsoft recommends that you use struct . If your type uses more than 16 bytes of stack memory, it uses reference types for its fields, or you might want to inherit from it, then use class .

Defining record struct types‌

C# 10 introduced the ability to use the record keyword with struct types as well as class

types. Let's see an example:

1. In the DisplacementVector type, add the record keyword, as highlighted in the following code:

public record struct DisplacementVector(int X, int Y);

In Program.cs , note that == now does not have a compiler error.

Run the PeopleApp project and view the result, as shown in the following output:

dv1.Equals(dv5): True) dv1 == dv5: True)

A record struct has all the same benefits over a record class that a struct has over a class . One difference between record struct and record class declared using primary constructor syntax is that record struct is not immutable, unless you also apply the readonly keyword to the record struct declaration. A struct does not implement the == and

!= operators, but they are automatically implemented with a record struct .

Good Practice: With this change, Microsoft recommends explicitly specifying class if you want to define a record class , even though the class keyword is optional, as shown in the following code: public record class ImmutableAnimal(string Name); .

Releasing unmanaged resources‌

In the previous chapter, we saw that constructors can be used to initialize fields and that a type may have multiple constructors. Imagine that a constructor allocates an unmanaged resource, that is, anything that is not controlled by .NET, such as a file or mutex under the control of the operating system. The unmanaged resource must be manually released because .NET cannot do it for us using its automatic garbage collection feature.Garbage collection is an advanced topic, so for this topic, I will show some code examples, but you do not need to write the code yourself.Each type can have a single finalizer that will be called by the .NET runtime when the resources need to be released. A finalizer has the same name as a constructor, that is, the name of the type, but it is prefixed with a tilde, ~ , as shown in the following code:

public class ObjectWithUnmanagedResources

{

public ObjectWithUnmanagedResources() // Constructor.

{

// Allocate any unmanaged resources.

}

~ObjectWithUnmanagedResources() // Finalizer aka destructor.

{

// Deallocate any unmanaged resources.

}

}

Do not confuse a finalizer (also known as a destructor) with a Deconstruct method. A destructor releases resources; in other words, it destroys an object in memory. A Deconstruct method returns an object split up into its constituent parts and uses the C# deconstruction syntax, for example, when working with tuples. See Chapter 5, Building Your Own Types with Object-Oriented Programming, for details of Deconstruct methods.The preceding code example is the minimum you should do when working with unmanaged resources. However, the problem with only providing a finalizer is that the .NET garbage collector requires two garbage collections to completely release the allocated resources for this type.Though optional, it is recommended to also provide a method to allow a developer who uses your type to explicitly release resources. This would allow the garbage collector to release managed parts of an unmanaged resource, such as a file, immediately and deterministically. This would mean it releases the managed memory part of the object in a single garbage collection instead of two rounds of garbage collection.There is a standard mechanism to do this by implementing the IDisposable interface, as shown in the following example:

public class ObjectWithUnmanagedResources : IDisposable

{

public ObjectWithUnmanagedResources()

{

// Allocate unmanaged resource.

}

~ObjectWithUnmanagedResources() // Finalizer.

{

Dispose(false);

}

bool disposed = false; // Indicates if resources have been released. public void Dispose()

{

Dispose(true);

// Tell garbage collector it does not need to call the finalizer. GC.SuppressFinalize(this);

}

protected virtual void Dispose(bool disposing)

{

if (disposed) return;

// Deallocate the *unmanaged* resource.

// ...

if (disposing)

{

// Deallocate any other *managed* resources.

// ...

}

disposed = true;

}

}

There are two Dispose methods, one public and one protected :

image

The public void Dispose method will be called by a developer using your type. When called, both unmanaged and managed resources need to be deallocated.

image

The protected virtual void Dispose method with a bool parameter is used internally to implement the deallocation of resources. It needs to check the disposing parameter and disposed field because if the finalizer thread has already run and called the

~ObjectWithUnmanagedResources method, then only managed resources need to be deallocated by the garbage collector.

The call to GC.SuppressFinalize(this) is what notifies the garbage collector that it no longer needs to run the finalizer, removing the need for a second garbage collection.

Ensuring that Dispose is called‌

When someone uses a type that implements IDisposable , they can ensure that the public

Dispose method is called with the using statement, as shown in the following code:

using (ObjectWithUnmanagedResources thing = new())

{

// Code that uses thing.

}

The compiler converts your code into something like the following, which guarantees that even if an exception occurs, the Dispose method will still be called:

ObjectWithUnmanagedResources thing = new(); try

{

// Code that uses thing.

}

finally

{

if (thing != null) thing.Dispose();

}

When someone uses a type that implements IAsyncDisposable , they can ensure that the public

Dispose method is called with the await using statement, as shown in the following code:

await using (ObjectWithUnmanagedResources thing = new())

{

// Code that uses async thing.

}

You will see practical examples of releasing unmanaged resources with IDisposable , using statements, and try ... finally blocks in Chapter 9, Working with Files, Streams, and Serialization.

Working with null values‌

You have seen how reference types are different from value types in how they are stored in memory, as well as how to store primitive values like numbers in struct variables. But what

if a variable does not yet have a value? How can we indicate that? C# has the concept of a

null value, which can be used to indicate that a variable has not been set.

Making a value type nullable‌

By default, value types like int and DateTime must always have a value, hence their name. Sometimes, for example, when reading values stored in a database that allows empty, missing, or null values, it is convenient to allow a value type to be null . We call this a nullable value type.You can enable this by adding a question mark as a suffix to the type when declaring a variable.Let's see an example. We will create a new project because some of the null handling options are set at the project level:

Use your preferred coding tool to add a new Console App / console project named

NullHandling to the Chapter06 solution.

In NullHandling.csproj , add an to globally and statically import the

System.Console class.

In Program.cs , delete the existing statements, and then add statements to declare and assign values, including null , to int variables, one suffixed with ? and one not, as shown in the following code:

int thisCannotBeNull = 4;

thisCannotBeNull = null; // CS0037 compiler error! WriteLine(thisCannotBeNull);

int? thisCouldBeNull = null; WriteLine(thisCouldBeNull); WriteLine(thisCouldBeNull.GetValueOrDefault()); thisCouldBeNull = 7; WriteLine(thisCouldBeNull); WriteLine(thisCouldBeNull.GetValueOrDefault());

1. Build the project and note the compile error, as shown in the following output:

Cannot convert null to 'int' because it is a non-nullable value type

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

//thisCannotBeNull = null; // CS0037 compiler error!

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

4

0

7

7

The second line is blank because it outputs the null value.

1. Add statements to use alternative syntax, as shown in the following code:

// The actual type of int? is Nullable. Nullable thisCouldAlsoBeNull = null; thisCouldAlsoBeNull = 9; WriteLine(thisCouldAlsoBeNull);

Click on Nullable and press F12, or right-click and choose Go To Definition.

Note that the generic value type, Nullable , must have a type T , which is a struct , aka a value type, and it has useful members like HasValue , Value , and GetValueOrDefault , as shown in Figure 6.2:

image

Figure 6.2: Revealing Nullable members

Good Practice: When you append a ? after a struct type, you change it to a different type. For example, DateTime? becomes Nullable .

Understanding null-related initialisms‌

Before we see some code, let's review some commonly used initialisms in Table 6.3: Initialism Meaning Description

NRT Nullable Reference Type

A compiler feature introduced with C# 8 and enabled by default in new projects with C# 10, which performs static analysis of your code at design time and shows warnings of potential misuse of null values for reference types.

NRE NullReferenceException An exception thrown at runtime when dereferencing a null

value, aka accessing a variable or member on an object that is null .

ANE ArgumentNullException An exception thrown at runtime by a method, property, or

indexer invocation when an argument or value is null , and when the business logic determines that it is not valid.

Table 6.3: Commonly used initialisms

Understanding nullable reference types‌

The use of the null value is so common, in so many languages, that many experienced programmers never question the need for its existence. However, there are many scenarios where we could write better, simpler code if a variable is not allowed to have a null value.The most significant change to the C# 8 language compiler was the introduction of checks and warnings for nullable and non-nullable reference types. "But wait!", you are probably thinking, "Reference types are already nullable!"And you would be right, but in C#

8 and later, reference types can be configured to warn you about null values by setting a file- or project-level option, enabling this useful new feature. Since this is a big change for C#, Microsoft decided to make the feature an opt-in.It will take several years for this new C# language compiler feature to make an impact, since thousands of existing library packages and apps will expect the old behavior. Even Microsoft did not have time to fully implement this new feature in all the main .NET packages until .NET 6. Important libraries

like Microsoft.Extensions for logging, dependency injections, and configuration were not annotated until .NET 7.During the transition, you can choose between several approaches for your own projects:

image

Default: For projects created using .NET 5 or earlier, no changes are needed. Non- nullable reference types are not checked. For projects created using .NET 6 or later, nullability checks are enabled by default, but this can be disabled by either deleting the entry in the project file or setting it to disable .

image

Opt-in project and opt-out files: Enable the feature at the project level, and for any files that need to remain compatible with old behavior, opt out. This was the approach Microsoft used internally while it updated its own packages to use this new feature.

image

Opt-in files: Only enable the NRT feature for individual files.

Warning! This NRT feature does not prevent null values – it just warns you about them, and the warnings can be disabled, so you still need to be careful!

string firstName; // Allows null but gives warning when potentially null. string? lastName; // Allows null and does not give warning if null.

Controlling the nullability warning check feature‌

To enable the nullability warning check feature at the project level, have the

element set to enable in your project file, as highlighted in the following markup:

...

enable

To disable the nullability warning check feature at the project level, have the

element set to disable in your project file, as highlighted in the following markup:

...

disable

You could also remove the element completely because the default, if not explicitly set, is disabled.To disable the feature at the file level, add the following to the top of a code file:

#nullable disable

To enable the feature at the file level, add the following to the top of a code file:

#nullable enable

Disabling null and other compiler warnings‌

You could decide to enable the nullability feature at the project or file level but then disable some of the 50+ warnings related to it. Some common nullability warnings are shown in Table 6.4:

Code Description

CS8600 Converting a null literal or a possible null value to a non-nullable type.

CS8601 A possible null reference assignment.

CS8602 A dereference of a possibly null reference.

CS8603 A possible null reference return.

CS8604 A possible null reference argument for a parameter.

CS8618 A non-nullable field '' must contain a non-null value when exiting a constructor. Consider declaring the field as nullable.

CS8625 Cannot convert a null literal to a non-nullable reference type.

CS8655 The switch expression does not handle some null inputs (it is not exhaustive). Table 6.4: Common nullability warnings

You can disable compiler warnings for a whole project. To do so, add a NoWarn element with a semicolon-separated list of compiler warning codes, as shown in the following markup:

CS8600;CS8602

To disable compiler warnings at the statement level, you can disable and then restore a specified compiler warning to temporarily suppress it for a block of statements, as shown in the following code:

#pragma warning disable CS8602 WriteLine(firstName.Length); WriteLine(lastName.Length); #pragma warning restore CS8602

These techniques can be used for any compiler warnings, not just those related to nullability.

Declaring non-nullable variables and parameters‌

If you enable NRTs and you want a reference type to be assigned the null value, then you will have to use the same syntax to make a value type nullable, that is, adding a ? symbol after the type declaration.So, how do NRTs work? Let's look at an example. When storing information about an address, you might want to force a value for the street, city, and region, but the building can be left blank, that is, null :

In the NullHandling project, add a class file named Address.cs .

in Address.cs , delete any existing statements and then add statements to declare an

Address class with four fields, as shown in the following code:

namespace Packt.Shared; public class Address

{

public string? Building; public string Street; public string City; public string Region;

}

After a few seconds, note the warnings about non-nullable fields, like Street not being initialized, as shown in Figure 6.3:

image

Figure 6.3: Warning messages about non-nullable fields in the Error List window

Assign the empty string value to the Street field, and define constructors to set the other fields that are non-nullable, as highlighted in the following code:

public string Street = string.Empty; public string City;

public string Region; public Address()

{

City = string.Empty;

Region = string.Empty;

}

// Call the default parameterless constructor

// to ensure that Region is also set. public Address(string city) : this()

{

City = city;

}

1. In Program.cs , import the namespace to use Address , as shown in the following code:

using Packt.Shared; // To use Address.

1. In Program.cs , add statements to instantiate an Address and set its properties, as shown in the following code:

Address address = new(city: "London")

{

Building = null, Street = null, Region = "UK"

};

1. Note the Warning CS8625 on setting the Street but not the Building , as shown in the following output:

CS8625 Cannot convert null literal to non-nullable reference type.

1. Append an exclamation mark after null when setting Street , as highlighted in the following code:

Street = null!, // null-forgiving operator.

Note that the warning disappears.

Add statements that will dereference the Building and Street properties, as shown in the following code:

WriteLine(address.Building.Length); WriteLine(address.Street.Length);

1. Note the Warning CS8602 on setting the Building but not the Street , as shown in the following output:

CS8602 Dereference of a possibly null reference.

At runtime it is still possible for an exception to be thrown when working with Street , but the compiler should continue to warn you of potential exceptions when working with Building so that you can change your code to avoid them.

1. Use the null-conditional operator to return null instead of accessing the Length , as shown in the following code:

WriteLine(address.Building?.Length);

1. Run the console app, and note that the statement that accesses the Length of the Building outputs a null value (blank line), but a runtime exception occurs when we access the Length of the Street , as shown in the following output:

Unhandled exception. System.NullReferenceException: Object reference not set to an instance of a

1. Wrap the statement that accesses the Street length in a null check, as shown in the following code:

if (address.Street is not null)

{

WriteLine(address.Street.Length);

}

It is worth reminding yourself that an NRT is only about asking the compiler to provide warnings about potential null values that might cause problems. It does not actually change the behavior of your code. It performs a static analysis of your code at compile time.This explains why the new language feature is named nullable reference types. Starting with C# 8.0, unadorned reference types can become non-nullable, and the same syntax is used to make a reference type nullable, as it is used for value types.

Suffixing a reference type with ? does not change the type. This is different from suffixing a value type with ? that changes its type to Nullable . Reference types can already have null values. All you do with nullable reference types (NRTs) is tell the compiler that you expect it to be null , so the compiler does not need to warn you.

However, this does not remove the need to perform null checks throughout your code.

Now let's look at language features to work with null values that change the behavior of your code and work well as a complement to NRTs.

Checking for null‌

Checking whether a nullable reference type or nullable value type variable currently contains null is important because if you do not, a NullReferenceException can be thrown, which results in an error. You should check for a null value before using a nullable variable, as shown in the following code:

// Check that the variable is not null before using it. if (thisCouldBeNull != null)

{

// Access a member of thisCouldBeNull. int length = thisCouldBeNull.Length;

...

}

C# 7 introduced is combined with the ! ( not ) operator as an alternative to != , as shown in the following code:

if (!(thisCouldBeNull is null))

{

C# 9 introduced is not as an even clearer alternative, as shown in the following code:

if (thisCouldBeNull is not null)

{

Good Practice: Although you traditionally would use the expression

(thisCouldBeNull != null) , this is no longer considered good practice because the developer could have overloaded the != operator to change how it works. Using pattern matching with is null and is not null are the only guaranteed ways to check for null . For many developers it is still instinctual to use != , so I apologize in advance if you catch me still using it!

If you try to use a member of a variable that might be null , use the null-conditional operator, ?. , as shown in the following code:

string authorName = null; int? authorNameLength;

// The following throws a NullReferenceException. authorNameLength = authorName.Length;

// Instead of throwing an exception, null is assigned. authorNameLength = authorName?.Length;

Sometimes, you want to either assign a variable to a result or use an alternative value, such as 3 , if the variable is null . You do this using the null-coalescing operator, ?? , as shown in the following code:

// Result will be 25 if authorName?.Length is null. authorNameLength = authorName?.Length ?? 25;

Checking for null in method parameters‌

Even if you enable NRTs, when defining methods with parameters, it is good practice to check for null values.In earlier versions of C#, you would have to write if statements to check for null parameter values and then throw an ArgumentNullException for any parameter that is null , as shown in the following code:

public void Hire(Person manager, Person employee)

{

if (manager is null)

{

throw new ArgumentNullException(paramName: nameof(manager));

}

if (employee is null)

{

throw new ArgumentNullException(paramName: nameof(employee));

}

...

}

C# 10 introduced a convenience method to throw an exception if an argument is null , as shown in the following code:

public void Hire(Person manager, Person employee)

{

ArgumentNullException.ThrowIfNull(manager); ArgumentNullException.ThrowIfNull(employee);

...

}

C# 11 previews proposed and introduced a new !! operator that does this for you, as shown in the following code:

public void Hire(Person manager!!, Person employee!!)

{

...

}

The if statement and throwing of the exception would be done for you. The code is injected and executed before any statements that you write.This proposal was controversial within the C# developer community. Some would prefer the use of attributes to decorate parameters instead of a pair of characters. The .NET product team said they reduced the .NET libraries by more than 10,000 lines of code by using this feature. That sounds like a good reason to use it to me! And no one must use it if they choose not to. Unfortunately, the team eventually decided to remove the feature, so now we all have to write the null checks manually. If you're interested in this story, then you can read more about it at the following link:https://devblogs.microsoft.com/dotnet/csharp-11-preview-updates/#remove- parameter-null-checking-from-c-11I include this story in this book because I think it's an interesting example of Microsoft being transparent, by developing .NET in the open and listening to and responding to feedback from the community.

Good Practice: Always remember that nullable is a warning check, not an enforcement. You can read more about the compiler warnings relating to null at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler- messages/nullable-warnings.

That's more than enough talk about "nothing"! Let's look at the meat of this chapter, inheritance.

Inheriting from classes‌

The Person type we created earlier derived (inherited) from System.Object . Now, we will create a subclass that inherits from Person :

In the PacktLibrary project, add a new class file named Employee.cs .

Modify its contents to define a class named Employee that derives from Person , as shown in the following code:

namespace Packt.Shared;

public class Employee : Person

{

}

1. In the PeopleApp project, in Program.cs , add statements to create an instance of the

Employee class, as shown in the following code:

Employee john = new()

{

Name = "John Jones",

Born = new(year: 1990, month: 7, day: 28,

hour: 0, minute: 0, second: 0, offset: TimeSpan.Zero))

};

john.WriteToConsole();

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

John Jones was born on a Saturday.

Note that the Employee class has inherited all the members of Person .

Extending classes to add functionality‌

Now, we will add some employee-specific members to extend the class:

1. In Employee.cs , add statements to define two properties, for an employee code and the date they were hired (we do not need to know a start time, so we can use the DateOnly type), as shown in the following code:

public string? EmployeeCode { get; set; } public DateOnly HireDate { get; set; }

1. In Program.cs , add statements to set John's employee code and hire date, as shown in the following code:

john.EmployeeCode = "JJ001";

john.HireDate = new(year: 2014, month: 11, day: 23); WriteLine($"{john.Name} was hired on {john.HireDate:yyyy-MM-dd}.");

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

John Jones was hired on 2014-11-23.

Hiding members‌

So far, the WriteToConsole method is inherited from Person , and it only outputs the employee's name and date and time of birth. We might want to change what this method does for an employee:

1. In Employee.cs , add statements to redefine the WriteToConsole method, as highlighted in the following code:

namespace Packt.Shared;

public class Employee : Person

{

public string? EmployeeCode { get; set; } public DateOnly HireDate { get; set; } public void WriteToConsole()

{

WriteLine(format:

"{0} was born on {1:dd/MM/yy} and hired on {2:dd/MM/yy}.", arg0: Name, arg1: Born, arg2: HireDate);

}

}

1. Run the PeopleApp project, view the result, and note that the first line of output is before the employees were hired; hence, it has a default date, as shown in the following output:

John Jones was born on 28/07/90 and hired on 01/01/01. John Jones was hired on 2014-11-23.

Your coding tool warns you that your method now hides the method from Person by drawing a squiggle under the method name, the PROBLEMS/Error List window includes more details, and the compiler will output a warning when you build and run the console application, as shown in Figure 6.4:

image

Figure 6.4: Hidden method warning

As the warning describes, you should hide this message by applying the new keyword to the method, indicating that you are deliberately replacing the old method, as highlighted in the following code:

public new void WriteToConsole()

Make this fix now.

Understanding this and base keywords‌

There are two special C# keywords that can be used to refer to the current object instance or the base class that it inherits from:

image

this : Represents the current object instance. For example, in the Person class instance members (but not in static members), you could use the expression this.Born to access the Born field of the current object instance. You rarely need to use it, since the expression Born would also work. It is only when there is a local variable also named Born that you would need to use this.Born , to explicitly say you are referring to the field, not the local variable.

image

base : Represents the base class that the current object inherits from. For example, anywhere in the Person class, you could use the expression base.ToString() to call the base class implementation of that method.

You will (hopefully) remember from Chapter 5, Building Your Own Types with Object- Oriented Programming, that to access static members you must use the type name.

Overriding members‌

Rather than hiding a method, it is usually better to override it. You can only override it if the base class chooses to allow overriding, by applying the virtual keyword to any methods that should allow overriding.Let's see an example:

1. In Program.cs , add a statement to write the value of the john variable to the console using its string representation, as shown in the following code:

WriteLine(john.ToString());

1. Run the PeopleApp project and note that the ToString method is inherited from System.Object , so the implementation returns the namespace and type name, as shown in the following output:

Packt.Shared.Employee

1. In Person.cs (not in the Employee class!), override this behavior by adding a ToString method to output the name of the person as well as the type name, as shown in the following code:

#region Overridden methods

public override string ToString()

{

return $"{Name} is a {base.ToString()}.";

}

#endregion

The base keyword allows a subclass to access members of its superclass, that is, the

base class that it inherits or derives from.

1. Run the PeopleApp project and view the result. Now, when the ToString method is called, it outputs the person's name, as well as returning the base class's implementation of ToString , as shown in the following output:

John Jones is a Packt.Shared.Employee.

Good Practice: Many real-world APIs, for example, Microsoft's Entity Framework Core, Castle's DynamicProxy, and Optimizely CMS's content models, require the properties that you define in your classes to be marked as virtual so that they can be overridden.

Carefully decide which of your method and property members should be marked as virtual .

Inheriting from abstract classes‌

Earlier in this chapter, you learned about interfaces that can define a set of members that a type must have to meet a basic level of functionality. These are very useful, but their main limitation is that until C# 8 they could not provide any implementation of their own.This is a particular problem if you still need to create class libraries that will work with .NET Framework and other platforms that do not support .NET Standard 2.1.In those earlier platforms, you could use an abstract class as a sort of halfway house between a pure interface and a fully implemented class.When a class is marked as abstract , this means that it cannot be instantiated because you have indicated that the class is not complete. It needs more implementation before it can be instantiated. For example, the System.IO.Stream class is abstract because it implements common functionality that all streams would need but is not complete, and therefore, it is useless without more implementation that is specific to the type of stream, so you cannot instantiate it using new Stream() .Let's compare the two types of interface and the two types of class, as shown in the following code:

public interface INoImplementation // C# 1 and later.

{

void Alpha(); // Must be implemented by derived type.

}

public interface ISomeImplementation // C# 8 and later.

{

void Alpha(); // Must be implemented by derived type. void Beta()

{

// Default implementation; can be overridden.

}

}

public abstract class PartiallyImplemented // C# 1 and later.

{

public abstract void Gamma(); // Must be implemented by derived type. public virtual void Delta() // Can be overridden.

{

// Implementation.

}

}

public class FullyImplemented : PartiallyImplemented, ISomeImplementation

{

public void Alpha()

{

// Implementation.

}

public override void Gamma()

{

// Implementation.

}

}

// You can only instantiate the fully implemented class. FullyImplemented a = new();

// All the other types give compile errors. PartiallyImplemented b = new(); // Compile error! ISomeImplementation c = new(); // Compile error! INoImplementation d = new(); // Compile error!

Choosing between an interface and an abstract class‌

You have now seen examples of implementing the concept of abstraction using either an interface or an abstract class. Which should you pick? Now that an interface can have default implementations for its members, is the abstract keyword for a class obsolete?Well, let’s think about a real example. Stream is an abstract class. Would or could the .NET team use an interface for that today? Every member of an interface must be public (or at least match the interface's access level which could be internal if it should only be used in the class library that it's defined in). An abstract class has more flexibility in its members' access modifiers.Another advantage of an abstract class over an interface is that serialization often does not work for an interface. So, no, we still need to be able to define abstract classes.

Preventing inheritance and overriding‌

You can prevent another developer from inheriting from your class by applying the sealed keyword to its definition. For example, no one can inherit from Scrooge McDuck, as shown in the following code:

public sealed class ScroogeMcDuck

{

}

An example of sealed in .NET is the string class. Microsoft has implemented some extreme optimizations inside the string class that could be negatively affected by your inheritance, so Microsoft prevents that.You can prevent someone from further overriding a virtual method in your class by applying the sealed keyword to the method. For example, no one can change the way Lady Gaga sings, as shown in the following code:

namespace Packt.Shared; public class Singer

{

// Virtual allows this method to be overridden. public virtual void Sing()

{

WriteLine("Singing...");

}

}

public class LadyGaga : Singer

{

// The sealed keyword prevents overriding the method in subclasses. public sealed override void Sing()

{

WriteLine("Singing with style...");

}

}

You can only seal an overridden method.

Understanding polymorphism‌

You have now seen two ways to change the behavior of an inherited method. We can hide it using the new keyword (known as non-polymorphic inheritance), or we can override it (known as polymorphic inheritance).Both ways can access members of the base or superclass by using the base keyword, so what is the difference?It all depends on the type of variable holding a reference to the object. For example, a variable of the Person type can hold a reference to a Person class, or any type that derives from Person .Let's see how this could affect your code:

1. In Employee.cs , add statements to override the ToString method so that it writes the employee's name and code to the console, as shown in the following code:

public override string ToString()

{

return $"{Name}'s code is {EmployeeCode}.";

}

1. In Program.cs , write statements to create a new employee named Alice stored in a variable of type Employee , also store Alice in a second variable of type Person , and then call both variables' WriteToConsole and ToString methods, as shown in the following code:

Employee aliceInEmployee = new()

{ Name = "Alice", EmployeeCode = "AA123" }; Person aliceInPerson = aliceInEmployee; aliceInEmployee.WriteToConsole(); aliceInPerson.WriteToConsole(); WriteLine(aliceInEmployee.ToString()); WriteLine(aliceInPerson.ToString());

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

Alice was born on 01/01/01 and hired on 01/01/01 Alice was born on a Monday

Alice's code is AA123 Alice's code is AA123

When a method is hidden with new , the compiler is not smart enough to know that the object is an Employee , so it calls the WriteToConsole method in Person .When a method is overridden with virtual and override , the compiler is smart enough to know that although the variable is declared as a Person class, the object itself is an Employee class, and therefore, the Employee implementation of ToString is called.The member modifiers and the effect they have are summarized in the following table:

Variable type Member modifier Method executed In class

Person WriteToConsole Person

Employee new WriteToConsole Employee

Person

virtual

ToString

Employee

Employee

override

ToString

Employee

In my opinion, polymorphism is academic to most programmers. If you get the concept, that's cool; but, if not, I suggest that you don't worry about it. Some people like to make others feel inferior by saying understanding polymorphism is important for all C# programmers, but in my opinion, it's not. There are thousands of other topics that your time and effort will be better spent on.You can have a successful career with C# and never need to be able to explain polymorphism, just as a racing car driver doesn't need to explain the engineering behind fuel injection.

Good Practice: You should use virtual and override rather than new to change the implementation of an inherited method whenever possible.

Casting within inheritance hierarchies‌

Casting between types is subtly different from converting between types. Casting is between similar types, like between a 16-bit integer and a 32-bit integer, or between a superclass and one of its subclasses. Converting is between dissimilar types, such as between text and a number.For example, if you need to work with multiple types of stream , then instead of declaring specific types of stream like MemoryStream or FileStream , you could declare an array of Stream , the supertype of MemoryStream and FileStream .

Implicit casting‌

In the previous example, you saw how an instance of a derived type can be stored in a variable of its base type (or its base's base type, and so on). When we do this, it is called implicit casting.

Explicit casting‌

The opposite of implicit casting is explicit casting, and you must use parentheses around the type you want to cast into as a prefix to do it:

1. In Program.cs , add a statement to assign the aliceInPerson variable to a new Employee

variable, as shown in the following code:

Employee explicitAlice = aliceInPerson;

Your coding tool displays a red squiggle and a compile error, as shown in Figure 6.5:

image

Figure 6.5: A missing explicit cast compile error

Change the statement to prefix the assigned variable name with a cast to the Employee

type, as shown highlighted in the following code:

Employee explicitAlice = (Employee)aliceInPerson;

Avoiding casting exceptions‌

The compiler is now happy; however, because aliceInPerson might be a different derived type, like Student instead of Employee , we need to be careful. In a real application with more complex code, the current value of this variable could have been set to a Student instance, and then this statement would throw an InvalidCastException error at runtime.

Using is to check a type‌

We can handle this by writing a try statement, but there is a better way. We can check the type of an object using the is keyword:

1. Wrap the explicit cast statement in an if statement, as highlighted in the following code:

if (aliceInPerson is Employee)

{

WriteLine($"{nameof(aliceInPerson)} is an Employee."); Employee explicitAlice = (Employee)aliceInPerson;

// Safely do something with explicitAlice.

}

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

aliceInPerson is an Employee.

You could simplify the code further using a declaration pattern, and this will avoid the need to perform an explicit cast, as shown in the following code:

if (aliceInPerson is Employee explicitAlice)

{

WriteLine($"{nameof(aliceInPerson)} is an Employee.");

// Safely do something with explicitAlice.

}

What if you want to execute a block of statements when Alice is not an employee?In the past, you would have had to use the ! (not) operator, as shown in the following code:

if (!(aliceInPerson is Employee))

With C# 9 and later, you can use the not keyword, as shown in the following code:

if (aliceInPerson is not Employee)

Using as to cast a type‌

Alternatively, you can use the as keyword to cast a type. Instead of throwing an exception, the as keyword returns null if the type cannot be cast:

1. In Program.cs , add statements to cast Alice using the as keyword, and then check whether the return value is not null, as shown in the following code:

Employee? aliceAsEmployee = aliceInPerson as Employee; if (aliceAsEmployee is not null)

{

WriteLine($"{nameof(aliceInPerson)} as an Employee.");

// Safely do something with aliceAsEmployee.

}

Since accessing a member of a null variable will throw a NullReferenceException error, you should always check for null before using the result.

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

aliceInPerson as an Employee.

Good Practice: Use the is and as keywords to avoid throwing exceptions when casting between derived types. If you don't do this, you must write try - catch statements for InvalidCastException .

Inheriting and extending .NET types‌

.NET has pre-built class libraries containing hundreds of thousands of types. Rather than creating your own completely new types, you can often get a head start by deriving from one of Microsoft's types to inherit some or all its behavior, and then overriding or extending it.

Inheriting exceptions‌

As an example of inheritance, we will derive a new type of exception:

In the PacktLibrary project, add a new class file named PersonException.cs .

Modify the contents of the file to define a class named PersonException with three constructors, as shown in the following code:

namespace Packt.Shared;

public class PersonException : Exception

{

public PersonException() : base() { }

public PersonException(string message) : base(message) { } public PersonException(string message, Exception innerException)

: base(message, innerException) { }

}

Unlike ordinary methods, constructors are not inherited, so we must explicitly declare and explicitly call the base constructor implementations in System.Exception (or whichever exception class you derived from) to make them available to programmers who might want to use those constructors with our custom exception.

1. In Person.cs , add statements to define a method that throws an exception if a date/time parameter is earlier than a person's date and time of birth, as shown in the following code:

public void TimeTravel(DateTime when)

{

if (when <= Born) { throw new PersonException("If you travel back in time to a date earlier than your own birth, } else { WriteLine($"Welcome to {when:yyyy}!"); } } 1. In Program.cs , add statements to test what happens when employee John Jones tries to time-travel too far back, as shown in the following code: try { john.TimeTravel(when: new(1999, 12, 31)); john.TimeTravel(when: new(1950, 12, 25)); } catch (PersonException ex) { WriteLine(ex.Message); } 1. Run the PeopleApp project and view the result, as shown in the following output: Welcome to 1999! If you travel back in time to a date earlier than your own birth, then the universe will explode Good Practice: When defining your own exceptions, give them the same three constructors that explicitly call the built-in ones in System.Exception . Other exceptions that you might inherit from may have more. Extending types when you can't inherit‌ Earlier, we saw how the sealed modifier can be used to prevent inheritance.Microsoft has applied the sealed keyword to the System.String class so that no one can inherit and potentially break the behavior of strings.Can we still add new methods to strings? Yes, if we use a language feature named extension methods, which was introduced with C# 3.0. To properly understand extension methods, we need to review static methods first. Using static methods to reuse functionality‌ Since the first version of C#, we've been able to create static methods to reuse functionality, such as the ability to validate that a string contains an email address. The implementation will use a regular expression that you will learn more about in Chapter 8, Working with Common .NET Types.Let's write some code: In the PacktLibrary project, add a new class file named StringExtensions.cs . Modify StringExtensions.cs , as shown in the following code, and note the following: image The class imports a namespace to handle regular expressions. image The IsValidEmail method is static , and it uses the Regex type to check for matches against a simple email pattern that looks for valid characters before and after the @ symbol: using System.Text.RegularExpressions; // To use Regex. namespace Packt.Shared; public class StringExtensions { public static bool IsValidEmail(string input) { // Use a simple regular expression to check // that the input string is a valid email. return Regex.IsMatch(input, @"[a-zA-Z0-9\.-_]+@[a-zA-Z0-9\.-_]+"); } } 1. In Program.cs , add statements to validate two examples of email addresses, as shown in the following code: string email1 = "pamela@test.com"; string email2 = "ian&test.com"; WriteLine("{0} is a valid e-mail address: {1}", arg0: email1, arg1: StringExtensions.IsValidEmail(email1)); WriteLine("{0} is a valid e-mail address: {1}", arg0: email2, arg1: StringExtensions.IsValidEmail(email2)); 1. Run the PeopleApp project and view the result, as shown in the following output: pamela@test.com is a valid e-mail address: True ian&test.com is a valid e-mail address: False This works, but extension methods can reduce the amount of code we must type and simplify the usage of this function. Using extension methods to reuse functionality‌ It is easy to turn static methods into extension methods: 1. In StringExtensions.cs , add the static modifier before the class, and then add the this modifier before the string type, as highlighted in the following code: public static class StringExtensions { public static bool IsValidEmail(this string input) { Good Practice: These two changes tell the compiler that it should treat the method as one that extends the string type. 1. In Program.cs , add statements to use the extension method for string values that need to be checked for valid email addresses, as shown in the following code: WriteLine("{0} is a valid e-mail address: {1}", arg0: email1, arg1: email1.IsValidEmail()); WriteLine("{0} is a valid e-mail address: {1}", arg0: email2, arg1: email2.IsValidEmail()); Note the subtle simplification in the syntax to call the IsValidEmail method. The older, longer syntax still works too. The IsValidEmail extension method now appears to be a method just like all the actual instance methods of the string type, such as IsNormalized , except with a small down arrow on the method icon to indicate an extension method, as shown in Figure 6.6: image Figure 6.6: Extension methods appear in IntelliSense alongside instance methods Run the PeopleApp project and view the result, which will be the same as before. Good Practice: Extension methods cannot replace or override existing instance methods. You cannot, for example, redefine the Insert method. The extension method will appear as an overload in IntelliSense, but an instance method will be called in preference to an extension method with the same name and signature. Although extension methods might not seem to give a big benefit, in Chapter 11, Querying and Manipulating Data Using LINQ, you will see some extremely powerful uses of extension methods. Summarizing custom type choices‌ Now that we have covered OOP and the C# features that enable you to define your own types, let's summarize what you've learned. Categories of custom type and their capabilities‌ class Yes Single Reference Heap sealed class Yes None Reference Heap abstract class No Single Reference Heap record or record class Yes Single Value Heap struct or record struct Yes None Value Stack interface No Multiple Reference Heap Categories of custom type and their capabilities are summarized in the following table: Type Instantiation Inheritance Equality Memory It is best to think about these differences by starting with the "normal" case and then spotting the differences in other cases. For example, a "normal" class can be instantiated with new , it supports single inheritance, it uses memory reference equality, and its state is stored in heap memory.Now let's highlight what is different about the more specialized types of classes: image A sealed class does not support inheritance. image An abstract class does not allow instantiation with new . image A record class uses value equality instead of reference equality. We can do the same for other types compared to a "normal" class: image A struct or record struct does not support inheritance, it uses value equality instead of reference equality, and its state is stored in stack memory. image An interface does not allow instantiation with new and supports multiple inheritance. Mutability and records‌ A common misconception is that record types are immutable, meaning its instance property and field values cannot be changed after initialization. However, the mutability of a record type actually depends on how the record is defined. Let's explore mutability: In the PacktLibrary project, add a new class file named Mutability.cs . Modify Mutability.cs , as shown in the following code, and note the following: namespace Packt.Shared; // A mutable record class. public record class C1 { public string? Name { get; set; } } // An immutable record class. public record class C2(string? Name); // A mutable record struct. public record struct S1 { public string? Name { get; set; } } // Another mutable record struct. public record struct S2(string? Name); // An immutable record struct. public readonly record struct S3(string? Name); 1. In the PeopleApp project, in Program.cs , create an instance of each type, setting the initial Name value to Bob , and then modify the Name property to Bill , you will see the two types that are immutable after initialization because they will give the compiler error CS8852 , as shown in the following code: C1 c1 = new() { Name = "Bob" }; c1.Name = "Bill"; C2 c2 = new(Name: "Bob"); c2.Name = "Bill"; // CS8852: Init-only property. S1 s1 = new() { Name = "Bob" }; s1.Name = "Bill"; S2 s2 = new(Name: "Bob"); s2.Name = "Bill"; S3 s3 = new(Name: "Bob"); s3.Name = "Bill"; // CS8852: Init-only property. Note that record C1 is mutable and C2 is immutable. Note that S1 and S2 are mutable and S3 is immutable. Comment out the two statements that cause compiler errors. Microsoft made some interesting design choices with records. Make sure you remember the subtle differences in behavior when combining record, class, struct and using different types of declaration of each. Comparing inheritance and implementation‌ For me, the terms inherit and implement are different, and in the early days of C# and .NET you could strictly apply them to classes and interfaces respectfully. For example, the FileStream class inherits from the Stream class, and the Int32 struct implements the IComparable interface.Inherit implies some functionality that a subclass gets "for free" by inheriting from its base aka super class. Implement implies some functionality that is NOT inherited but instead MUST be provided by the subclass. This is why I chose to title this chapter Implementing Interfaces and Inheriting Classes.Before C# 8, interfaces were always purely contracts. There was no functionality in an interface that you could inherit. In those days, you could strictly use the term implement for interfaces that represent a list of members that your type must implement, and use the term inherit for classes with functionality that your type can inherit and potentially override.With C# 8, interfaces can now include default implementations, making them more like abstract classes, and the term inherit for an interface that has default implementations does make sense. But I feel uncomfortable with this capability, as do many other .NET developers because it messes up what used to be a clean language design. Default interfaces also require changes to the underlying .NET runtime, so they cannot be used with legacy platforms like .NET Standard 2.0 class libraries and .NET Framework.Classes can also have abstract members, for example, methods or properties without any implementation, just like an interface could have. When a subclass inherits from this class, it MUST provide an implementation of those abstract members, and the base class must be decorated with the abstract keyword to prevent it from being instantiated using new because it is missing some functionality. Reviewing illustrative code‌ Let's review some example code that illustrates some of the important differences between types. Note the following: image image To simplify the code, I have left out access modifiers like private and public . Instead of normal brace formatting, to save vertical space I have put all the method implementation on one statement, for example: void M1() { /* implementation */ } image Using "I" as a prefix for interfaces is a convention, not a requirement. It is useful to highlight interfaces using this prefix, since only interfaces support multiple inheritance. Here's the code: // These are both "classic" interfaces in that they are pure contracts. // They have no functionality, just the signatures of members that // must be implemented. interface IAlpha { // A method that must be implemented in any type that implements // this interface. void M1(); } interface IBeta { void M2(); // Another method. } // A type (a struct in this case) implementing an interface. // ": IAlpha" means Gamma promises to implement all members of IAlpha. struct Gamma : IAlpha { void M1() { /* implementation */ } } // A type (a class in this case) implementing two interfaces. class Delta : IAlpha, IBeta { void M1() { /* implementation */ } void M2() { /* implementation */ } } // A sub class inheriting from a base aka super class. // ": Delta" means inherit all members from Delta. class Episilon : Delta { // This can be empty because this inherits M1 and M2 from Delta. // You could also add new members here. } // A class with one inheritable method and one abstract method // that must be implemented in sub classes. A class with at least // one abstract member must be decorated with the abstract keyword // to prevent instantiation. abstract class Zeta { // An implemented method would be inherited. void M3() { /* implementation */ } // A method that must be implemented in any type that inherits // this abstract class. abstract void M4(); } // A class inheriting the M3 method from Zeta but it must provide // an implementation for M4. class Eta : Zeta { void M4() { /* implementation */ } } // In C# 8 and later, interfaces can have default implementations // as well as members that must be implemented. // Requires: .NET Standard 2.1, .NET Core 3.0 or later. interface ITheta { void M3() { /* implementation */ } void M4(); } // A class inheriting the default implementation from an interface // and must provide an implementation for M4. class Iota : ITheta { void M4() { /* implementation */ } } Practicing and exploring‌ Test your knowledge and understanding by answering some questions, getting some hands-on practice, and exploring this chapter's topics with more in-depth research. Exercise 6.1 – Test your knowledge‌ Answer the following questions: What is a delegate? What is an event? How are a base class and a derived class related, and how can the derived class access the base class? What is the difference between is and as operators? Which keyword is used to prevent a class from being derived from or a method from being further overridden? Which keyword is used to prevent a class from being instantiated with the new keyword? Which keyword is used to allow a member to be overridden? What's the difference between a destructor and a deconstruct method? What are the signatures of the constructors that all exceptions should have? What is an extension method, and how do you define one? Exercise 6.2 – Practice creating an inheritance hierarchy‌ Explore inheritance hierarchies by following these steps: Add a new console app named Ch06Ex02Inheritance to your Chapter06 solution. Create a class named Shape with properties named Height , Width , and Area . Add three classes that derive from it - Rectangle , Square , and Circle —with any additional members you feel are appropriate and that override and implement the Area property correctly. In Program.cs , add statements to create one instance of each shape, as shown in the following code: Rectangle r = new(height: 3, width: 4.5); WriteLine($"Rectangle H: {r.Height}, W: {r.Width}, Area: {r.Area}"); Square s = new(5); WriteLine($"Square H: {s.Height}, W: {s.Width}, Area: {s.Area}"); Circle c = new(radius: 2.5); WriteLine($"Circle H: {c.Height}, W: {c.Width}, Area: {c.Area}"); 1. Run the console app and ensure that the result looks like the following output: Rectangle H: 3, W: 4.5, Area: 13.5 Square H: 5, W: 5, Area: 25 Circle H: 5, W: 5, Area: 19.6349540849362 Exercise 6.3 – Writing better code‌ Read the following online-only section to learn how to use analyzers to write better code: https://github.com/markjprice/cs12dotnet8/blob/main/docs/ch06-writing-better-code.md. Exercise 6.4 – Explore topics‌ Use the links on the following page to learn more about the topics covered in this chapter: https://github.com/markjprice/cs12dotnet8/blob/main/docs/book-links.md#chapter-6--- implementing-interfaces-and-inheriting-classes Summary‌ In this chapter, you learned about: image image Operators Generic types image image Delegates and events Implementing interfaces image image Memory usage differences between reference and value types Working with null values image Deriving and casting types using inheritance image Base and derived classes, how to override a type member, and using polymorphism In the next chapter, you will learn how .NET is packaged and deployed, and in subsequent chapters, the types that it provides you with to implement common functionality, such as file handling and database access. 7 Packaging and Distributing .NET Types‌‌‌ Join our book community on Discord https://packt.link/EarlyAccess image This chapter is about how C# keywords are related to .NET types, and about the relationship between namespaces and assemblies. You'll become familiar with how to package and publish your .NET apps and libraries for cross-platform use. We also cover how to decompile .NET assemblies for learning purposes and why you cannot prevent others from decompiling your code.In an online-only section, Exercise 7.3 – Porting from .NET Framework to modern .NET, you can learn how to use legacy .NET Framework libraries in .NET libraries and the possibility of porting legacy .NET Framework code bases to modern .NET. In another online- only section, Exercise 7.4 – Creating source generators, you will learn how to create source generators that can dynamically add source code to your projects, a very powerful feature.This chapter covers the following topics: image image The road to .NET 8 Understanding .NET components image image image Publishing your applications for deployment Native ahead-of-time compilation Decompiling .NET assemblies image image Packaging your libraries for NuGet distribution Working with preview features The road to .NET 8‌ This part of the book is about the functionality in the Base Class Library (BCL) APIs provided by .NET and how to reuse functionality across all the different .NET platforms using .NET Standard.From .NET Core 2.0 onward, the support for a minimum of .NET Standard 2.0 is important because it provides many of the APIs that were missing from the first version of .NET Core. The 15 years' worth of libraries and applications that .NET Framework developers had available to them that are relevant for modern development have now been migrated to .NET and can run cross-platform on macOS and Linux variants, as well as on Windows..NET Standard 2.1 added about 3,000 new APIs. Some of those APIs need runtime changes that would break backward compatibility, so .NET Framework 4.8 only implements .NET Standard 2.0; .NET Core 3.0, Xamarin, Mono, and Unity implement .NET Standard 2.1..NET 5 removed the need for .NET Standard because all project types can now target a single version of .NET. The same applies to .NET 6 and later. Each version from .NET 5 onward is backward compatible with previous versions. This means a class library that targets .NET 5 can be used by any .NET 5 or later projects of any type. Now that .NET versions have been released with full support for mobile and desktop apps built using .NET MAUI, the need for .NET Standard has been further reduced.Since you might still need to create class libraries for legacy .NET Framework projects or legacy Xamarin mobile apps, there is still a need to create .NET Standard 2.0 class libraries. And currently, you must also use a .NET Standard 2.0 class library to create a source generator.To summarize the progress that .NET has made since the first version of .NET Core in 2016, I have compared the major .NET Core and modern .NET versions with the equivalent .NET Framework versions in the following list: image .NET Core 1.x: Much smaller API compared to .NET Framework 4.6.1, which was the current version in March 2016. image .NET Core 2.x: Reached API parity with .NET Framework 4.7.1 for modern APIs because they both implement .NET Standard 2.0. image .NET Core 3.x: Larger API compared to .NET Framework for modern APIs because .NET Framework 4.8 does not implement .NET Standard 2.1. image .NET 5: Even larger API compared to .NET Framework 4.8 for modern APIs, with much- improved performance. image .NET 6: Continued improvements to performance and expanded APIs with optional support for mobile apps in .NET MAUI that was added in May 2022. image .NET 7: Final unification with the support for mobile apps with .NET MAUI available as an optional workload. This book does not cover .NET MAUI development. Packt has multiple books that specialize in .NET MAUI, and you can find them by searching their website. image .NET 8: Continues to improve the platform and should be used for all new development. .NET Core 1.0, June 2016‌ Implemented an API suitable for building modern cross-platform apps, including web and cloud applications and services for Linux using ASP.NET Core. .NET Core 1.1, November 2016‌ Fixed bugs, increased the number of Linux distributions supported, supported .NET Standard 1.6, and improved performance, especially with ASP.NET Core for web apps and services. .NET Core 2.0, August 2017‌ Implemented .NET Standard 2.0, the ability to reference .NET Framework libraries, and added more performance improvements. .NET Core 2.1, May 2018‌ Focused on an extendable tooling system, added new types like Span , new APIs for cryptography and compression, a Windows Compatibility Pack with an additional 20,000 APIs to help port old Windows applications, Entity Framework Core value conversions, LINQ GroupBy conversions, data seeding, query types, and even more performance improvements, including the topics listed in Table 7.1:

Feature Chapter Topic

Spans 8 Working with spans, indexes, and ranges Brotli compression 9 Compressing with the Brotli algorithm EF Core lazy loading 10 Enabling lazy loading

EF Core data seeding 10 Understanding data seeding Table 7.1: Features of .NET Core 2.1

.NET Core 2.2, December 2018‌

Focused on diagnostic improvements for the runtime, optional tiered compilation, and added new features to ASP.NET Core and Entity Framework Core like spatial data support using types from the NetTopologySuite (NTS) library, query tags, and collections of owned entities.

.NET Core 3.0, September 2019‌

Added support for building Windows desktop applications using Windows Forms (2001), Windows Presentation Foundation (WPF; 2006), and Entity Framework 6.3. Also introduced side-by-side and app-local deployments; a fast JSON reader; serial port access and other pinout access for Internet of Things (IoT) solutions; and tiered compilation by default, including the topics listed in Table 7.2:

Feature Chapter Topic

Embedding .NET in-app 7 Publishing your applications for deployment Index and Range 8 Working with spans, indexes, and ranges System.Text.Json 9 High-performance JSON processing

Table 7.2: Features of .NET Core 3.0

.NET Core 3.1, December 2019‌

Added bug fixes and refinements so that it could be a Long Term Support (LTS) release.

.NET 5, November 2020‌

Unified the various .NET platforms except mobile, refined the platform, and improved performance, including the topics listed in Table 7.3:

Feature Chapter Topic

Half type 8 Working with numbers

Regular expression performance improvements 8 Regular expression performance

improvements

System.Text.Json improvements 9 High-performance JSON processing

EF Core generated SQL 10 Getting the generated SQL

EF Core Filtered Include 10 Filtering included entities

EF Core Scaffold-DbContext now singularizes using Humanizer

Table 7.3: Features of .NET 5

.NET 6, November 2021‌

10 Scaffolding models using an existing database

Added more features to EF Core for data management, new types for working with dates and times, and improved performance yet again, including the topics listed in Table 7.4:

Feature Chapter Topic

Check .NET SDK status 7 Checking your .NET SDKs for updates

Link trim mode as default 7 Reducing the size of apps using app trimming

EnsureCapacity for List 8 Improving performance by ensuring the capacity of a collection

Low-level file API using

RandomAccess

Reading and writing with random access handles

EF Core configuration 10 Configuring preconvention models

conventions

New LINQ methods

11

Building LINQ expressions with the Enumerable class

TryGetNonEnumeratedCount

Table 7.4: Features of .NET 6

11

Aggregating sequences

.NET 7, November 2022‌

Finally unified with the mobile platform, added more features like string syntax coloring and IntelliSense, support for creating and extracting Tar archives, and improving the performance of inserts and updates with EF Core, including the topics listed in Table 7.5:

Feature Chapter Topic

[StringSyntax] attribute 8 Activating regular expression syntax coloring

[GeneratedRegex] attribute 8 Improving regular expression performance with source

generators

Tar archive support 9 Exercise 9.3 – Working with Tar archives

ExecuteUpdate and

ExecuteDelete

More efficient updates and deletes

Order and OrderDescending 11 Sorting by the item itself Table 7.5: Features of .NET 7

.NET 8, November 2023‌

Improved native AOT (ahead-of-time) compilation support, and added some advanced features for library authors related to source generation, including the topics listed in Table 7.6:

Feature Chapter Topic

Terminal logger for build output and changed default publish configuration

Managing projects using the dotnet CLI

Simplified output paths 7 Controlling where build artifacts are created

Improved native AOT support 7 Native ahead-of-time compilation

New Random methods 8 Generating random numbers for games and similar apps

New array, collection, and span initialization syntax

Initializing collections using collection expressions

Frozen collections 8 Read-only, immutable, and frozen collections

New data validation attributes 10 Using EF Core annotation attributes to define the model

Table 7.6: Features of .NET 8

Checking your .NET SDKs for updates‌

Introduced with .NET 6, Microsoft added a command to check the versions of .NET SDKs and runtimes that you have installed and warn you if any need updating. For example, enter the following command:

dotnet sdk check

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

.NET SDKs:

Version Status

5.0.214

.NET 5.0 is out of support.

6.0.101

Patch 6.0.119 is available.

6.0.314

Up to date.

7.0.304

Patch 7.0.305 is available.

8.0.100

Up to date.

Good Practice: To maintain support from Microsoft, you must keep your .NET SDKs and

.NET runtimes up to date with the latest patches.

Understanding .NET components‌

.NET is made up of several pieces, which are shown in the following list:

image

Language compilers: These turn your source code written with languages such as C#, F#, and Visual Basic into intermediate language (IL) code stored in assemblies. With C# 6 and later, Microsoft switched to an open-source rewritten compiler known as Roslyn, which is also used by Visual Basic.

image

Common Language Runtime (CoreCLR): This runtime loads assemblies, compiles the IL code stored in them into native code instructions for your computer's CPU, and executes the code within an environment that manages resources such as threads and memory.

image

Base Class Libraries (BCL or CoreFX): These are prebuilt assemblies of types packaged and distributed using NuGet for performing common tasks when building applications. You can use them to quickly build anything you want, rather like combining LEGO™ pieces.

Assemblies, NuGet packages, and namespaces‌

An assembly is where a type is stored in the filesystem. Assemblies are a mechanism for deploying code. For example, the System.Data.dll assembly contains types for managing data. To use types in other assemblies, they must be referenced. Assemblies can be static (pre- created) or dynamic (generated at runtime). Dynamic assemblies are an advanced feature that we will not cover in this book. Assemblies can be compiled into a single file as a DLL (class library) or an EXE (console app).Assemblies are distributed as NuGet packages, which are files that are downloadable from public online feeds and can contain multiple assemblies and other resources. You will also hear about project SDKs, workloads, and platforms, which are combinations of NuGet packages.Microsoft's NuGet feed is found here: https://www.nuget.org/.

What is a namespace?‌

A namespace is the address of a type. Namespaces are a mechanism to uniquely identify a type by requiring a full address rather than just a short name. In the real world, Bob of 34 Sycamore Street is different from Bob of 12 Willow Drive.In .NET, the IActionFilter interface of the System.Web.Mvc namespace is different from the IActionFilter interface of the System.Web.Http.Filters namespace.

Dependent assemblies‌

If an assembly is compiled as a class library and provides types for other assemblies to use, then it has the file extension .dll (dynamic link library), and it cannot be executed standalone.Likewise, if an assembly is compiled as an application, then it has the file extension .exe (executable) and can be executed standalone. Before .NET Core 3, console apps were compiled to .dll files and had to be executed by the dotnet run command or a host

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

Microsoft .NET project SDKs‌

By default, console applications have a dependency reference on the Microsoft .NET project SDK. This platform contains thousands of types in NuGet packages that almost all applications would need, such as the System.Int32 and System.String types.When using .NET, you reference the dependency assemblies, NuGet packages, and platforms that your application needs in a project file.Let's explore the relationship between assemblies and namespaces:

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

image

Project template: Console App / console

image

Project file and folder: AssembliesAndNamespaces

image

Solution file and folder: Chapter07

Open AssembliesAndNamespaces.csproj and note that it is a typical project file for a

.NET application, as shown in the following markup:

Exe

net8.0

enable

enable

1. After the section, add a new section to statically import System.Console for all C# files using the implicit usings .NET SDK feature, as shown in the following markup:

Namespaces and types in assemblies‌

Many common .NET types are in the System.Runtime.dll assembly. There is not always a one-to- one mapping between assemblies and namespaces. A single assembly can contain many namespaces and a namespace can be defined in many assemblies. You can see the relationship between some assemblies and the namespaces that they supply types for, as shown in Table 7.7:

Assembly Example namespaces Example types

System.Runtime.dll System , System.Collections ,

System.Collections.Generic

Int32 , String ,

IEnumerable

System.Console.dll System Console

System.Threading.dll System.Threading Interlocked , Monitor ,

Mutex

System.Xml.XDocument.dll System.Xml.Linq XDocument , XElement ,

XNode

Table 7.7: Examples of assemblies and their namespaces

NuGet packages‌

.NET is split into a set of packages, distributed using a Microsoft-supported package management technology named NuGet. Each of these packages represents a single assembly of the same name. For example, the System.Collections package contains the System.Collections.dll assembly.The following are the benefits of packages:

image

image

Packages can be easily distributed on public feeds. Packages can be reused.

image

Packages can ship on their own schedule.

image

Packages can be tested independently of other packages.

image

Packages can support different OSes and CPUs by including multiple versions of the same assembly built for different OSes and CPUs.

image

Packages can have dependencies specific to only one library.

image

Apps are smaller because unreferenced packages aren't part of the distribution. Table

7.8 lists some of the more important packages and their important types:

Package Important types

System.Runtime Object , String , Int32 , Array System.Collections List , Dictionary System.Net.Http HttpClient , HttpResponseMessage System.IO.FileSystem File , Directory System.Reflection Assembly , TypeInfo , MethodInfo

Table 7.8: Some important packages and their important types

Understanding frameworks‌

There is a two-way relationship between frameworks and packages. Packages define the APIs, while frameworks group packages. A framework without any packages would not define any APIs..NET packages each support a set of frameworks. For example, the System.IO.FileSystem package version 4.3.0 supports the following frameworks:

image

.NET Standard, version 1.3 or later.

image

.NET Framework, version 4.6 or later.

image

Six Mono and Xamarin platforms (for example, Xamarin.iOS).

More Information: You can read the details at the following link: https://www.nuget.org/packages/System.IO.FileSystem/ #supportedframeworks-body-tab.

Importing a namespace to use a type‌

Let's explore how namespaces are related to assemblies and types:

1. In the AssembliesAndNamespaces project, in Program.cs , delete the existing statements and then enter the following code:

XDocument doc = new();

Recent versions of code editors will often automatically add a namespace import statement to fix the problem I want you to see. Please delete the using statement that your code editor writes for you.

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

CS0246 The type or namespace name 'XDocument' could not be found (are you missing a using direct

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

Click inside the XDocument class name. Your code editor displays a light bulb, showing that it recognizes the type and can automatically fix the problem for you.

Click the light bulb, and select using System.Xml.Linq; from the menu.

This will import the namespace by adding a using statement to the top of the file. Once a namespace is imported at the top of a code file, then all the types within the namespace are available for use in that code file by just typing their name, without the type name needing to be fully qualified by prefixing it with its namespace.I like to add a comment after importing a namespace to remind me why I need to import that namespace, as shown in the following code:

using System.Xml.Linq; // To use XDocument.

If you do not comment your namespaces, you or other developers will not know why they are imported and might delete them, breaking the code. Or they might never delete imported namespaces "just in case" they are needed, potentially cluttering the code unnecessarily. This is why most modern code editors have features to remove unused namespaces. This technique also subconsciously trains you, while you are learning, to remember which namespace you need to import to use a particular type or extension method.

Relating C# keywords to .NET types‌

One of the common questions I get from new C# programmers is, "What is the difference between string with a lowercase s and String with an uppercase S?"The short answer is easy: none. The long answer is that all C# keywords that represent types like string or int are aliases for a .NET type in a class library assembly.When you use the string keyword, the compiler recognizes it as a System.String type. When you use the int type, the compiler recognizes it as a System.Int32 type.Let's see this in action with some code:

1. In Program.cs , declare two variables to hold string values, one using lowercase string

and one using uppercase String , as shown in the following code:

string s1 = "Hello"; String s2 = "World"; WriteLine($"{s1} {s2}");

Run the AssembliesAndNamespaces project and note that string and String both work and literally mean the same thing.

In AssembliesAndNamespaces.csproj , add an entry to prevent the System namespace from being globally imported, as shown in the following markup:

1. In Program.cs , and in the Error List or PROBLEMS window, note the compiler error message, as shown in the following output:

CS0246 The type or namespace name 'String' could not be found (are you missing a using directive

1. At the top of Program.cs , import the System namespace with a using statement that will fix the error, as shown in the following code:

using System; // To use String.

Good Practice: When you have a choice, use the C# keyword instead of the actual type because the keywords do not need a namespace to be imported.

Mapping C# aliases to .NET types‌

Table 7.9 shows the 18 C# type keywords along with their actual .NET types:

Keyword .NET type Keyword .NET type string System.String char System.Char sbyte System.SByte byte System.Byte short System.Int16 ushort System.UInt16 int System.Int32 uint System.UInt32 long System.Int64 ulong System.UInt64 nint System.IntPtr nuint System.UIntPtr float System.Single double System.Double decimal System.Decimal bool System.Boolean

object System.Object dynamic System.Dynamic.DynamicObject

Table 7.9: C# type keywords and their actual .NET types

Other .NET programming language compilers can do the same thing. For example, the Visual Basic .NET language has a type named Integer , which is its alias for System.Int32 .

Understanding native-sized integers‌

C# 9 introduced the nint and nuint keyword aliases for native-sized integers, meaning that the storage size for the integer value is platform-specific. They store a 32-bit integer in a 32-bit process and sizeof() returns 4 bytes; they store a 64-bit integer in a 64-bit process and sizeof() returns 8 bytes. The aliases represent pointers to the integer value in memory, which is why their .NET names are IntPtr and UIntPtr . The actual storage type will be either System.Int32 or System.Int64 , depending on the process.In a 64-bit process, the following code:

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

produces this output:

Environment.Is64BitProcess = True int.MaxValue = 2,147,483,647

nint.MaxValue = 9,223,372,036,854,775,807

Revealing the location of a type‌

Code editors provide built-in documentation for .NET types. Let's start by making sure that you have the expected experience and then explore:

image

If you are using Visual Studio 2022, then make sure you have disabled Source Link: Navigate to Tools | Options.

image

image

In the search box, enter navigation in source . Select Text Editor | C# | Advanced.

image

Clear the Enable navigation to Source Link and Embedded sources checkbox, and then click OK.

Right-click inside XDocument and choose Go to Definition.

Navigate to the top of the code file, expand the collapsed region, and note the assembly filename is System.Xml.XDocument.dll , but the class is in the System.Xml.Linq namespace, as shown in the following code and in Figure 7.1:

#region Assembly System.Runtime, Version=8.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a

// C:\Program Files\dotnet\packs\Microsoft.NETCore.App.Ref\8.0.0\ref\net8.0\System.Runtime.dll #endregion

image

Figure 7.1: Assembly and namespace that contains the XDocument type

Close the XDocument [from metadata] tab.

Right-click inside string or String and choose Go to Definition.

Navigate to the top of the code file, expand the collapsed region, and note the assembly filename is System.Runtime.dll but the class is in the System namespace.

Your code editor is technically lying to you. If you remember when we wrote code in Chapter 2, Speaking C#, when we revealed the extent of the C# vocabulary, we discovered that the System.Runtime.dll assembly contains zero types.What the System.Runtime.dll assembly does contain are type-forwarders. These are special types that appear to exist in an assembly but are implemented elsewhere. In this case, they are implemented deep inside the .NET runtime using highly optimized code.You might want to use a type-forwarder if you refactor a type to move it from its original assembly to a different one. Without defining a type-forwarder, any projects that reference the original assembly will not find the type in it and a runtime exception will be thrown. You can read more about this contrived example at the following link: https://learn.microsoft.com/en-us/dotnet/standard/assembly/type-forwarding.

Sharing code with legacy platforms using .NET Standard‌

Before .NET Standard, there were Portable Class Libraries (PCLs). With PCLs, you could create a library of code and explicitly specify which platforms you want the library to support, such as Xamarin, Silverlight, and Windows 8. Your library could then use the intersection of APIs that are supported by the specified platforms.Microsoft realized that this was unsustainable, so they created .NET Standard—a single API that all future .NET platforms would support. There are older versions of .NET Standard, but .NET Standard 2.0 was an attempt to unify all important recent .NET platforms. .NET Standard 2.1 was released in late 2019 but only .NET Core 3.0 and that year's version of Xamarin support its new features. For the rest of this book, I will use the term .NET Standard to mean .NET Standard 2.0..NET Standard is like HTML5 in that they are both standards that a platform should support. Just as Google's Chrome browser and Microsoft's Edge browser implement the HTML5 standard, .NET Core, .NET Framework, and Xamarin all implement .NET Standard. If you want to create a library of types that will work across variants of legacy .NET, you can do so most easily with .NET Standard.

Good Practice: Since many of the API additions in .NET Standard 2.1 required runtime changes, and .NET Framework is Microsoft's legacy platform that needs to remain as unchanging as possible, .NET Framework 4.8 remained on .NET Standard 2.0 rather than implementing .NET Standard 2.1. If you need to support .NET Framework customers, then you should create class libraries on .NET Standard 2.0, even though it is not the latest and does not support all the recent language and BCL new features.

Your choice of which .NET Standard version to target comes down to a balance between maximizing platform support and available functionality. A lower version supports more platforms but has a smaller set of APIs. A higher version supports fewer platforms but has a larger set of APIs. Generally, you should choose the lowest version that supports all the APIs that you need.

Understanding defaults for class libraries with different SDKs‌

When using the dotnet SDK tool to create a class library, it might be useful to know which target framework will be used by default, as shown in Table 7.10:

SDK Default target framework for new class libraries

.NET Core 3.1 netstandard2.0

.NET 6 net6.0

.NET 7 net7.0

.NET 8 net8.0

Table 7.10: .NET SDKs and their default target framework for new class libraries

Of course, just because a class library targets a specific version of .NET by default, it does not mean you cannot change it after creating a class library project using the default template.You can manually set the target framework to a value that supports the projects that need to reference that library, as shown in Table 7.11:

Class library target framework

Can be used by projects that target

netstandard2.0 .NET Framework 4.6.1 or later, .NET Core 2 or later, .NET 5 or later, Mono

5.4 or later, Xamarin.Android 8 or later, and Xamarin.iOS 10.14 or later.

netstandard2.1 .NET Core 3 or later, .NET 5 or later, Mono 6.4 or later, Xamarin.Android

10 or later, and Xamarin.iOS 12.16 or later.

net6.0 .NET 6 or later.

net7.0 .NET 7 or later.

net8.0 .NET 8 or later.

Table 7.11: Class library target frameworks and the projects that can use them

Good Practice: Always check the target framework of a class library and then manually change it to something more appropriate if necessary. Make a conscious decision about what it should be rather than accepting the default.

Creating a .NET Standard class library‌

We will create a class library using .NET Standard 2.0 so that it can be used across all important .NET legacy platforms and cross-platform on Windows, macOS, and Linux operating systems, while also having access to a wide set of .NET APIs:

1. Use your preferred code editor to add a new Class Library / classlib project named

SharedLibrary that targets .NET Standard 2.0 to the Chapter07 solution:

image

If you use Visual Studio 2022, when prompted for the Target Framework, select .NET Standard 2.0, and then configure the startup project for the solution to the current selection.

image

If you use Visual Studio Code, include a switch to target .NET Standard 2.0, as shown in the following command:

dotnet new classlib -f netstandard2.0

Good Practice: If you need to create types that use new features in .NET 8, as well as types that only use .NET Standard 2.0 features, then you can create two separate class libraries: one targeting .NET Standard 2.0 and one targeting .NET 8.

An alternative to manually creating two class libraries is to create one that supports multi-targeting. If you would like me to add a section about multi-targeting to the next edition, please let me know. You can read about multi-targeting here: https://learn.microsoft.com/en-us/dotnet/standard/library-guidance/cross-platform- targeting#multi-targeting.

Controlling the .NET SDK‌

By default, executing dotnet commands uses the highest version installed .NET SDK. There may be times when you want to control which SDK is used.For example, once .NET 9 is available in preview starting in February 2024, or the final version in November 2024, you might install it. But you would probably want your experience to match the book steps that use the .NET 8 SDK. But once you install a .NET 9 SDK, then it will be used by default. You can control the .NET SDK used by default by using a global.json file, which contains the version to use. The dotnet command searches the current folder and then each ancestor folder in turn for a global.json file to see if it should use a different .NET SDK version.You do not need to complete the following steps, but if you want to try and do not already have .NET 6 SDK installed, then you can install it from the following link:https://dotnet.microsoft.com/download/dotnet/6.0

Create a subdirectory/folder in the Chapter07 folder named ControlSDK .

On Windows, start Command Prompt or Windows Terminal. On macOS, start Terminal. If you are using Visual Studio Code, then you can use the integrated terminal.

In the ControlSDK folder, at the command prompt or terminal, enter a command to list the installed .NET SDKs, as shown in the following command:

dotnet --list-sdks

1. Note the results and the version number of the latest .NET 6 SDK installed, as shown highlighted in the following output:

5.0.214 [C:\Program Files\dotnet\sdk]

6.0.314 [C:\Program Files\dotnet\sdk]

7.0.304 [C:\Program Files\dotnet\sdk]

8.0.100 [C:\Program Files\dotnet\sdk]

1. Create a global.json file that forces the use of the latest .NET Core 6.0 SDK that you have installed (which might be later than mine), as shown in the following command:

dotnet new globaljson --sdk-version 6.0.314

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

The template "global.json file" was created successfully.

1. Use your preferred code editor to open the global.json file and review its contents, as shown in the following markup:

{

"sdk": {

"version": "6.0.314"

}

}

For example, to open it with Visual Studio Code, enter the command: code global.json .

1. In the ControlSDK folder, at the command prompt or terminal, enter a command to create a class library project, as shown in the following command:

dotnet new classlib

1. If you do not have the .NET 6 SDK installed, then you will see an error, as shown in the following output:

Could not execute because the application was not found or a compatible .NET SDK is not installe

1. If you do have the .NET 6 SDK installed, then a class library project will be created that targets .NET 6 by default, as shown highlighted in the following markup:

net6.0

enable

enable

Mixing SDKs and framework targets‌

Many organizations decide to target a long-term support version of .NET to get up to three years of support from Microsoft. Doing this does not mean you lose the benefits of improvements to the C# language during the lifetime of the .NET runtime that you need to target.You can easily continue to target the .NET 8 runtime while installing and using future C# compilers, as shown in Figure 7.2 and illustrated in the following list:

November 2023: Install .NET SDK 8.0.100 and use it to build projects that target .NET 8 and use the C# 12 compiler by default. Every month, update to .NET 8 SDK patches on the development computer and update to .NET 8 runtime patches on any deployment computers.

February 2024: Optionally, install .NET SDK 9 Preview 1 to explore the new C# language and .NET library features. Note that you won't be able to use new library features while targeting .NET 8. Previews are released monthly between February and October each year. Read the monthly announcement blog posts to find out about the new features in that preview.

November 2024: Install .NET SDK 9.0.100 and use it to build projects that continue to target .NET 8 and use the C# 13 compiler for its new features. You will be using a fully supported SDK and fully supported runtime. You can also use new features in EF Core 9 because it will continue to target .NET 8.

February 2025: Optionally, install .NET 10 previews to explore new C# language and .NET library features. Start planning if any new library and ASP.NET Core features in .NET 9 and .NET 10 can be applied to your .NET 8 projects when you are ready to migrate.

November 2025: Install .NET 10.0.100 SDK and use it to build projects that target .NET

8 and use the C# 14 compiler. Migrate your .NET 8 projects to .NET 10 since it is an LTS release. You have until November 2026 to complete the migration when .NET 8 reaches end- of-life.

image

Figure 7.2: Targeting .NET 8 for long-term support while using the latest C# compilers

When deciding to install a .NET SDK, remember that the latest is used by default to build any .NET projects. Once you've installed a .NET 9 SDK preview, it will be used by default for all projects, unless you force the use of an older, fully supported SDK version like

8.0.100 or a later patch.

Publishing your code for deployment‌

If you write a novel and you want other people to read it, you must publish it.Most developers write code for other developers to use in their own projects, or for users to run as an app. To do so, you must publish your code as packaged class libraries or executable applications.There are three ways to publish and deploy a .NET application. They are:

image

image

image

Framework-dependent deployment (FDD) Framework-dependent executable (FDE) Self-contained

If you choose to deploy your application and its package dependencies, but not .NET itself, then you rely on .NET already being on the target computer. This works well for web applications deployed to a server because .NET and lots of other web applications are likely already on the server.FDD means you deploy a DLL that must be executed by the dotnet command-line tool. FDE means you deploy an EXE that can be run directly from the command line. Both require the appropriate version of the .NET runtime to be installed on the system.Sometimes, you want to be able to give someone a USB stick containing your application built for their operating system and know that it can execute on their computer. You would want to perform a self-contained deployment. While the size of the deployment files will be larger, you'll know that it will work.

Creating a console app to publish‌

Let's explore how to publish a console app:

Use your preferred code editor to add a new Console App / console project named

DotNetEverywhere to the Chapter07 solution. Make sure you target .NET 8.

Modify the project file to statically import the System.Console class in all C# files.

In Program.cs , delete the existing statements, and then add a statement to output a message saying the console app can run everywhere and some information about the operating system, as shown in the following code:

WriteLine("I can run everywhere!");

WriteLine($"OS Version is {Environment.OSVersion}."); if (OperatingSystem.IsMacOS())

{

WriteLine("I am macOS.");

}

else if (OperatingSystem.IsWindowsVersionAtLeast(major: 10, build: 22000))

{

WriteLine("I am Windows 11.");

}

else if (OperatingSystem.IsWindowsVersionAtLeast(major: 10))

{

WriteLine("I am Windows 10.");

}

else

{

WriteLine("I am some other mysterious OS.");

}

WriteLine("Press any key to stop me.");

ReadKey(intercept: true); // Do not output the key that was pressed.

1. Run the DotNetEverywhere project and note the results when run on Windows 11, as shown in the following output:

I can run everywhere!

OS Version is Microsoft Windows NT 10.0.22000.0. I am Windows 11.

Press any key to stop me.

1. In DotNetEverywhere.csproj , add the runtime identifiers (RIDs) to target three operating systems inside the element, as shown highlighted in the following markup:

Exe

net8.0

enable

enable

win10-x64;osx-x64;osx.11.0-arm64;linux-x64;linux-arm64

image

The win10-x64 RID value means Windows 10 or Windows Server 2016 64-bit. You could also use the win10-arm64 RID value to deploy to a Microsoft Surface Pro X.

image

The osx-x64 RID value means macOS Sierra 10.12 or later. You can also specify version- specific RID values like osx.10.15-x64 (Catalina), osx.11.0-x64 (Big Sur on Intel), or osx.11.0-arm64 (Big Sur on Apple Silicon).

image

The linux-x64 RID value means most desktop distributions of Linux, like Ubuntu, CentOS,

Debian, or Fedora. Use linux-arm for Raspbian or Raspberry Pi OS 32-bit. Use

linux-arm64 for a Raspberry Pi running Ubuntu 64-bit.

There are two elements that you can use to specify runtime identifiers. Use

if you only need to specify one. Use if you need to specify multiple, as we did in the preceding example. If you use the wrong one,

then the compiler will give an error and it can be difficult to understand why with only one character difference!

Understanding dotnet commands‌

When you install the .NET SDK, it includes a command-line interface (CLI) named dotnet .The

.NET CLI has commands that work on the current folder to create a new project using templates:

On Windows, start Command Prompt or Windows Terminal. On macOS, start Terminal. If you prefer to use Visual Studio 2022 or Visual Studio Code, then you can use the integrated terminal.

Enter the dotnet new list (or dotnet new -l or dotnet new --list with older SDKs) command to list your currently installed templates, the most common of which are shown in Table 7.12:

Template Name Short Name Language

.NET MAUI App maui C#

.NET MAUI Blazor App maui-blazor C#

ASP.NET Core Empty web C#, F#

ASP.NET Core gRPC Service grpc C#

ASP.NET Core Web API webapi C#, F# ASP.NET Core Web API (native AOT) api C# ASP.NET Core Web App (Model-View-Controller) mvc C#, F# Blazor Web App blazor C#

Class Library classlib C#, F#, VB

Console App console C#, F#, VB

EditorConfig File editorconfig

global.json File globaljson

Solution File sln

xUnit Test Project xunit

Table 7.12: Project template full and short names

.NET MAUI projects are not supported for Linux. The team has said they have left that work to the open source community. If you need to create a truly cross-platform graphical app, then take a look at Avalonia at the following link: https://avaloniaui.net/.

Getting information about .NET and its environment‌

It is useful to see what .NET SDKs and runtimes are currently installed, alongside information about the operating system, as shown in the following command:

dotnet --info

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

.NET SDK (reflecting any global.json): Version: 8.0.100

Commit: 3fe444af72 Runtime Environment:

OS Name: Windows

OS Version: 10.0.22621 OS Platform: Windows RID: win10-x64

Base Path: C:\Program Files\dotnet\sdk\8.0.100\

.NET workloads installed:

There are no installed workloads to display. Host (useful for support):

Version: 8.0.0 Commit: bc78804f5d

.NET SDKs installed:

5.0.214 [C:\Program Files\dotnet\sdk]

6.0.317 [C:\Program Files\dotnet\sdk]

7.0.401 [C:\Program Files\dotnet\sdk]

8.0.100 [C:\Program Files\dotnet\sdk]

.NET runtimes installed:

Microsoft.AspNetCore.App 5.0.17 [...\dotnet\shared\Microsoft.AspNetCore.All]

...

Managing projects using the dotnet CLI‌

The .NET CLI has the following commands that work on the project in the current folder, to manage the project:

image

dotnet help : This shows the command-line help.

image

dotnet new : This creates a new .NET project or file.

image

dotnet tool : This installs or manages tools that extend the .NET experience.

image

dotnet workload : This manages optional workloads like .NET MAUI.

image

dotnet restore : This downloads dependencies for the project.

image

dotnet build : This builds, aka compiles, a .NET project. A new switch introduced with

.NET 8 is --tl (meaning terminal logger), which provides a modern output. For example, it provides real-time information about what the build is doing. You can learn more at the following link: https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet- build#options.

image

dotnet build-server : This interacts with servers started by a build.

image

dotnet msbuild : This runs MS Build Engine commands.

image

image

image

dotnet clean : This removes the temporary outputs from a build. dotnet test : This builds and then runs unit tests for the project. dotnet run : This builds and then runs the project.

image

dotnet pack : This creates a NuGet package for the project.

image

dotnet publish : This builds and then publishes the project, either with dependencies or as a self-contained application. In .NET 7 and earlier, this published the Debug configuration by default. In .NET 8 and later, it now publishes the Release configuration by default.

image

dotnet add : This adds a reference to a package or class library to the project.

image

dotnet remove : This removes a reference to a package or class library from the project.

image

dotnet list : This lists the package or class library references for the project.

Publishing a self-contained app‌

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

At the command prompt or terminal, make sure that you are in the DotNetEverywhere

folder.

Enter a command to build and publish the self-contained release version of the console application for Windows 10, as shown in the following command:

dotnet publish -c Release -r win10-x64 --self-contained

1. Note the build engine restores any needed packages, compiles the project source code into an assembly DLL, and creates a publish folder, as shown in the following output:

MSBuild version 17.8.0+14c24b2d3 for .NET Determining projects to restore...

All projects are up-to-date for restore.

DotNetEverywhere -> C:\cs12dotnet8\Chapter07\DotNetEverywhere\bin\Release\net8.0\win10-x64\Dot DotNetEverywhere -> C:\cs12dotnet8\Chapter07\DotNetEverywhere\bin\Release\net8.0\win10-x64\pub

1. Enter the following commands to build and publish the release versions for macOS and Linux variants:

dotnet publish -c Release -r osx-x64 --self-contained

dotnet publish -c Release -r osx.11.0-arm64 --self-contained dotnet publish -c Release -r linux-x64 --self-contained dotnet publish -c Release -r linux-arm64 --self-contained

Good Practice: You could automate these commands by using a scripting language like PowerShell and execute the script file on any operating system using the cross-platform PowerShell Core. I have done this for you at the following link: https://github.com/markjprice/cs12dotnet8/tree/main/scripts/publish-scripts.

Open Windows File Explorer or a macOS Finder window, navigate to DotNetEverywhere\bin\Release\net8.0 , and note the output folders for the five operating systems.

In the win10-x64 folder, open the publish folder, and note all the supporting assemblies, like Microsoft.CSharp.dll .

Select the DotNetEverywhere executable file, and note it is 154 KB, as shown in Figure 7.3:

image

Figure 7.3: The DotNetEverywhere executable file for Windows 10 64-bit

If you are on Windows, then double-click to execute the program and note the result, as shown in the following output:

I can run everywhere!

OS Version is Microsoft Windows NT 10.0.22621.0. I am Windows 11.

Press any key to stop me.

Press any key to close the console app and its window.

Note that the total size of the publish folder and all its files is 68.3 MB.

In the osx.11.0-arm64 folder, select the publish folder, note all the supporting assemblies, and then select the DotNetEverywhere executable file. Note that the executable is 125 KB, and the publish folder is about 73.9 MB. There is no .exe file extension for published applications on macOS, so the filename will not have an extension.

If you copy any of those publish folders to the appropriate operating system, the console app will run; this is because it is a self-contained deployable .NET application. For

example, here it is on macOS with Intel:

I can run everywhere!

OS Version is Unix 13.5.2 I am macOS.

Press any key to stop me.

This example used a console app, but you could just as easily create an ASP.NET Core website or web service, or a Windows Forms or WPF app. Of course, you can only deploy Windows desktop apps to Windows computers, not Linux or macOS.

Publishing a single-file app‌

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

dotnet publish -r win10-x64 -c Release --no-self-contained

/p:PublishSingleFile=true

This will generate two files: DotNetEverywhere.exe and DotNetEverywhere.pdb . The .exe file is the executable. The .pdb file is a program debug database file that stores debugging information.If you prefer the .pdb file to be embedded in the .exe file, for example, to ensure it is deployed with its assembly, then add a element to the

element in your .csproj file and set it to embedded , as shown highlighted in the following markup:

Exe

net8.0

enable

enable

win10-x64;osx-x64;osx.11.0-arm64;linux-x64;linux-arm64

embedded

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

1. At the command prompt or terminal, in the DotNetEverywhere folder, enter the command to build the self-contained release version of the console app for Windows 10, as shown in the following command:

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

1. Navigate to the DotNetEverywhere\bin\Release\net8.0\win10-x64\publish folder and select the DotNetEverywhere executable file. Note that the executable is now 62.6 MB, and there is also a .pdb file that is 11 KB. The sizes of these files on your system will vary.

Reducing the size of apps using app trimming‌

One of the problems with deploying a .NET app as a self-contained app is that the .NET libraries take up a lot of space. One of the biggest needs is to reduce the size of Blazor WebAssembly components because all the .NET libraries need to be downloaded to the browser.Luckily, you can reduce this size by not packaging unused assemblies with your

deployments. Introduced with .NET Core 3, the app trimming system can identify the assemblies needed by your code and remove those that are not needed. This was known as copyused trim mode.With .NET 5, the trimming went further by removing individual types, and even members, like methods from within an assembly if they are not used. For example, with a Hello World console app, the System.Console.dll assembly is trimmed from 61.5 KB to 31.5 KB. This was known as link trim mode, but it was not enabled by default.With .NET 6, Microsoft added annotations to their libraries to indicate how they can be safely trimmed so the trimming of types and members was made the default.With .NET 7, Microsoft renamed link to full and copyused to partial .The catch is how well the trimming identifies unused assemblies, types, and members. If your code is dynamic, perhaps using reflection, then it might not work correctly, so Microsoft also allows manual control.There are two ways to enable type-level and member-level, aka full , trimming. Since this level of trimming is the default with .NET 6 or later, all we need to do is enable trimming without setting a trim level or mode.The first way is to add an element in the project file, as shown in the following markup:

true

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

dotnet publish ... -p:PublishTrimmed=True

There are two ways to enable assembly-level, aka partial , trimming.The first way is to add two elements in the project file, as shown in the following markup:

true

partial

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

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

Controlling where build artifacts are created‌

Traditionally, each project has its own bin and obj subfolders where temporary files are created during the build process. When you publish, the files are created in the bin folder.You might prefer to put all these temporary files and folders somewhere else.

Introduced with .NET 8 is the ability to control where build artifacts are created. Let's see how:

1. At the command prompt or terminal for the Chapter07 folder, enter the following command:

dotnet new buildprops --use-artifacts

1. Note the success message, as shown in the following output:

The template "MSBuild Directory.Build.props file" was created successfully.

We could have created this file in the cs12dotnet8 folder, and it would then affect all projects in all chapters.

1. In the Chapter07 folder, open the Directory.Build.props file, as shown in the following markup:

enable

enable

Good Practice: Preview features are not supported in production code. Preview features are likely to have breaking changes before the final release. Enable preview features at your own risk. Switch to a GA release future SDK like .NET 9 to use new compiler features while still targeting older but longer supported versions of .NET like .NET 8.

Requiring preview features‌

The [RequiresPreviewFeatures] attribute is used to indicate assemblies, types, or members that use and therefore require warnings about preview features. A code analyzer then scans for this assembly and generates warnings if needed. If your code does not use any preview features, you will not see any warnings. If you use any preview features, then your code should warn consumers of your code that you use preview features.

Enabling preview features‌

In the Project file, add an element to enable preview features and an element to enable preview language features, as shown highlighted in the following markup:

Exe

net8.0

enable

enable

true

preview

Method interceptors‌

An interceptor is a method that substitutes for a call to an interceptable method with a call to itself. They are an advanced feature most commonly used in source generators. If readers are interested, then I might add a section about them to the ninth edition.

More Information: You can learn more about interceptors at the following link: https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-12#interceptors.

Practicing and exploring‌

Test your knowledge and understanding by answering some questions, getting some hands-on practice, and exploring with deeper research into the topics of this chapter.

Exercise 7.1 – Test your knowledge‌

Answer the following questions:

What is the difference between a namespace and an assembly?

How do you reference another project in a .csproj file?

What is the benefit of a tool like ILSpy?

Which .NET type does the C# float alias represent?

When porting an application from .NET Framework to .NET 6, what tool should you run before porting, and what tool could you run to perform much of the porting work?

What is the difference between framework-dependent and self-contained deployments of

.NET applications?

What is a RID?

What is the difference between the dotnet pack and dotnet publish commands?

What types of applications written for the .NET Framework can be ported to modern .NET?

Can you use packages written for .NET Framework with modern .NET?

Exercise 7.2 – 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-7--- packaging-and-distributing-net-types

Exercise 7.3 – Porting from .NET Framework to modern .NET‌

If you are interested in porting legacy projects from .NET Framework to modern .NET, then I have written an online-only section at the following link:https://github.com/markjprice/cs12dotnet8/blob/main/docs/ch07-porting.md

Exercise 7.4 – Creating source generators‌

If you are interested in creating source generators, then I have written an online-only section at the following link:https://github.com/markjprice/cs12dotnet8/blob/main/docs/ch07- source-generators.mdYou can find examples of source generators at the following link:https://github.com/amis92/csharp-source-generators

Exercise 7.5 – Explore PowerShell‌

PowerShell is Microsoft's scripting language for automating tasks on every operating system. Microsoft recommends Visual Studio Code with the PowerShell extension for writing PowerShell scripts.Since PowerShell is its own extensive language, there is not enough space in this book to cover it. You can learn about some key concepts from a Microsoft training module at the following link: https://learn.microsoft.com/en-us/training/modules/introduction-to- powershell/You can read the official documentation at the following link: https://learn.microsoft.com/en-us/powershell/.

Exercise 7.6 – Improving performance in .NET‌

Microsoft has made significant improvements to performance in the past few years. You should review the blog posts written by Stephen Toub to learn what the team changed and why. His posts are famously long, detailed, and brilliant!You can find the posts about the improvements at the following links:https://devblogs.microsoft.com/dotnet/performance- improvements-in-net-core/ - 25 pageshttps://devblogs.microsoft.com/dotnet/performance- improvements-in-net-core-2-1/ - 20 pageshttps://devblogs.microsoft.com/dotnet/performance- improvements-in-net-core-3-0/ - 41 pageshttps://devblogs.microsoft.com/dotnet/performance- improvements-in-net-5/ - 43 pageshttps://devblogs.microsoft.com/dotnet/performance- improvements-in-net-6/ - 100

pageshttps://devblogs.microsoft.com/dotnet/performance_improvements_in_net_7/ - 156 pageshttps://devblogs.microsoft.com/dotnet/performance-improvements-in-net-8/ - 218 pagesGet

ready for .NET 9's article being almost 300 pages. 😉

Summary‌

In this chapter, we:

image

image

Reviewed the journey to .NET 8 for BCL functionality. Explored the relationship between assemblies and namespaces.

image

image

image

Saw options for publishing an app for distribution to multiple operating systems. Learned how to publish to native AOT for faster startup and smaller memory footprint. Learned how to decompile .NET assemblies for educational purposes.

image

image

Packaged and distributed a class library. Learned how to activate preview features.

In the next chapter, you will learn about some common BCL types that are included with modern .NET.

8 Working with Common .NET Types‌‌‌

Join our book community on Discord

https://packt.link/EarlyAccess

image

This chapter is about some common types that are included with .NET. These include types for manipulating numbers, text, and collections; improving working with spans, indexes, and ranges; and in an optional online-only section, working with network resources.This chapter covers the following topics:

image

image

Working with numbers Working with text

image

image

image

Pattern matching with regular expressions Storing multiple objects in collections Working with spans, indexes, and ranges

Working with numbers‌

One of the most common types of data is numbers. The most common types in .NET for working with numbers are shown in Table 8.1:

Namespace Example type(s) Description

System SByte , Int16 , Int32 ,

Int64 , Int128

System Byte , UInt16 , UInt32 ,

UInt64 , UInt128

Integers; that is, zero, and positive and negative whole numbers.

Cardinals; that is, zero and positive whole numbers.

System Half , Single , Double Reals; that is, floating-point numbers.

System Decimal Accurate reals; that is, for use in science, engineering, or financial scenarios.

System.Numerics BigInteger , Complex ,

Quaternion

Table 8.1: Common .NET number types

Arbitrarily large integers, complex numbers, and quaternion numbers.

.NET has had the 32-bit float and 64-bit double types since .NET Framework 1.0 was released in 2002. The IEEE 754 specification also defines a 16-bit floating-point standard. Machine learning and other algorithms would benefit from this smaller, lower-precision number type, so Microsoft introduced the System.Half type with .NET 5 and later. Currently, the C# language does not define a half alias, so you must use the .NET type System.Half . This might change in the future. System.Int128 and System.UInt128 were introduced with .NET 7, and they too do not yet have a C# alias keyword.

Working with big integers‌

The largest whole number that can be stored in .NET types that have a C# alias is about eighteen and a half quintillion, stored in an unsigned 64-bit integer using ulong . But what if you need to store numbers larger than that?Let's explore numerics:

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

image

image

image

Project template: Console App / console Project file and folder: WorkingWithNumbers Solution file and folder: Chapter08

In the project file, add an element to statically and globally import the System.Console

class.

In Program.cs , delete the existing statements and then add a statement to import

System.Numerics , as shown in the following code:

using System.Numerics; // To use BigInteger.

1. Add statements to output the maximum value of the ulong type, and a number with 30 digits using BigInteger , as shown in the following code:

const int width = 40;

WriteLine("ulong.MaxValue vs a 30-digit BigInteger"); WriteLine(new string('-', width));

ulong big = ulong.MaxValue; WriteLine($"{big,width:N0}"); BigInteger bigger =

BigInteger.Parse("123456789012345678901234567890");

WriteLine($"{bigger,width:N0}");

The width constant with the value 40 in the format code means “right-align 40 characters,” so both numbers are lined up to the right-hand edge. The N0 means “use thousand separators and zero decimal places.”

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

ulong.MaxValue vs a 30-digit BigInteger

image

18,446,744,073,709,551,615

123,456,789,012,345,678,901,234,567,890

Working with complex numbers‌

A complex number can be expressed as a + bi, where a and b are real numbers and i is an imaginary unit, where i2 = −1. If the real part a is zero, it is a pure imaginary number. If the imaginary part b is zero, it is a real number.Complex numbers have practical applications in many STEM (science, technology, engineering, and mathematics) fields of study. They are added by separately adding the real and imaginary parts of the summands; consider this:

(a + bi) + (c + di) = (a + c) + (b + d)i

Let's explore complex numbers:

1. In Program.cs , add statements to add two complex numbers, as shown in the following code:

Complex c1 = new(real: 4, imaginary: 2); Complex c2 = new(real: 3, imaginary: 7); Complex c3 = c1 + c2;

// Output using the default ToString implementation. WriteLine($"{c1} added to {c2} is {c3}");

// Output using a custom format.

WriteLine("{0} + {1}i added to {2} + {3}i is {4} + {5}i", c1.Real, c1.Imaginary,

c2.Real, c2.Imaginary, c3.Real, c3.Imaginary);

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

<4; 2> added to <3; 7> is <7; 9>

4 + 2i added to 3 + 7i is 7 + 9i

.NET 6 and earlier used a different default format for complex numbers:

(4, 2) added to (3, 7) is (7, 9) . In .NET 7 and later, the default format was changed to use angle brackets and semi-colons because some cultures use round brackets to indicate negative numbers and use commas for decimal numbers. At the time of writing, the official documentation has not been updated to use the new format, as shown at the following link: https://learn.microsoft.com/en- us/dotnet/api/system.numerics.complex.tostring.

Generating random numbers for games and similar apps‌

In scenarios that don't need truly random numbers like games, you can create an instance of the Random class, as shown in the following code example:

Random r = new();

Random has a constructor with a parameter for specifying a seed value used to initialize its pseudo-random number generator, as shown in the following code:

Random r = new(Seed: 46378);

As you learned in Chapter 2, Speaking C#, parameter names should use camel case. The developer who defined the constructor for the Random class broke this convention. The parameter name should be seed , not Seed .

Good Practice: Shared seed values act as a secret key, so if you use the same random number generation algorithm with the same seed value in two applications, then they can generate the same "random" sequences of numbers. Sometimes this is necessary, for example, when synchronizing a GPS receiver with a satellite, or when a game needs to randomly generate the same level. But usually, you want to keep your seed secret.

To avoid allocating more memory than necessary, .NET 6 introduced a shared static instance of Random that you can access instead of creating your own.The Random class has commonly used methods for generating random numbers, as described in the following list:

image

Next : This method returns a random int (whole number) and it takes two parameters, minValue and maxValue , but maxValue is not the maximum value that the method returns! It is an exclusive upper bound, meaning maxValue is one more than the maximum value returned. Use the NextInt64 method to return a long integer.

image

NextDouble : This method returns a number that is greater than or equal to 0.0 and less than and never equal to 1.0 . Use the NextSingle method to return a float .

image

NextBytes : This method populates an array of any size with random byte ( 0 to 255 ) values. It is common to format byte values as hexadecimal, for example, 00 to FF .

Let's see some examples of generating pseudo-random numbers:

1. In Program.cs , add statements to access the shared Random instance, and then call its methods to generate random numbers, as shown in the following code:

Random r = Random.Shared;

// minValue is an inclusive lower bound i.e. 1 is a possible value.

// maxValue is an exclusive upper bound i.e. 7 is not a possible value. int dieRoll = r.Next(minValue: 1, maxValue: 7); // Returns 1 to 6.

WriteLine($"Random die roll: {dieRoll}");

double randomReal = r.NextDouble(); // Returns 0.0 to less than 1.0. WriteLine($"Random double: {randomReal}");

byte[] arrayOfBytes = new byte[256];

r.NextBytes(arrayOfBytes); // Fills array with 256 random bytes. Write("Random bytes: ");

for (int i = 0; i < arrayOfBytes.Length; i++) { Write($"{arrayOfBytes[i]:X2} "); } WriteLine(); 1. Run the code and view the result, as shown in the following output: Random die roll: 1 Random double: 0.06735275453092382 Random bytes: D9 38 CD F3 5B 40 2D F4 5B D0 48 DF F7 B6 67 C1 95 A1 2C 58 42 CF 70 6C C3 BE 82 D In scenarios that do need truly random numbers like cryptography, there are specialized types for that, like RandomNumberGenerator . I plan to cover this and other cryptographic types in the companion book, Tools and Skills for .NET 8 Pros in a chapter titled Protecting Data and Apps Using Cryptography, expected to publish in the first half of 2024. .NET 8 introduced two new Random methods, as described in the following list: image GetItems : This method is passed an array or read-only span of any type T of choices and the number of items you want to generate, and then it returns that number of items randomly selected from the choices.

image

Shuffle : This method is passed an array or span of any type T and the order of items is randomized.

Let's see an example of each:

1. In Program.cs , add statements to access the shared Random instance, and then call its methods to generate random numbers, as shown in the following code:

string[] beatles = r.GetItems(

choices: new[] { "John", "Paul", "George", "Ringo" }, length: 10);

Write("Random ten beatles:"); foreach (string beatle in beatles)

{

Write($" {beatle}");

}

WriteLine(); r.Shuffle(beatles); Write("Shuffled beatles:");

foreach (string beatle in beatles)

{

Write($" {beatle}");

}

WriteLine();

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

Random ten beatles: Paul Paul John John John John Paul John George Ringo Shuffled beatles: George John Paul Paul John John John Ringo Paul John

Generating GUIDs‌

A GUID (globally unique identifier) is a 128-bit text string that represents a unique value for identification. As a developer, you will need to generate GUIDs when a unique reference is needed to identify information. Traditionally, database and computer systems may have used an incrementing integer value, but a GUID is more likely to avoid conflicts in multi- tasking systems.The System.Guid type is a value type ( struct ) that represents a GUID value. It has Parse and TryParse methods to take an existing GUID value represented as a string and convert it into the Guid type. It has a NewGuid method to generate a new value.Let's see how we can generate GUID values and output them:

1. In Program.cs , add statements to access the shared Random instance, and then call its methods to generate random numbers, as shown in the following code:

WriteLine($"Empty GUID: {Guid.Empty}."); Guid g = Guid.NewGuid(); WriteLine($"Random GUID: {g}.");

byte[] guidAsBytes = g.ToByteArray(); Write("GUID as byte array: ");

for (int i = 0; i < guidAsBytes.Length; i++) { Write($"{guidAsBytes[i]:X2} "); } WriteLine(); 1. Run the code and view the result, as shown in the following output: Empty GUID: 00000000-0000-0000-0000-000000000000. Random GUID: c7a11eea-45a5-4619-964a-a9cce1e4220c. GUID as byte array: EA 1E A1 C7 A5 45 19 46 96 4A A9 CC E1 E4 22 0C Working with text‌ One of the other most common types of data for variables is text. The most common types in .NET for working with text are shown in Table 8.2: Namespace Type Description System Char Storage for a single text character System String Storage for multiple text characters System.Text StringBuilder Efficiently manipulates strings System.Text.RegularExpressions Regex Efficiently pattern-matches strings Table 8.2: Common .NET types for working with text Getting the length of a string‌ Let's explore some common tasks when working with text; for example, sometimes you need to find out the length of a piece of text stored in a string variable: Use your preferred code editor to add a new Console App / console project named WorkingWithText to the Chapter08 solution. In the WorkingWithText project, in Program.cs , delete the existing statements and then add statements to define a variable to store the name of the city London, and then write its name and length to the console, as shown in the following code: string city = "London"; WriteLine($"{city} is {city.Length} characters long."); 1. Run the code and view the result, as shown in the following output: London is 6 characters long. Getting the characters of a string‌ The string class uses an array of char internally to store the text. It also has an indexer, which means that we can use the array syntax to read its characters. Array indexes start at zero, so the third character will be at index 2.Let's see this in action: 1. Add a statement to write the characters at the first and fourth positions in the string variable, as shown in the following code: WriteLine($"First char is {city[0]} and fourth is {city[3]}."); 1. Run the code and view the result, as shown in the following output: First char is L and fourth is d. Splitting a string‌ Sometimes, you need to split some text wherever there is a character, such as a comma: 1. Add statements to define a single string variable containing comma-separated city names, then use the Split method and specify that you want to treat commas as the separator, and then enumerate the returned array of string values, as shown in the following code: string cities = "Paris,Tehran,Chennai,Sydney,New York,Medellín"; string[] citiesArray = cities.Split(','); WriteLine($"There are {citiesArray.Length} items in the array:"); foreach (string item in citiesArray) { WriteLine($" {item}"); } 1. Run the code and view the result, as shown in the following output: There are 6 items in the array: Paris Tehran Chennai Sydney New York Medellín Later in this chapter, you will learn how to handle more complex string-splitting scenarios using a regular expression. Getting part of a string‌ Sometimes, you need to get part of some text. The IndexOf method has nine overloads that return the index position of a specified char or string within a string . The Substring method has two overloads, as shown in the following list: image Substring(startIndex, length) : Returns part of a string starting at startIndex and containing the next length characters image Substring(startIndex) : Returns part of a string starting at startIndex and containing all characters up to the end of the string Let's explore a simple example: 1. Add statements to store a person's full name in a string variable with a space character between the first and last names, find the position of the space, and then extract the first name and last name as two parts so that they can be recombined in a different order, as shown in the following code: string fullName = "Alan Shore"; int indexOfTheSpace = fullName.IndexOf(' '); string firstName = fullName.Substring( startIndex: 0, length: indexOfTheSpace); string lastName = fullName.Substring( startIndex: indexOfTheSpace + 1); WriteLine($"Original: {fullName}"); WriteLine($"Swapped: {lastName}, {firstName}"); 1. Run the code and view the result, as shown in the following output: Original: Alan Shore Swapped: Shore, Alan If the format of the initial full name was different, for example, "LastName, FirstName" , then the code would need to be different. As an optional exercise, try writing some statements that would change the input "Shore, Alan" into "Alan Shore" . Checking a string for content‌ Sometimes, you need to check whether a piece of text starts or ends with some characters or contains some characters. You can achieve this with methods named StartsWith , EndsWith , and Contains : 1. Add statements to store a string value and then check if it starts with or contains a couple of different string values, as shown in the following code: string company = "Microsoft"; WriteLine($"Text: {company}"); WriteLine("Starts with M: {0}, contains an N: {1}", arg0: company.StartsWith("M"), arg1: company.Contains("N")); 1. Run the code and view the result, as shown in the following output: Text: Microsoft Starts with M: True, contains an N: False Comparing string values‌ Two common tasks with string values are sorting (aka collating) and comparing. For example, when a user enters their username or password, you need to compare what they entered with what is stored.The string class implements the IComparable interface meaning that you can easily compare two string values using the CompareTo instance method and it will return -1 , 0 , or 1 depending on if the value is "less than," "equal to," or "greater than" the other. You saw an example of this when you implemented the IComparable interface for the Person class in Chapter 6, Implementing Interfaces and Inheriting Classes.But the lower or upper casing of characters can affect ordering, and the ordering rules for text are culture dependent. For example, double-L is treated as a single character in traditional Spanish, as shown in Table 8.3: Culture Description Example string values Spanish In 1994, the Royal Spanish Academy issued a Modern: llegar comes before lugar . new alphabetization rule to treat LL and CH Traditional: llegar comes after lugar . as Latin alphabetic characters instead of separate individual characters. Swedish In 2006, the Swedish Academy issued a new rule. Before 2006, V and W were the same character. Since 2006, they are treated as separate characters. German Phonebook ordering is different than dictionary ordering, for example, umlauts are sorted as combinations of letters. German The character ß is sorted as SS . This is a common issue with addresses since the word for street is Straße . Swedish words mostly only use V. Loanwords (words taken from other languages) that contain W can now keep those Ws instead of replacing the Ws with Vs. Müller and Mueller in phonebook ordering are the same name. Straße and Strasse have the same meaning. Table 8.3: Examples of ordering rules in European languages For consistency and performance, you sometimes want to make comparisons in a culture- invariant way. It is therefore better to use the static method Compare .Let's see some examples: 1. At the top of Program.cs , import the namespace for working with cultures and enable special characters like the Euro currency symbol, as shown in the following code: using System.Globalization; // To use CultureInfo. OutputEncoding = System.Text.Encoding.UTF8; // Enable Euro symbol. 1. In Program.cs , define some text variables and compare them in different cultures, as shown in the following code: CultureInfo.CurrentCulture = CultureInfo.GetCultureInfo("en-US"); string text1 = "Mark"; string text2 = "MARK"; WriteLine($"text1: {text1}, text2: {text2}"); WriteLine("Compare: {0}.", string.Compare(text1, text2)); WriteLine("Compare (ignoreCase): {0}.", string.Compare(text1, text2, ignoreCase: true)); WriteLine("Compare (InvariantCultureIgnoreCase): {0}.", string.Compare(text1, text2, StringComparison.InvariantCultureIgnoreCase)); 1. Run the code, view the result, and note that a lowercase "a" is "less than" ( -1 ) an upper case "A," so the comparison returns -1. But we can either set an option to ignore case, or even better, do a culture- and case-invariant comparison to treat the two string values as equal ( 0 ), as shown in the following output: text1: Mark, text2: MARK Compare: -1. Compare (ignoreCase): 0. Compare (InvariantCultureIgnoreCase): 0. More Information: You can learn more about string comparisons at the following link: https://learn.microsoft.com/en-us/globalization/locale/sorting-and-string-comparison. Joining, formatting, and other string members‌ There are many other string members, as shown in Table 8.4: Member Description Trim , TrimStart , TrimEnd These methods trim whitespace characters such as space, tab, and carriage return from the start and/or end. ToUpper , ToLower These convert all the characters into uppercase or lowercase. Insert , Remove These methods insert or remove some text. Replace This replaces some text with other text. string.Empty This can be used instead of allocating memory each time you use a literal string value using an empty pair of double quotes ( "" ). string.Concat This concatenates two string variables. The + operator does the equivalent when used between string operands. string.Join This concatenates one or more string variables with a character in between each one. string.IsNullOrEmpty This checks whether a string variable is null or empty. string.IsNullOrWhiteSpace This checks whether a string variable is null or whitespace; that is, a mix of any number of horizontal and vertical spacing characters, for example, tab, space, carriage return, line feed, and so on. string.Format An alternative method to string interpolation for outputting formatted string values, which uses positioned instead of named parameters. Table 8.4: Joining, formatting, and other string members Some of the preceding methods are static methods. This means that the method can only be called from the type, not from a variable instance. In the preceding table, I indicated the static methods by prefixing them with string. , as in string.Format . Let's explore some of these methods: 1. Add statements to take an array of string values and combine them back together into a single string variable with separators using the Join method, as shown in the following code: string recombined = string.Join(" => ", citiesArray); WriteLine(recombined);

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

Paris => Tehran => Chennai => Sydney => New York => Medellín

1. Add statements to use positioned parameters and interpolated string formatting syntax to output the same three variables twice, as shown in the following code:

string fruit = "Apples"; decimal price = 0.39M; DateTime when = DateTime.Today;

WriteLine($"Interpolated: {fruit} cost {price:C} on {when:dddd}."); WriteLine(string.Format("string.Format: {0} cost {1:C} on {2:dddd}.",

arg0: fruit, arg1: price, arg2: when));

Some code editors like JetBrains Rider will warn you about boxing operations. These are slow but not a problem in this scenario. To avoid boxing, call ToString on price and when .

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

Interpolated: Apples cost $0.39 on Friday. string.Format: Apples cost $0.39 on Friday.

Note that we could have simplified the second statement because Console.WriteLine supports the same format codes as string.Format , as shown in the following code:

WriteLine("WriteLine: {0} cost {1:C} on {2:dddd}.", arg0: fruit, arg1: price, arg2: when);

Building strings efficiently‌

You can concatenate two strings to make a new string using the String.Concat method or simply by using the + operator. But both choices are bad practice when combining more than a few values because .NET must create a completely new string in memory.This might not be noticeable if you are only adding two string values, but if you concatenate inside a loop with many iterations, it can have a significant negative impact on performance and memory use. You can concatenate string variables more efficiently using the StringBuilder type.I have written an online-only section for the companion book, Apps and Services with .NET 8, about performance benchmarking using string concatenations as the main example. You can optionally complete the section and its practical coding tasks at the following link: https://github.com/markjprice/apps-services-net8/blob/main/docs/ch01-benchmarking.md.

More Information: You can see examples of using StringBuilder at the following link: https://learn.microsoft.com/en-us/dotnet/api/system.text.stringbuilder#examples.

Pattern matching with regular expressions‌

Regular expressions are useful for validating input from the user. They are very powerful and can get very complicated. Almost all programming languages have support for regular expressions and use a common set of special characters to define them.Let's try out some example regular expressions:

Use your preferred code editor to add a new Console App / console project named

WorkingWithRegularExpressions to the Chapter08 solution.

In Program.cs , delete the existing statements and then import the following namespace:

using System.Text.RegularExpressions; // To use Regex.

Checking for digits entered as text‌

We will start by implementing the common example of validating number input:

1. In Program.cs , add statements to prompt the user to enter their age and then check that it is valid using a regular expression that looks for a digit character, as shown in the following code:

Write("Enter your age: ");

string input = ReadLine()!; // Null-forgiving operator. Regex ageChecker = new(@"\d"); WriteLine(ageChecker.IsMatch(input) ? "Thank you!" :

$"This is not a valid age: {input}");

Note the following about the code:

image

The @ character switches off the ability to use escape characters in the string . Escape characters are prefixed with a backslash. For example, \t means a tab and \n means a new line. When writing regular expressions, we need to disable this feature. To paraphrase the television show The West Wing, "Let backslash be backslash."

image

Once escape characters are disabled with @ , then they can be interpreted by a regular expression. For example, \d means digit. You will learn about more regular expression symbols that are prefixed with a backslash later in this topic.

1. Run the code, enter a whole number such as 34 for the age, and view the result, as shown in the following output:

Enter your age: 34 Thank you!

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

Enter your age: carrots

This is not a valid age: carrots

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

Enter your age: bob30smith Thank you!

The regular expression we used is \d , which means one digit. However, it does not specify what can be entered before and after that one digit. This regular expression could be described in English as "Enter any characters you want as long as you enter at least one digit character."In regular expressions, you indicate the start of some input with the caret

^ symbol and the end of some input with the dollar $ symbol. Let's use these symbols to indicate that we expect nothing else between the start and end of the input except for a digit.

1. Add a ^ and a $ to change the regular expression to ^\d$ , as shown highlighted in the following code:

Regex ageChecker = new(@"^\d$");

Run the code again and note that it rejects any input except a single digit.

Add a + after the \d expression to modify the meaning to one or more digits, as shown highlighted in the following code:

Regex ageChecker = new(@"^\d+$");

1. Run the code again and note the regular expression only allows zero or positive whole numbers of any length.

Regular expression performance improvements‌

The .NET types for working with regular expressions are used throughout the .NET platform and many of the apps built with it. As such, they have a significant impact on performance. But until now, they have not received much optimization attention from Microsoft.With .NET 5 and later, the types in the System.Text.RegularExpressions namespace have rewritten implementations to squeeze out maximum performance. Common regular expression benchmarks using methods like IsMatch are now five times faster. And the best thing is, you do not have to change your code to get the benefits!With .NET 7 and later, the IsMatch method of the Regex class now has an overload for a ReadOnlySpan as its input, which gives even better performance.

Understanding the syntax of a regular expression‌

Some common symbols that you can use in regular expressions are shown in Table 8.5:

Symbol

Meaning

Symbol

Meaning

^

Start of input

$

End of input

\d

A single digit

\D

A single non -digit

\s

Whitespace

\S

Non -whitespace

\w

Word characters

\W

Non -word characters

[A-Za-z0-9] Range(s) of characters \^ ^ (caret) character

[aeiou] Set of characters [^aeiou] Not in a set of characters

. Any single character \. . (dot) character Table 8.5: Common regular expression symbols

In addition, some common regular expression quantifiers that affect the previous symbols in a regular expression are shown in Table 8.6:

Symbol Meaning Symbol Meaning

+ One or more ? One or none

{3} Exactly three {3,5} Three to five

{3,} At least three {,3} Up to three

Table 8.6: Common regular expression quantifiers

Examples of regular expressions‌

Some examples of regular expressions with a description of their meaning are shown in Table 8.7:

Expression Meaning

\d A single digit somewhere in the input

a The character “a” somewhere in the input

Bob The word “Bob” somewhere in the input

^Bob The word “Bob” at the start of the input

Bob$ The word “Bob” at the end of the input

^\d{2}$ Exactly two digits

^[0-9]{2}$ Exactly two digits

^[A-Z]{4,}$ At least four uppercase English letters in the ASCII character set only

^[A-Za-z]{4,}$ At least four upper or lowercase English letters in the ASCII character set only

^[A-Z]{2}\d{3}$ Two uppercase English letters in the ASCII character set and three digits only

^[A-Za-z\u00c0-\u017e]+$

At least one uppercase or lowercase English letter in the ASCII character set or European letters in the Unicode character set, as shown in the following list:

ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝ

Þßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿıŒœŠšŸŽž

^d.g$ The letter d , then any character, and then the letter g , so it would match both dig and dog or any single character between the d and g

^d\.g$ The letter d , then a dot . , and then the letter g , so it would match d.g only

Table 8.7: Examples of regular expressions with descriptions of their meaning

Good Practice: Use regular expressions to validate input from the user. The same regular expressions can be reused in other languages such as JavaScript and Python.

Splitting a complex comma-separated string‌

Earlier in this chapter, you learned how to split a simple comma-separated string variable. But what about the following example of film titles?

"Monsters, Inc.","I, Tonya","Lock, Stock and Two Smoking Barrels"

The string value uses double quotes around each film title. We can use these to identify whether we need to split on a comma (or not). The Split method is not powerful enough, so we can use a regular expression instead.

Good Practice: You can read a fuller explanation in the Stack Overflow article that inspired this task at the following link: https://stackoverflow.com/questions/18144431/regex-to-split-a-csv.

To include double quotes inside a string value, we prefix them with a backslash, or we could use the C# 11 raw string literal feature in C# 11 or later:

1. Add statements to store a complex comma-separated string variable, and then split it in a dumb way using the Split method, as shown in the following code:

// C# 1 to 10: Use escaped double-quote characters \"

// string films = "\"Monsters, Inc.\",\"I, Tonya\",\"Lock, Stock and Two Smoking Barrels\"";

// C# 11 or later: Use """ to start and end a raw string literal string films = """

"Monsters, Inc.","I, Tonya","Lock, Stock and Two Smoking Barrels" """;

WriteLine($"Films to split: {films}"); string[] filmsDumb = films.Split(',');

WriteLine("Splitting with string.Split method:"); foreach (string film in filmsDumb)

{

WriteLine($" {film}");

}

1. Add statements to define a regular expression to split and write the film titles in a smart way, as shown in the following code:

Regex csv = new( "(?:^|,)(?=[^\"]|(\")?)\"?((?(1)[^\"]*|[^,\"]*))\"?(?=,|$)");

MatchCollection filmsSmart = csv.Matches(films); WriteLine("Splitting with regular expression:"); foreach (Match film in filmsSmart)

{

WriteLine($" {film.Groups[2].Value}");

}

In a later section, you will see how you can get a source generator to auto-generate XML comments for a regular expression to explain how it works. This is really useful for regular expressions that you might have copied from a website.

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

Splitting with string.Split method: "Monsters

Inc." "I

Tonya"

"Lock

Stock and Two Smoking Barrels" Splitting with regular expression:

Monsters, Inc.

I, Tonya

Lock, Stock and Two Smoking Barrels

Activating regular expression syntax coloring‌

If you use Visual Studio 2022 as your code editor, then you probably noticed that when passing a string value to the Regex constructor, you see color syntax highlighting, as shown in Figure 8.1:

image

Figure 8.1: Regular expression color syntax highlighting when using the Regex constructor

This would be a good time to remind print book readers who will only see the preceding figure in grayscale that they can see all figures in full color as a PDF at the following link: https://static.packt-cdn.com/downloads/???_ColorImages.pdf

Why does this string get syntax coloring for regular expressions when most string values do not? Let's find out:

1. Right-click on the new constructor, select Go To Implementation, and note the string parameter named pattern is decorated with an attribute named StringSyntax that has the string constant Regex value passed to it, as shown highlighted in the following code:

public Regex([StringSyntax(StringSyntaxAttribute.Regex)] string pattern) : this(pattern, culture: null)

{

}

1. Right-click on the StringSyntax attribute, select Go To Implementation, and note there are 12 recognized string syntax formats that you can choose from as well as Regex , as shown in the following partial code:

[AttributeUsage(AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Parameter, public sealed class StringSyntaxAttribute : Attribute

{

public const string CompositeFormat = "CompositeFormat"; public const string DateOnlyFormat = "DateOnlyFormat"; public const string DateTimeFormat = "DateTimeFormat"; public const string EnumFormat = "EnumFormat";

public const string GuidFormat = "GuidFormat"; public const string Json = "Json";

public const string NumericFormat = "NumericFormat"; public const string Regex = "Regex";

public const string TimeOnlyFormat = "TimeOnlyFormat"; public const string TimeSpanFormat = "TimeSpanFormat"; public const string Uri = "Uri";

public const string Xml = "Xml";

…

}

1. In the WorkingWithRegularExpressions project, add a new class file named Program.Strings.cs , delete any existing statements, and then define some string constants in a partial Program class, as shown in the following code:

partial class Program

{

private const string DigitsOnlyText = @"^\d+$"; private const string CommaSeparatorText =

"(?:^|,)(?=[^\"]|(\")?)\"?((?(1)[^\"]*|[^,\"]*))\"?(?=,|$)";

}

Note that the two string constants do not have any color syntax highlighting yet.

1. In Program.cs , replace the literal string with the string constant for the digits-only regular expression, as shown highlighted in the following code:

Regex ageChecker = new(DigitsOnlyText);

1. In Program.cs , replace the literal string with the string constant for the comma- separator regular expression, as shown highlighted in the following code:

Regex csv = new(CommaSeparatorText);

Run the WorkingWithRegularExpressions project and confirm that the regular expression behavior is as before.

In Program.Strings.cs , import the namespace for the [StringSyntax] attribute and then decorate both string constants with it, as shown highlighted in the following code:

using System.Diagnostics.CodeAnalysis; // To use [StringSyntax]. partial class Program

{

[StringSyntax(StringSyntaxAttribute.Regex)] private const string DigitsOnlyText = @"^\d+$"; [StringSyntax(StringSyntaxAttribute.Regex)] private const string CommaSeparatorText =

"(?:^|,)(?=[^\"]|(\")?)\"?((?(1)[^\"]*|[^,\"]*))\"?(?=,|$)";

}

1. In Program.Strings.cs , add another string constant for formatting a date, as shown in the following code:

[StringSyntax(StringSyntaxAttribute.DateTimeFormat)] private const string FullDateTime = "";

Click inside the empty string, type the letter d , and note the IntelliSense, as shown in Figure 8.2:

image

Figure 8.2: IntelliSense activated due to the StringSyntax attribute

Finish entering the date format and as you type, note the IntelliSense:

dddd, d MMMM yyyy .

Inside, at the end of the DigitsOnlyText string literal, enter a \ , and note the IntelliSense to help you write a valid regular expression, as shown in Figure 8.3:

image

Figure 8.3: IntelliSense for writing a regular expression

Delete the \ that you entered to trigger IntelliSense.

The [StringSyntax] attribute is a new feature introduced in .NET 7. It depends on your code editor whether it is recognized. The .NET BCL has more than 350 parameters, properties, and fields that are now decorated with this attribute.

Improving regular expression performance with source generators‌

When you pass a string literal or string constant to the constructor of Regex , the class parses the string and transforms it into an internal tree structure that represents the expression in an optimized way that can be executed efficiently by a regular expression interpreter.You can also compile regular expressions by specifying a RegexOptions , as in the following code:

Regex ageChecker = new(DigitsOnlyText, RegexOptions.Compiled);

Unfortunately, compiling has the negative effect of slowing down the initial creation of the regular expression. After creating the tree structure that would then be executed by the interpreter, the compiler then must convert the tree into IL code, and then that IL code needs to be JIT compiled into native code. If you’re only running the regular expression a few times, it is not worth compiling it, which is why it is not the default behavior. If you’re running the regular expression more than a few times, for example, because it will be used to validate the URL for every incoming HTTP request to a website, then it is worth compiling. But even then, you should only use compilation if you must use .NET 6 or earlier..NET 7 introduced a source generator for regular expressions that recognizes if you decorate a partial method that returns Regex with the [GeneratedRegex] attribute. It generates an implementation of that method that implements the logic for the regular expression.Let's see it in action:

1. In the WorkingWithRegularExpressions project, add a new class file named Program.Regexs.cs and modify its content to define some partial methods, as shown in the following code:

using System.Text.RegularExpressions; // To use [GeneratedRegex]. partial class Program

{

[GeneratedRegex(DigitsOnlyText, RegexOptions.IgnoreCase)] private static partial Regex DigitsOnly(); [GeneratedRegex(CommaSeparatorText, RegexOptions.IgnoreCase)] private static partial Regex CommaSeparator();

}

1. In Program.cs , replace the new constructor with a call to the partial method that returns the digits-only regular expression, as shown highlighted in the following code:

Regex ageChecker = DigitsOnly();

1. In Program.cs , replace the new constructor with a call to the partial method that returns the comma-separator regular expression, as shown highlighted in the following code:

Regex csv = CommaSeparator();

Hover your mouse pointer over the partial methods and note the tooltip describes the behavior of the regular expression, as shown in Figure 8.4:

image

Figure 8.4: Tooltip for a partial method shows a description of the regular expression

Right-click the DigitsOnly partial method, select Go To Definition, and note that you can review the implementation of the auto-generated partial methods, as shown in Figure 8.5:

image

Figure 8.5: The auto-generated source code for the regular expression

Run the project and confirm that the functionality is the same as before.

You can learn more about the improvements to regular expressions with .NET 7 at the following link: https://devblogs.microsoft.com/dotnet/regular-expression-improvements- in-dotnet-7.

Storing multiple objects in collections‌

Another of the most common types of data is collections. If you need to store multiple values in a variable, then you can use a collection.A collection is a data structure in memory that can manage multiple items in different ways, although all collections have some shared functionality.The most common types in .NET for working with collections are shown in Table 8.8:

Namespace Example type(s) Description

System .Collections IEnumerable ,

IEnumerable System .Collections .Generic List ,

Dictionary ,

Queue ,

Stack

System .Collections .Concurrent BlockingCollection ,

ConcurrentDictionary ,

ConcurrentQueue System .Collections .Immutable ImmutableArray ,

ImmutableDictionary ,

ImmutableList ,

ImmutableQueue

Table 8.8: Common .NET collection types

Common features of all collections‌

Interfaces and base classes used by collections.

Introduced in C# 2.0 with .NET Framework 2.0. These collections allow you to specify the type you want to store using a generic type parameter (which is safer, faster, and more efficient).

These collections are safe to use in multithreaded scenarios.

Designed for scenarios where the contents of the original collection will never change, although they can create modified collections as a new instance.

All collections implement the ICollection interface; this means that they must have a Count property to tell you how many objects are in them, and three other members, as shown in the following code:

namespace System.Collections;

public interface ICollection : IEnumerable

{

int Count { get; }

bool IsSynchronized { get; } object SyncRoot { get; }

void CopyTo(Array array, int index);

}

For example, if we had a collection named passengers , we could do this:

int howMany = passengers.Count;

As you have probably surmised, CopyTo copies the collection to an array. IsSynchronized and

SyncRoot are used in multithreading scenarios, so I do not cover them in this book.All

collections implement the IEnumerable interface, which means that they can be iterated using the foreach statement. They must have a GetEnumerator method that returns an object that implements IEnumerator ; this means that the returned object must have MoveNext and Reset methods for navigating through the collection and a Current property containing the current item in the collection, as shown in the following code:

namespace System.Collections; public interface IEnumerable

{

IEnumerator GetEnumerator();

}

public interface IEnumerator

{

object Current { get; } bool MoveNext();

void Reset();

}

For example, to perform an action on each object in the passengers collection, we could write the following code:

foreach (Passenger p in passengers)

{

// Perform an action on each passenger.

}

As well as the object -based collection interface, there is also a generic collection interface, where the generic type defines the type stored in the collection. It has additional members like IsReadOnly , Add , Clear , Contains , and Remove , as shown in the following code:

namespace System.Collections.Generic;

public interface ICollection : IEnumerable, IEnumerable

{

int Count { get; }

bool IsReadOnly { get; } void Add(T item);

void Clear();

bool Contains(T item);

void CopyTo(T[] array, int index); bool Remove(T item);

}

Working with lists‌

Lists, that is, a type that implements IList , are ordered collections, with an int

index to show the position of an item within the list, as shown in the following code:

namespace System.Collections.Generic; [DefaultMember("Item")] // aka "this" indexer.

public interface IList : ICollection, IEnumerable, IEnumerable

{

T this[int index] { get; set; } int IndexOf(T item);

void Insert(int index, T item); void RemoveAt(int index);

}

The [DefaultMember] attribute allows you to specify which member is accessed by default when no member name is specified. To make IndexOf the default member, you would use [DefaultMember("IndexOf")] . To specify the indexer, you use [DefaultMember("Item")] .

IList derives from ICollection , so it has a Count property, and an Add method to put an item at the end of the collection, as well as an Insert method to put an item in the

list at a specified position, and RemoveAt to remove an item at a specified position.Lists are a good choice when you want to manually control the order of items in a collection. Each item in a list has a unique index (or position) that is automatically assigned. Items can be any type defined by T and items can be duplicated. Indexes are int types and start from 0 , so the first item in a list is at index 0 , as shown in Table 8.9:

Index Item

London

Paris

London

Sydney

Table 8.9: Cities in a list with indexes

If a new item (for example, Santiago) is inserted between London and Sydney, then the index of Sydney is automatically incremented. Therefore, you must be aware that an item’s index can change after inserting or removing items, as shown in Table 8.10:

Index Item

London

Paris

London

Santiago

Sydney

Table 8.10: Cities list after an item is inserted

Good Practice: Some developers can get into a poor habit of using List and other collections when an array would be better. Use arrays instead of collections if the data will not change size after instantiation. You should also use lists initially while you are adding and removing items, but then convert them into an array once you are done with manipulating the items.

Let's explore lists:

Use your preferred code editor to add a new Console App / console project named

WorkingWithCollections to the Chapter08 solution.

Add a new class file named Program.Helpers.cs .

In Program.Helpers.cs , define a partial Program class with a generic method to output a collection of T values with a title, as shown in the following code:

partial class Program

{

private static void OutputCollection( string title, IEnumerable collection)

{

WriteLine($"{title}:"); foreach (T item in collection)

{

WriteLine($" {item}");

}

}

}

1. In Program.cs , delete the existing statements and then add some statements to illustrate some of the common ways of defining and working with lists, as shown in the following code:

// Simple syntax for creating a list and adding three items. List cities = new();

cities.Add("London"); cities.Add("Paris"); cities.Add("Milan");

/* Alternative syntax that is converted by the compiler into the three Add method calls above.

List cities = new()

{ "London", "Paris", "Milan" }; */

/* Alternative syntax that passes an array of string values to AddRange method.

List cities = new();

cities.AddRange(new[] { "London", "Paris", "Milan" }); */ OutputCollection("Initial list", cities);

WriteLine($"The first city is {cities[0]}."); WriteLine($"The last city is {cities[cities.Count - 1]}."); cities.Insert(0, "Sydney");

OutputCollection("After inserting Sydney at index 0", cities); cities.RemoveAt(1);

cities.Remove("Milan");

OutputCollection("After removing two cities", cities);

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

Initial list: London Paris

Milan

The first city is London. The last city is Milan.

After inserting Sydney at index 0: Sydney

London Paris Milan

After removing two cities: Sydney

Paris

Working with dictionaries‌

Dictionaries are a good choice when each value (or object) has a unique sub-value (or a made-up value) that can be used as a key to quickly find a value in the collection later. The key must be unique. For example, if you are storing a list of people, you could choose to use a government-issued identity number as the key. Dictionaries are called hashmaps in other languages like Python and Java.Think of the key as being like an index entry in a real-world dictionary. It allows you to quickly find the definition of a word because the

words (in other words, keys) are kept sorted; if we know we're looking for the definition of manatee, we will jump to the middle of the dictionary to start looking, because the letter m is in the middle of the alphabet.Dictionaries in programming are similarly smart when looking something up. They must implement the interface IDictionary , as shown in the following code:

namespace System.Collections.Generic; [DefaultMember("Item")] // aka "this" indexer. public interface IDictionary

: ICollection>, IEnumerable>, IEnumerable

{

TValue this[TKey key] { get; set; } ICollection Keys { get; } ICollection Values { get; } void Add(TKey key, TValue value); bool ContainsKey(TKey key);

bool Remove(TKey key);

bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value);

}

Items in a dictionary are instances of the struct , aka the value type,

KeyValuePair , where TKey is the type of the key and TValue is the type of the value, as shown in the following code:

namespace System.Collections.Generic;

public readonly struct KeyValuePair

{

public KeyValuePair(TKey key, TValue value); public TKey Key { get; }

public TValue Value { get; } [EditorBrowsable(EditorBrowsableState.Never)]

public void Deconstruct(out TKey key, out TValue value); public override string ToString();

}

An example Dictionary uses a string as the key and a Person instance as the value. Dictionary uses string values for both, as shown in Table 8.11:

Key Value

BSA Bob Smith

MW Max Williams BSB Bob Smith

AM Amir Mohammed

Table 8.11: Dictionary with keys and values Let's explore dictionaries:

1. At the top of Program.cs , define an alias for the Dictionary class where

TKey and TValue are both string , as shown in the following code:

// Define an alias for a dictionary with string key and string value.

using StringDictionary = System.Collections.Generic.Dictionary;

1. In Program.cs , add some statements to illustrate some of the common ways of working with dictionaries, for example, looking up word definitions, as shown in the following code:

// Declare a dictionary without the alias.

// Dictionary keywords = new();

// Use the alias to declare the dictionary. StringDictionary keywords = new();

// Add using named parameters.

keywords.Add(key: "int", value: "32-bit integer data type");

// Add using positional parameters. keywords.Add("long", "64-bit integer data type");

keywords.Add("float", "Single precision floating point number");

/* Alternative syntax; compiler converts this to calls to Add method. Dictionary keywords = new()

{

{ "int", "32-bit integer data type" },

{ "long", "64-bit integer data type" },

{ "float", "Single precision floating point number" },

}; */

/* Alternative syntax; compiler converts this to calls to Add method. Dictionary keywords = new()

{

["int"] = "32-bit integer data type", ["long"] = "64-bit integer data type",

["float"] = "Single precision floating point number",

}; */

OutputCollection("Dictionary keys", keywords.Keys); OutputCollection("Dictionary values", keywords.Values); WriteLine("Keywords and their definitions:");

foreach (KeyValuePair item in keywords)

{

WriteLine($" {item.Key}: {item.Value}");

}

// Look up a value using a key. string key = "long";

WriteLine($"The definition of {key} is {keywords[key]}.");

The trailing commas after the third item is added to the dictionary are optional and the compiler will not complain about them. This is convenient so that you can change the order of the three items without having to delete and add commas in the right places.

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

Dictionary keys: int

long float

Dictionary values:

32-bit integer data type 64-bit integer data type

Single precision floating point number Keywords and their definitions:

int: 32-bit integer data type long: 64-bit integer data type

float: Single precision floating point number The definition of long is 64-bit integer data type

In Chapter 11, Querying and Manipulating Data Using LINQ, you will learn how to create dictionaries and lookups from existing data sources like tables in a database using LINQ methods like ToDictionary and ToLookup . This is much more common than manually adding items to a dictionary as shown in this section.

Sets, stacks, and queues‌

Sets are a good choice when you want to perform set operations between two collections. For example, you may have two collections of city names, and you want to know which names appear in both sets (known as the intersect between the sets). Items in a set must be unique.

Common set methods are shown in Table 8.12:

Method Description

Add If the item does not already exist in the set, then it is added. Returns

true if the item was added, and false if it was already in the set.

ExceptWith Removes the items in the set passed as the parameter from the set.

IntersectWith Removes the items not in the set passed as the parameter and in the set.

IsProperSubsetOf ,

IsProperSupersetOf

, IsSubsetOf ,

IsSupersetOf

A subset is a set whose items are all in the other set. A proper subset is a set whose items are all in the other set but there is at least one item in the other set that is not in the set. A superset is a set that contains all the items in the other set. A proper superset is a set that contains all the items in the other set and at least one more not in the other set.

Overlaps The set and the other set share at least one common item.

SetEquals The set and the other set contain exactly the same items.

SymmetricExceptWith Removes the items not in the set passed as the parameter from the set and adds any that are missing.

UnionWith Adds any items in the set passed as the parameter to the set that are not already in the set.

Table 8.12: Set methods

Let's explore example code for sets:

1. In Program.cs , add some statements to add items to a set, as shown in the following code:

HashSet names = new(); foreach (string name in

new[] { "Adam", "Barry", "Charlie", "Barry" })

{

bool added = names.Add(name); WriteLine($"{name} was added: {added}.");

}

WriteLine($"names set: {string.Join(',', names)}.");

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

Adam was added: True.

Barry was added: True.

Charlie was added: True.

Barry was added: False.

names set: Adam,Barry,Charlie.

You will see more set operations in Chapter 11, Querying and Manipulating Data Using LINQ.Stacks are a good choice when you want to implement last-in, first-out (LIFO) behavior. With a stack, you can only directly access or remove the one item at the top of the stack, although you can enumerate to read through the whole stack of items. You cannot, for example, directly access the second item in a stack.For example, word processors use a stack to remember the sequence of actions you have recently performed, and then when you press Ctrl + Z, it will undo the last action in the stack, and then the next-to-last action, and so on.Queues are a good choice when you want to implement the first-in, first-out (FIFO) behavior. With a queue, you can only directly access or remove the item at the front of the queue, although you can enumerate to read through the whole queue of items. You cannot, for example, directly access the second item in a queue.For example, background processes use a queue to process work items in the order that they arrive, just like people standing in line at the post office..NET 6 introduced the PriorityQueue , where each item in the queue has a priority value assigned, as well as its position in the queue.Let's explore example code for queues:

1. In Program.cs , add some statements to illustrate some of the common ways of working with queues, for example, handling customers in a queue for coffee, as shown in the following code:

Queue coffee = new(); coffee.Enqueue("Damir"); // Front of the queue. coffee.Enqueue("Andrea"); coffee.Enqueue("Ronald"); coffee.Enqueue("Amin"); coffee.Enqueue("Irina"); // Back of the queue.

OutputCollection("Initial queue from front to back", coffee);

// Server handles next person in queue. string served = coffee.Dequeue(); WriteLine($"Served: {served}.");

// Server handles next person in queue. served = coffee.Dequeue(); WriteLine($"Served: {served}.");

OutputCollection("Current queue from front to back", coffee); WriteLine($"{coffee.Peek()} is next in line."); OutputCollection("Current queue from front to back", coffee);

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

Initial queue from front to back: Damir

Andrea Ronald Amin Irina

Served: Damir.

Served: Andrea.

Current queue from front to back: Ronald

Amin Irina

Ronald is next in line.

Current queue from front to back: Ronald

Amin Irina

1. In Program.Helpers.cs , in the partial Program class, add a static method named

OutputPQ , as shown in the following code:

private static void OutputPQ(string title, IEnumerable<(TElement Element, TPriority Priority)> collection)

{

WriteLine($"{title}:");

foreach ((TElement, TPriority) item in collection)

{

WriteLine($" {item.Item1}: {item.Item2}");

}

}

Note that the OutputPQ method is generic. You can specify the two types used in the tuples that are passed in as collection .

1. In Program.cs , add some statements to illustrate some of the common ways of working with priority queues, as shown in the following code:

PriorityQueue vaccine = new();

// Add some people.

// 1 = High priority people in their 70s or poor health.

// 2 = Medium priority e.g. middle-aged.

// 3 = Low priority e.g. teens and twenties. vaccine.Enqueue("Pamela", 1);

vaccine.Enqueue("Rebecca", 3);

vaccine.Enqueue("Juliet", 2);

vaccine.Enqueue("Ian", 1);

OutputPQ("Current queue for vaccination", vaccine.UnorderedItems); WriteLine($"{vaccine.Dequeue()} has been vaccinated."); WriteLine($"{vaccine.Dequeue()} has been vaccinated."); OutputPQ("Current queue for vaccination", vaccine.UnorderedItems); WriteLine($"{vaccine.Dequeue()} has been vaccinated."); WriteLine("Adding Mark to queue with priority 2."); vaccine.Enqueue("Mark", 2);

WriteLine($"{vaccine.Peek()} will be next to be vaccinated."); OutputPQ("Current queue for vaccination", vaccine.UnorderedItems);

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

Current queue for vaccination: Pamela: 1

Rebecca: 3

Juliet: 2

Ian: 1

Pamela has been vaccinated. Ian has been vaccinated.

Current queue for vaccination: Juliet: 2

Rebecca: 3

Juliet has been vaccinated.

Adding Mark to queue with priority 2 Mark will be next to be vaccinated. Current queue for vaccination:

Mark: 2

Rebecca: 3

Collection add and remove methods‌

Each collection has a different set of methods to "add" and "remove" items, as shown in

Table 8.13:

Collection "Add" "Remove" Description

methods methods

List Add ,

Insert

Remove

,

Lists are ordered so items have an integer index position. Add

will add a new item at the end of the list. Insert will add a

RemoveAt new item at the index position specified.

Dictionary Add Remove Dictionaries are not ordered so items do not have integer index

positions. You can check if a key has been used by calling the

ContainsKey method.

Stack Push Pop Stacks always add a new item at the top of the stack using the

Push method. The first item is at the bottom. Items are always removed from the top of the stack using the Pop method. Call the Peek method to see this value without removing it. Stacks are LIFO.

Queue Enqueue Dequeue Queues always add a new item at the end of the queue using the

Enqueue method. The first item is at the front of the queue. Items are always removed from the front of the queue using the Dequeue method. Call the Peek method to see this value without removing it. Queues are FIFO.

Table 8.13: Collection "add" and "remove" methods

Sorting collections‌

A List class can be sorted by manually calling its Sort method (but remember that the indexes of each item will change). Manually sorting a list of string values or other built- in types will work without extra effort on your part, but if you create a collection of your own type, then that type must implement an interface named IComparable . You learned how to do this in Chapter 6, Implementing Interfaces and Inheriting Classes.A Stack or Queue collection cannot be sorted because you wouldn't usually want that functionality; for example, you would probably never sort a queue of guests checking into a hotel. But sometimes, you might want to sort a dictionary or a set.Sometimes it would be useful to have an automatically sorted collection, that is, one that maintains the items in a sorted order as you add and remove them.There are multiple auto-sorting collections to choose from. The differences between these sorted collections are often subtle but can have an impact on the memory requirements and performance of your application, so it is worth putting effort into picking the most appropriate option for your requirements.Some common auto-sorting collections are shown in Table 8.14:

Collection Description

SortedDictionary This represents a collection of key/value pairs that are

sorted by key. Internally it maintains a binary tree for items.

SortedList This represents a collection of key-value pairs that are

sorted by key. The name is misleading because this is not a list. Compared to SortedDictionary , retrieval performance is similar, it uses less memory, and insert and remove operations are slower for unsorted data. If it is populated from sorted data, then it is faster. Internally, it maintains a sorted array with a binary search to find elements.

SortedSet This represents a collection of unique objects that are maintained in a sorted order.

Table 8.14: Common auto-sorting collections

Specialized collections‌

There are a few other collections for special situations.The System.Collections.BitArray collection manages a compact array of bit values, which are represented as Booleans, where true indicates that the bit is on (value is 1) and false indicates that the bit is off (value is 0).The System.Collections.Generics.LinkedList collection represents a doubly linked list where every item has a reference to its previous and next items. They provide better performance compared to List for scenarios where you will frequently insert and remove items from the middle of the list. In a LinkedList , the items do not have to be rearranged in memory.

Read-only, immutable, and frozen collections‌

When we looked at the generic collection interface, we saw that it has a property named IsReadOnly . This is useful when we want to pass a collection to a method but not allow it to make changes.For example, we might define a method, as shown in the following code:

void ReadCollection(ICollection collection)

{

// We can check if the collection is read-only. if (collection.IsReadOnly)

{

// Read the collection.

}

else

{

WriteLine("You have given me a collection that I could change!");

}

}

Generic collections like List and Dictionary have an AsReadOnly method to create a ReadOnlyCollection that references the original collection. Although the ReadOnlyCollection has to have an Add and a Remove method because it implements ICollection , it throws a NotImplementedException to prevent changes. If the original collection has items added or removed, the ReadOnlyCollection will see those changes. You can think of a ReadOnlyCollection as a protected view of a collection.Let's see how we can make sure a collection is read-only:

In the WorkingWithCollections project, in Program.Helpers.cs , add a method that should only be given a read-only dictionary with string for the type of key and value, but the naughty method tries to call Add , as shown in the following code:

private static void UseDictionary( IDictionary dictionary)

{

WriteLine($"Count before is {dictionary.Count}."); try

{

WriteLine("Adding new item with GUID values.");

// Add method with return type of void. dictionary.Add(

key: Guid.NewGuid().ToString(), value: Guid.NewGuid().ToString());

}

catch (NotSupportedException)

{

WriteLine("This dictionary does not support the Add method.");

}

WriteLine($"Count after is {dictionary.Count}.");

}

Note the type of parameter is IDictionary . Using an interface provides more flexibility because we can pass either a Dictionary , a ReadOnlyDictionary , or anything else that implements that interface.

1. In Program.cs , add statements to pass the keywords dictionary to this naughty method, as shown in the following code:

UseDictionary(keywords);

1. Run the code, view the result, and note that the naughty method was able to add a new key-value pair, so the count has incremented, as shown in the following output:

Count before is 3.

Adding new item with GUID values. Count after is 4.

1. In Program.cs , comment out the UseDictionary statement and then add a statement to pass the dictionary converted into a read-only collection, as shown in the following code:

//UseDictionary(keywords); UseDictionary(keywords.AsReadOnly());

1. Run the code, view the result, and note that this time the method was not able to add an item, so the count is the same, as shown in the following output:

Count before is 3.

Adding new item with GUID values.

This dictionary does not support the Add method. Count after is 3.

1. At the top of Program.cs , import the System.Collections.Immutable namespace, as shown in the following code:

using System.Collections.Immutable; // To use ImmutableDictionary.

1. In Program.cs , comment out the AsReadOnly statement and then add a statement to pass the keywords converted into an immutable dictionary, as shown highlighted in the following code:

//UseDictionary(keywords.AsReadOnly()); UseDictionary(keywords.ToImmutableDictionary());

1. Run the code, view the result, and note that this time the method was also not able to add a default value, so the count is the same – it is the same behavior as using a read-only collection, so what's the point of immutable collections?

If you import the System.Collections.Immutable namespace, then any collection that implements IEnumerable is given six extension methods to convert it into an immutable collection like a list, dictionary, set, and so on.Although the immutable collection will have a method named Add , it does not add an item to the original immutable collection!

Instead, it returns a new immutable collection with the new item in it. The original immutable collection still only has the original items in it.Let's see an example:

1. In Program.cs , add statements to convert the keywords dictionary into an immutable dictionary and then add a new keyword definition to it by randomly generating GUID values, as shown in the following code:

ImmutableDictionary immutableKeywords = keywords.ToImmutableDictionary();

// Call the Add method with a return value. ImmutableDictionary newDictionary =

immutableKeywords.Add(

key: Guid.NewGuid().ToString(), value: Guid.NewGuid().ToString());

OutputCollection("Immutable keywords dictionary", immutableKeywords); OutputCollection("New keywords dictionary", newDictionary);

1. Run the code, view the result, and note that the immutable keywords dictionary does not get modified when you call the Add method on it; instead, it returns a new dictionary with all the existing keywords plus the newly added keyword, as shown in the following output:

Immutable keywords dictionary:

[float, Single precision floating point number] [long, 64-bit integer data type]

[int, 32-bit integer data type] New keywords dictionary:

[d0e099ff-995f-4463-ae7f-7b59ed3c8d1d, 3f8e4c38-c7a3-4b20-acb3-01b2e3c86e8c] [float, Single precision floating point number]

[long, 64-bit integer data type] [int, 32-bit integer data type]

Newly added items will not always appear at the top of the dictionary as shown in my output above. Internally, the order is defined by the hash of the key. This is why dictionaries are sometimes called hash tables.

Good Practice: To improve performance, many applications store a shared copy of commonly accessed objects in a central cache. To safely allow multiple threads to work with those objects knowing they won't change, you should make them immutable or use a concurrent collection type, which you can read about at the following link: https://learn.microsoft.com/en-us/dotnet/api/system.collections.concurrent.

The generic collections have some potential performance issues related to how they are designed. First, being generic, the types of items or types used for keys and values for a dictionary have a big effect on performance depending on what they are. Since they could be any type, the .NET team cannot optimize the algorithm. string and int types are the most used in real life. If the .NET team could rely on those always being the types used, then they could greatly improve performance.Second, collections are dynamic, meaning that new items can be added, and existing items can be removed at any time. Even more optimizations could be made if the .NET team knew that no more changes would be made to the collection..NET 8 introduces a new concept: frozen collections. Hmmm, we already have immutable collections, so what is different about frozen collections? Are they tasty and delicious like ice cream? The idea is that 95% of the time, a collection is populated and then never changed. So, if we could optimize them at the time of creation, then those optimizations could be made, adding some time and effort upfront, but then after that, performance for reading the collection could be greatly improved.In .NET 8, there are only two frozen collections: FrozenDictionary and FrozenSet . More may come in future versions of .NET, but these are the two most common scenarios that would benefit from the frozen concept.Let's go:

1. At the top of Program.cs , import the System.Collections.Frozen namespace, as shown in the following code:

using System.Collections.Frozen; // To use FrozenDictionary.

1. At the bottom of Program.cs , add statements to convert the keywords dictionary into a frozen dictionary, output its items, and then look up the definition of long , as shown in the following code:

// Creating a frozen collection has an overhead to perform the

// sometimes complex optimizations. FrozenDictionary frozenKeywords =

keywords.ToFrozenDictionary();

OutputCollection("Frozen keywords dictionary", frozenKeywords);

// Lookups are faster in a frozen dictionary. WriteLine($"Define long: {frozenKeywords["long"]}");

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

Frozen keywords dictionary:

[int, 32-bit integer data type] [long, 64-bit integer data type]

[float, Single precision floating point number] Define long: 64-bit integer data type

What the Add method does depends on the type, as summarized in the following list:

image

List : Adds a new item to the end of the existing list.

image

Dictionary : Adds a new item to the existing dictionary in a position determined by its internal structure.

image

ReadOnlyCollection : Throws a not-supported exception.

image

ImmutableList : Returns a new list with the new item in it. Does not affect the original list.

image

ImmutableDictionary : Returns a new dictionary with the new item in it. Does not affect the original dictionary.

image

FrozenDictionary : Does not exist.

More Information: The documentation for frozen collections is found at the following link: https://learn.microsoft.com/en-us/dotnet/api/system.collections.frozen.

Initializing collections using collection expressions‌

Introduced with C# 12 is a new consistent syntax for initializing arrays, collections, and span variables.With C# 11 and earlier, you would have to declare and initialize an array, collection, or span of int values using the following code:

int[] numbersArray11 = { 1, 3, 5 };

List numbersList11 = new() { 1, 3, 5 };

Span numbersSpan11 = stackalloc int[] { 1, 3, 5 };

Starting with C# 12, you can now consistently use square brackets, and the compiler will do the right thing, as shown in the following code:

int[] numbersArray12 = [ 1, 3, 5 ];

List numbersList12 = [ 1, 3, 5 ];

Span numbersSpan12 = [ 1, 3, 5 ];

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

Good practice with collections‌

Since .NET 1.1, types like StringBuilder have had a method named EnsureCapacity that can presize its internal storage array to the expected final size of the string . This improves performance because it does not have to repeatedly increment the size of the array as more characters are appended.Since .NET Core 2.1, types like Dictionary and HashSet have also had EnsureCapacity .In .NET 6 and later, collections like List , Queue , and Stack now have an EnsureCapacity method too, as shown in the following code:

List names = new(); names.EnsureCapacity(10_000);

// Load ten thousand names into the list.

Let's say you need to create a method to process a collection. For maximum flexibility, you could declare the input parameter to be IEnumerable and make the method generic, as shown in the following code:

void ProcessCollection(IEnumerable collection)

{

// Process the items in the collection,

// perhaps using a foreach statement.

}

I could pass an array, a list, a queue, or a stack, containing any type, like int , string , Person , or anything else that implements IEnumerable , into this method and it will process the items. However, the flexibility to pass any collection to this method comes at a performance cost.One of the performance problems with IEnumerable is also one of its benefits: deferred execution, also known as lazy loading. Types that implement this interface do not have to implement deferred execution, but many do.But the worst performance problem with IEnumerable is that the iteration must allocate an object on the heap. To avoid this memory allocation, you should define your method using a concrete type, as shown highlighted in the following code:

void ProcessCollection(List collection)

{

// Process the items in the collection,

// perhaps using a foreach statement.

}

This will use the List.Enumerator GetEnumerator() method, which returns a struct , instead of the IEnumerator GetEnumerator() method, which returns a reference type. Your code will be two to three times faster and require less memory. As with all recommendations related to performance, you should confirm the benefit by running performance tests on your actual code in a product environment.

Working with spans, indexes, and ranges‌

One of Microsoft's goals with .NET Core 2.1 was to improve performance and resource usage. A key .NET feature that enables this is the Span type.

Using memory efficiently using spans‌

When manipulating arrays, you will often create new copies or subsets of existing ones so that you can process just the subset. This is not efficient because duplicate objects must be created in memory.If you need to work with a subset of an array, use a span because it is like a window into the original array. This is more efficient in terms of memory usage and improves performance. Spans only work with arrays, not collections, because the memory must be contiguous.Before we look at spans in more detail, we need to understand some related objects: indexes and ranges.

Identifying positions with the Index type‌

C# 8 introduced two features for identifying an item's index position within an array and a range of items using two indexes.You learned in the previous section that objects in a list can be accessed by passing an integer into their indexer, as shown in the following code:

int index = 3;

Person p = people[index]; // Fourth person in array. char letter = name[index]; // Fourth letter in name.

The Index value type is a more formal way of identifying a position, and supports counting from the end, as shown in the following code:

// Two ways to define the same index, 3 in from the start. Index i1 = new(value: 3); // Counts from the start

Index i2 = 3; // Using implicit int conversion operator.

// Two ways to define the same index, 5 in from the end. Index i3 = new(value: 5, fromEnd: true);

Index i4 = ^5; // Using the caret ^ operator.

Identifying ranges with the Range type‌

The Range value type uses Index values to indicate the start and end of its range, using its constructor, C# syntax, or its static methods, as shown in the following code:

Range r1 = new(start: new Index(3), end: new Index(7));

Range r2 = new(start: 3, end: 7); // Using implicit int conversion. Range r3 = 3..7; // Using C# 8.0 or later syntax.

Range r4 = Range.StartAt(3); // From index 3 to last index. Range r5 = 3..; // From index 3 to last index.

Range r6 = Range.EndAt(3); // From index 0 to index 3. Range r7 = ..3; // From index 0 to index 3.

Extension methods have been added to string values (which internally use an array of char ), int arrays, and spans to make ranges easier to work with. These extension methods accept a range as a parameter and return a Span . This makes them very memory-efficient.

Using indexes, ranges, and spans‌

Let's explore using indexes and ranges to return spans:

Use your preferred code editor to add a new Console App / console project named

WorkingWithRanges to the Chapter08 solution.

In Program.cs , delete the existing statements and then add statements to compare using the string type's Substring method with ranges to extract parts of someone's name, as shown in the following code:

string name = "Samantha Jones";

// Getting the lengths of the first and last names. int lengthOfFirst = name.IndexOf(' ');

int lengthOfLast = name.Length - lengthOfFirst - 1;

// Using Substring.

string firstName = name.Substring( startIndex: 0,

length: lengthOfFirst);

string lastName = name.Substring( startIndex: name.Length - lengthOfLast, length: lengthOfLast);

WriteLine($"First: {firstName}, Last: {lastName}");

// Using spans.

ReadOnlySpan nameAsSpan = name.AsSpan(); ReadOnlySpan firstNameSpan = nameAsSpan[0..lengthOfFirst]; ReadOnlySpan lastNameSpan = nameAsSpan[^lengthOfLast..]; WriteLine($"First: {firstNameSpan}, Last: {lastNameSpan}");

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

First: Samantha, Last: Jones First: Samantha, Last: Jones

Practicing and exploring‌

Test your knowledge and understanding by answering some questions, getting some hands-on practice, and exploring with deeper research into the topics in this chapter.

Exercise 8.1 – Test your knowledge‌

Use the web to answer the following questions:

What is the maximum number of characters that can be stored in a string variable?

When and why should you use a SecureString type?

When is it appropriate to use a StringBuilder class?

When should you use a LinkedList class?

When should you use a SortedDictionary class rather than a SortedList class?

In a regular expression, what does $ mean?

In a regular expression, how can you represent digits?

Why should you not use the official standard for email addresses to create a regular expression to validate a user's email address?

What characters are output when the following code runs?

string city = "Aberdeen";

ReadOnlySpan citySpan = city.AsSpan()[^5..^0]; WriteLine(citySpan.ToString());

1. How could you check that a web service is available before calling it?

Exercise 8.2 – Practice regular expressions‌

In the Chapter08 solution, create a console app named Ch08Ex02RegularExpressions that prompts the user to enter a regular expression and then prompts the user to enter some input, and compare the two for a match until the user presses Esc, as shown in the following output:

The default regular expression checks for at least one digit.

Enter a regular expression (or press ENTER to use the default): ^[a-z]+$ Enter some input: apples

apples matches ^[a-z]+$? True

Press ESC to end or any key to try again.

Enter a regular expression (or press ENTER to use the default): ^[a-z]+$ Enter some input: abc123xyz

abc123xyz matches ^[a-z]+$? False

Press ESC to end or any key to try again.

Exercise 8.3 – Practice writing extension methods‌

In the Chapter08 solution, create a class library named Ch08Ex03NumbersAsWordsLib and projects to test it. It should define extension methods that extend number types such as BigInteger and int with a method named ToWords that returns a string describing the number.For example, 18,000,000 would be eighteen million, and 18,456,002,032,011,000,007 would be eighteen quintillion, four hundred and fifty-six quadrillion, two trillion, thirty- two billion, eleven million, and seven.You can read more about names for large numbers at the following link: https://en.wikipedia.org/wiki/Names_of_large_numbers.

Exercise 8.4 – Working with network resources‌

If you are interested in some low-level types for working with network resources, then you can read an online-only section found at the following link:https://github.com/markjprice/cs12dotnet8/blob/main/docs/ch08-network-resources.md

Exercise 8.5 – 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-8---working- with-common-net-types

Summary‌

In this chapter, you explored:

image

Choices for types to store and manipulate numbers.

image

image

Handling text, including using regular expressions for validating input. Collections to use for storing multiple items.

image

Working with indexes, ranges, and spans.

In the next chapter, we will manage files and streams, encode and decode text, and perform serialization.

Working with Files, Streams, and Serialization‌‌‌

Join our book community on Discord

https://packt.link/EarlyAccess

image

This chapter is about reading and writing to files and streams, text encoding, and serialization. Applications that do not interact with the filesystem are extraordinarily rare. As a .NET developer, almost every application that you build will need to manage the filesystem and create, open, read, and write to and from files. Most of those files will contain text, so it is important to understand how text is encoded. And finally, after working with objects in memory, you will need to store them somewhere permanently for later reuse. You do that using a technique called serialization.In this chapter, we will cover the following topics:

image

Managing the filesystem

image

image

image

Reading and writing with streams Encoding and decoding text Serializing object graphs

image

Working with environment variables

Managing the filesystem‌

Your applications will often need to perform input and output operations with files and directories in different environments. The System and System.IO namespaces contain classes for this purpose.

Handling cross-platform environments and filesystems‌

Let's explore how to handle cross-platform environments and the differences between Windows, Linux, and macOS. Paths are different for Windows, macOS, and Linux, so we will start by exploring how .NET handles this:

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

image

image

image

Project template: Console App / console Project file and folder: WorkingWithFileSystems Solution file and folder: Chapter09

In the project file, add a package reference for Spectre.Console , and then add elements to import the following classes statically and globally: System.Console , System.IO.Directory , System.IO.Path , and System.Environment , as shown in the following markup:

Build the WorkingWithFileSystems project to restore packages.

Add a new class file named Program.Helpers.cs .

In Program.Helpers.cs , add a partial Program class with a SectionTitle method, as shown in the following code:

// null namespace to merge with auto-generated Program. partial class Program

{

private static void SectionTitle(string title)

{

WriteLine();

ConsoleColor previousColor = ForegroundColor;

// Use a color that stands out on your system. ForegroundColor = ConsoleColor.DarkYellow; WriteLine($"*** {title} ***");

ForegroundColor = previousColor;

}

}

image

1. In Program.cs , add statements to use a Spectre.Console table to do the following: Output the path and directory separation characters.

image

Output the path of the current directory.

image

Output some special paths for system files, temporary files, and documents:

using Spectre.Console; // To use Table.

#region Handling cross-platform environments and filesystems SectionTitle("Handling cross-platform environments and filesystems");

// Create a Spectre Console table. Table table = new();

// Add two columns with markup for colors. table.AddColumn("[blue]MEMBER[/]"); table.AddColumn("[blue]VALUE[/]");

// Add rows.

table.AddRow("Path.PathSeparator", PathSeparator.ToString()); table.AddRow("Path.DirectorySeparatorChar",

DirectorySeparatorChar.ToString()); table.AddRow("Directory.GetCurrentDirectory()",

GetCurrentDirectory()); table.AddRow("Environment.CurrentDirectory", CurrentDirectory); table.AddRow("Environment.SystemDirectory", SystemDirectory); table.AddRow("Path.GetTempPath()", GetTempPath()); table.AddRow("");

table.AddRow("GetFolderPath(SpecialFolder", "");

table.AddRow(" .System)", GetFolderPath(SpecialFolder.System)); table.AddRow(" .ApplicationData)",

GetFolderPath(SpecialFolder.ApplicationData)); table.AddRow(" .MyDocuments)",

GetFolderPath(SpecialFolder.MyDocuments)); table.AddRow(" .Personal)",

GetFolderPath(SpecialFolder.Personal));

// Render the table to the console AnsiConsole.Write(table); #endregion

The Environment type has many other useful members that we did not use in this code, including the OSVersion and ProcessorCount properties.

1. Run the code and view the result, as shown using Visual Studio 2022 on Windows in Figure 9.1:

image

Figure 9.1: Showing filesystem information with Visual Studio 2022 on Windows

More Information: You can learn more about using Spectre Console tables at the following link: https://spectreconsole.net/widgets/table.

When running the console app using dotnet run on a Mac, the path and directory separator characters are different and the CurrentDirectory will be the project folder, not a folder inside bin , as shown in Figure 9.2:

image

Figure 9.2: Showing filesystem information with the CLI on macOS

Good Practice: Windows uses a backslash ( \ ) for the directory separator character. macOS and Linux use a forward slash ( / ) for the directory separator character. Do not assume what character is used in your code when combining paths; use Path.DirectorySeparatorChar .

In future sections of this chapter, we will create directories and files in the Personal special folder, so make a note of where that is for your operating system. For example, if you're using Linux, it should be $USER/Documents .

Managing drives‌

To manage drives, use the DriveInfo type, which has a static method that returns information about all the drives connected to your computer. Each drive has a drive type.Let's explore drives:

1. In Program.cs , write statements to get all the drives and output their name, type, size, available free space, and format, but only if the drive is ready, as shown in the following code:

SectionTitle("Managing drives"); Table drives = new(); drives.AddColumn("[blue]NAME[/]"); drives.AddColumn("[blue]TYPE[/]"); drives.AddColumn("[blue]FORMAT[/]"); drives.AddColumn(new TableColumn(

"[blue]SIZE (BYTES)[/]").RightAligned()); drives.AddColumn(new TableColumn(

"[blue]FREE SPACE[/]").RightAligned());

foreach (DriveInfo drive in DriveInfo.GetDrives())

{

if (drive.IsReady)

{

drives.AddRow(drive.Name, drive.DriveType.ToString(), drive.DriveFormat, drive.TotalSize.ToString("N0"), drive.AvailableFreeSpace.ToString("N0"));

}

else

{

drives.AddRow(drive.Name, drive.DriveType.ToString(), string.Empty, string.Empty, string.Empty);

}

}

AnsiConsole.Write(drives);

Good Practice: Check that a drive is ready before reading properties such as TotalSize , or you will see an exception thrown with removable drives.

On Linux, by default, your console app will only have permission to read the Name and DriveType properties when run as a normal user. An UnauthorizedAccessException is thrown for DriveFormat , TotalSize , and AvailableFreeSpace . Run the console app as superuser to avoid this issue, as shown in the following command:

sudo dotnet run . Using sudo is fine in a development environment, but in a production environment, it's recommended to edit your permissions to avoid running with elevated permissions. On Linux, the name and drive format columns might also need to be wider, for example, 55 and 12 characters wide respectively.

1. Run the code and view the result, as shown in Figure 9.3:

image

Figure 9.3: Showing drive information on Windows and macOS

Managing directories‌

To manage directories, use the Directory , Path , and Environment static classes. These types include many members to work with the filesystem.When constructing custom paths, you must be careful to write your code so that it makes no assumptions about the platform, for example, what to use for the directory separator character:

1. In Program.cs , write statements to do the following:

image

Define a custom path under the user's home directory by creating an array of strings for the directory names, and then properly combine them with the Path type's Combine method.

image

Check for the existence of the custom directory path using the Exists method of the

Directory class.

image

Create and then delete the directory, including files and subdirectories within it, using the CreateDirectory and Delete methods of the Directory class:

SectionTitle("Managing directories"); string newFolder = Combine(

GetFolderPath(SpecialFolder.Personal), "NewFolder"); WriteLine($"Working with: {newFolder}");

// We must explicitly say which Exists method to use

// because we statically imported both Path and Directory. WriteLine($"Does it exist? {Path.Exists(newFolder)}"); WriteLine("Creating it...");

CreateDirectory(newFolder);

// Let's use the Directory.Exists method this time. WriteLine($"Does it exist? {Directory.Exists(newFolder)}"); Write("Confirm the directory exists, and then press any key."); ReadKey(intercept: true);

WriteLine("Deleting it..."); Delete(newFolder, recursive: true);

WriteLine($"Does it exist? {Path.Exists(newFolder)}");

In .NET 6 and earlier, only the Directory class had an Exists method. In .NET 7 or later, the Path class also has an Exists method. Both can be used to check for the existence of a path.

1. Run the code, view the result, and use your favorite file management tool to confirm that the directory has been created before pressing Enter to delete it, as shown in the following output:

Working with: C:\Users\markj\OneDrive\Documents\NewFolder Does it exist? False

Creating it...

Does it exist? True

Confirm the directory exists, and then press any key. Deleting it...

Does it exist? False

Managing files‌

When working with files, you can statically import the file type, just as we did for the directory type. However, for the next example, we will not do so because it has some of the same methods as the directory type, and they would conflict. The file type has a short enough name not to matter in this case. The steps are as follows:

In Program.cs , write statements to do the following:

Check for the existence of a file.

Create a text file.

Write a line of text to the file.

Close the file to release system resources and file locks (this would normally be done inside a try - finally statement block to ensure that the file is closed even if an exception occurs when writing to it).

Copy the file to a backup.

Delete the original file.

Read the backup file's contents and then close it:

SectionTitle("Managing files");

// Define a directory path to output files starting

// in the user's folder. string dir = Combine(

GetFolderPath(SpecialFolder.Personal), "OutputFiles"); CreateDirectory(dir);

// Define file paths.

string textFile = Combine(dir, "Dummy.txt"); string backupFile = Combine(dir, "Dummy.bak"); WriteLine($"Working with: {textFile}");

WriteLine($"Does it exist? {File.Exists(textFile)}");

// Create a new text file and write a line to it. StreamWriter textWriter = File.CreateText(textFile); textWriter.WriteLine("Hello, C#!");

textWriter.Close(); // Close file and release resources. WriteLine($"Does it exist? {File.Exists(textFile)}");

// Copy the file, and overwrite if it already exists. File.Copy(sourceFileName: textFile,

destFileName: backupFile, overwrite: true); WriteLine(

$"Does {backupFile} exist? {File.Exists(backupFile)}"); Write("Confirm the files exist, and then press any key."); ReadKey(intercept: true);

// Delete the file.

File.Delete(textFile);

WriteLine($"Does it exist? {File.Exists(textFile)}");

// Read from the text file backup. WriteLine($"Reading contents of {backupFile}:"); StreamReader textReader = File.OpenText(backupFile); WriteLine(textReader.ReadToEnd()); textReader.Close();

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

Working with: C:\Users\markj\OneDrive\Documents\OutputFiles\Dummy.txt Does it exist? False

Does it exist? True

Does C:\Users\markj\OneDrive\Documents\OutputFiles\Dummy.bak exist? True Confirm the files exist, and then press any key.

Does it exist? False

Reading contents of C:\Users\markj\OneDrive\Documents\OutputFiles\Dummy.bak: Hello, C#!

Managing paths‌

Sometimes, you need to work with parts of a path; for example, you might want to extract just the folder name, the filename, or the extension. Sometimes, you need to generate temporary folders and filenames. You can do this with static methods of the Path class:

1. In Program.cs , add the following statements:

SectionTitle("Managing paths");

WriteLine($"Folder Name: {GetDirectoryName(textFile)}"); WriteLine($"File Name: {GetFileName(textFile)}"); WriteLine("File Name without Extension: {0}",

GetFileNameWithoutExtension(textFile)); WriteLine($"File Extension: {GetExtension(textFile)}"); WriteLine($"Random File Name: {GetRandomFileName()}"); WriteLine($"Temporary File Name: {GetTempFileName()}");

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

Folder Name: C:\Users\markj\OneDrive\Documents\OutputFiles File Name: Dummy.txt

File Name without Extension: Dummy File Extension: .txt

Random File Name: u45w1zki.co3 Temporary File Name:

C:\Users\markj\AppData\Local\Temp\tmphdmipz.tmp

GetTempFileName creates a zero-byte file and returns its name, ready for you to use.

GetRandomFileName just returns a filename; it doesn't create the file.

Getting file information‌

To get more information about a file or directory, for example, its size or when it was last accessed, you can create an instance of the FileInfo or DirectoryInfo class. FileInfo and DirectoryInfo both inherit from FileSystemInfo , so they both have members such as LastAccessTime and Delete , as well as extra members specific to themselves, as shown in Table 9.1:

Class Members

FileSystemInfo

Fields: FullPath , OriginalPath

Properties: Attributes , CreationTime , CreationTimeUtc , Exists , Extension , FullName , LastAccessTime , LastAccessTimeUtc , LastWriteTime , LastWriteTimeUtc , Name

Methods: Delete , GetObjectData , Refresh

DirectoryInfo

Properties: Parent , Root

Methods: Create , CreateSubdirectory , EnumerateDirectories , EnumerateFiles , EnumerateFileSystemInfos , GetAccessControl , GetDirectories , GetFiles ,

GetFileSystemInfos , MoveTo , SetAccessControl

FileInfo

Properties: Directory , DirectoryName ,

IsReadOnly , Length

Methods: AppendText , CopyTo , Create , CreateText , Decrypt , Encrypt , GetAccessControl , MoveTo , Open , OpenRead , OpenText , OpenWrite , Replace , SetAccessControl

Table 9.1: Classes to get information about files and directories

Let's write some code that uses a FileInfo instance to efficiently perform multiple actions on a file:

1. In Program.cs , add statements to create an instance of FileInfo for the backup file, and write information about it to the console, as shown in the following code:

SectionTitle("Getting file information"); FileInfo info = new(backupFile); WriteLine($"{backupFile}:");

WriteLine($" Contains {info.Length} bytes."); WriteLine($" Last accessed: {info.LastAccessTime}"); WriteLine($" Has readonly set to {info.IsReadOnly}.");

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

C:\Users\markj\OneDrive\Documents\OutputFiles\Dummy.bak: Contains 12 bytes.

Last accessed: 13/07/2023 12:11:12 Has readonly set to False.

The number of bytes might be different on your operating system because operating systems can use different line endings.

Controlling how you work with files‌

When working with files, you often need to control how they are opened. The File.Open method has overloads to specify additional options using enum values.The enum types are as follows:

image

FileMode : This controls what you want to do with the file, like CreateNew ,

OpenOrCreate , or Truncate .

image

FileAccess : This controls what level of access you need, like ReadWrite .

image

FileShare : This controls locks on the file to allow other processes the specified level of access, like Read .

You might want to open a file and read from it, and allow other processes to read it too, as shown in the following code:

FileStream file = File.Open(pathToFile, FileMode.Open, FileAccess.Read, FileShare.Read);

There is also an enum for attributes of a file as follows:

image

FileAttributes : This is to check a FileSystemInfo -derived type’s Attributes property for values like Archive and Encrypted .

You could check a file or directory's attributes, as shown in the following code:

FileInfo info = new(backupFile);

WriteLine("Is the backup file compressed? {0}", info.Attributes.HasFlag(FileAttributes.Compressed));

Now that you've learned some common ways to work with the directories and files in the filesystem, you next need to learn how to read and write the data stored in a file, that is, how to work with streams.

Reading and writing with streams‌

In Chapter 10, Working with Data Using Entity Framework Core, you will use a file named Northwind.db , but you will not work with the file directly. Instead, you will interact with the SQLite database engine, which in turn will read and write to the file. In scenarios where there is no other system that "owns" the file and does the reading and writing for you, you will use a file stream to work directly with the file.A stream is a sequence of bytes that can be read from and written to. Although files can be processed rather like arrays, with random access provided by knowing the position of a byte within the file, it is more efficient to process a file as a stream in which the bytes can be accessed in sequential order. When a human does the processing, they tend to need random access so that they can jump around the data making changes and return to the data they worked on earlier. When an automated system does the processing, they tend to be able to work sequentially and only need to "touch" the data once.Streams can also be used to process terminal input and output and networking resources, such as sockets and ports, that do not provide random access and cannot seek (that is, move) to a position. You can write code to process some arbitrary bytes without knowing or caring where they come from. Your code simply reads or writes to a stream, and another piece of code handles where the bytes are stored.

Understanding abstract and concrete streams‌

There is an abstract class named Stream that represents any type of stream. Remember that an abstract class cannot be instantiated using new ; it can only be inherited. This is because it is only partially implemented.There are many concrete classes that inherit from this base class, including FileStream , MemoryStream , BufferedStream , GZipStream , and SslStream . They all work the same way. All streams implement IDisposable , so they have a Dispose method to release unmanaged resources.Some of the common members of the Stream class are described in Table 9.2:

Member Description

CanRead , CanWrite Length , Position

Close ,

Dispose

These properties determine if you can read from and write to the stream.

These properties determine the total number of bytes and the current position within the stream. These properties may throw a NotSupportedException for some types of streams, for example, if CanSeek returns false .

This method closes the stream and releases its resources. You can call either method since the implementation of Dispose literally calls Close !

Flush If the stream has a buffer, then this method writes the bytes in the buffer to the stream, and the buffer is cleared.

CanSeek This property determines if the Seek method can be used.

Seek This method moves the current position to the one specified in its parameter.

Read ,

ReadAsync

These methods read a specified number of bytes from the stream into a byte array and advance the position.

ReadByte This method reads the next byte from the stream and advances the position.

Write ,

WriteAsync

These methods write the contents of a byte array into the stream.

WriteByte This method writes a byte to the stream. Table 9.2: Common members of the Stream class

Understanding storage streams‌

Some storage streams that represent a location where the bytes will be stored are described in Table 9.3:

Namespace Class Description

System.IO FileStream Bytes stored in the filesystem.

System.IO MemoryStream Bytes stored in memory in the current process.

System.Net.Sockets NetworkStream Bytes stored at a network location. Table 9.3: Storage stream classes

FileStream has been rewritten in .NET 6 to have much higher performance and reliability on Windows. You can read more about this at the following link: https://devblogs.microsoft.com/dotnet/file-io-improvements-in-dotnet-6/.

Understanding function streams‌

Function streams cannot exist on their own but can only be "plugged into" other streams to add functionality. Some are described in Table 9.4:

Namespace Class Description

System.Security.Cryptography CryptoStream This encrypts and decrypts the stream.

System.IO.Compression GZipStream ,

DeflateStream

These compress and decompress the stream.

System.Net.Security AuthenticatedStream This sends credentials across the

stream.

Table 9.4: Function stream classes

Understanding stream helpers‌

Although there will be occasions where you need to work with streams at a low level, most often, you can plug helper classes into the chain to make things easier. All the helper types for streams implement IDisposable , so they have a Dispose method to release unmanaged resources.Some helper classes to handle common scenarios are described in Table 9.5:

Namespace Class Description

System.IO StreamReader This reads from the underlying stream as plain text.

System.IO StreamWriter This writes to the underlying stream as plain text.

System.IO BinaryReader This reads from streams as .NET types. For example, the ReadDecimal

method reads the next 16 bytes from the underlying stream as a

decimal value, and the ReadInt32 method reads the next 4 bytes as an int value.

System.IO BinaryWriter This writes to streams as .NET types. For example, the Write method with a decimal parameter writes 16 bytes to the underlying stream, and the Write method with an int parameter writes 4 bytes.

System.Xml XmlReader This reads from the underlying stream using the XML format. System.Xml XmlWriter This writes to the underlying stream using the XML format. Table 9.5: Stream helper classes

Building a stream pipeline‌

It is very common to combine a helper like StreamWriter and multiple function streams like CryptoStream and GZipStream with a storage stream like FileStream into a pipeline, as shown in Figure 9.4:

image

Figure 9.4: Writing plain text, then encrypting and compressing it into a file stream

Your code would just call a simple helper method like WriteLine to send a string value like "Hello" through the pipeline until it arrives at its final destination having been encrypted and compressed so it gets written to the file as "G7x" (or whatever it would be).

Writing to text streams‌

When you open a file to read or write to it, you use resources outside of .NET. These are called unmanaged resources and must be disposed of when you are done working with them. To deterministically control when they are disposed of, we can call the Dispose method. When the Stream class was first designed, all cleanup code was expected to go in the Close method. But later, the concept of IDisposable was added to .NET and Stream had to implement a Dispose method. Later, the using statement was added to .NET, which can automatically call Dispose . So today, you can call either Close or Dispose , and they actually do the same thing.Let's type some code to write text to a stream:

Use your preferred code editor to add a new Console App / console project named

WorkingWithStreams to the Chapter09 solution:

image

In Visual Studio, set the startup project for the solution to the current selection.

In the project file, add an element to import the System.Console , System.Environment , and System.IO.Path classes statically and globally.

Add a new class file named Program.Helpers.cs .

In Program.Helpers.cs , add a partial Program class with a SectionTitle and an

OutputFileInfo method, as shown in the following code:

// null namespace to merge with auto-generated Program. partial class Program

{

private static void SectionTitle(string title)

{

ConsoleColor previousColor = ForegroundColor; ForegroundColor = ConsoleColor.DarkYellow; WriteLine($"*** {title} ***"); ForegroundColor = previousColor;

}

private static void OutputFileInfo(string path)

{

WriteLine("**** File Info ****"); WriteLine($"File: {GetFileName(path)}"); WriteLine($"Path: {GetDirectoryName(path)}");

WriteLine($"Size: {new FileInfo(path).Length:N0} bytes."); WriteLine("/ ");

WriteLine(File.ReadAllText(path)); WriteLine(" /");

}

}

Add a new class file named Viper.cs .

In Viper.cs , define a static class named Viper with a static array of string values named Callsigns , as shown in the following code:

namespace Packt.Shared; public static class Viper

{

// Define an array of Viper pilot call signs. public static string[] Callsigns = new[]

{

"Husker", "Starbuck", "Apollo", "Boomer", "Bulldog", "Athena", "Helo", "Racetrack"

};

}

1. In Program.cs , delete the existing statements, and then import the namespace to work with the Viper class, as shown in the following code:

using Packt.Shared; // To use Viper.

1. In Program.cs , add statements to enumerate the Viper call signs, writing each one on its own line in a single text file, as shown in the following code:

SectionTitle("Writing to text streams");

// Define a file to write to.

string textFile = Combine(CurrentDirectory, "streams.txt");

// Create a text file and return a helper writer. StreamWriter text = File.CreateText(textFile);

// Enumerate the strings, writing each one to the stream

// on a separate line.

foreach (string item in Viper.Callsigns)

{

text.WriteLine(item);

}

text.Close(); // Release unmanaged file resources. OutputFileInfo(textFile);

Calling Close on the stream writer helper will call Close on the underlying stream. This in turn calls Dispose to release unmanaged file resources.

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

**** File Info **** File: streams.txt

Path: C:\cs12dotnet8\Chapter09\WorkingWithStreams\bin\Debug\net8.0 Size: 68 bytes.

/------------------

Husker Starbuck Apollo Boomer Bulldog Athena Helo Racetrack

------------------/

1. Open the file that was created, and confirm that it contains the list of call signs, as well as a blank line because we are effectively calling WriteLine twice: once when we write the last call sign to the file, and again when we read the whole file and write it out to the console.

Remember that if you run the project at the command prompt using dotnet run , then the path will be the project folder. It will not include bin\Debug\net8.0 .

Writing to XML streams‌

There are two ways to write an XML element, as follows:

image

WriteStartElement and WriteEndElement : Use this pair when an element might have child elements.

image

WriteElementString : Use this when an element does not have children.

Now, let's try storing the Viper pilot call signs array of string values in an XML file:

1. At the top of Program.cs , import the System.Xml namespace, as shown in the following code:

using System.Xml; // To use XmlWriter and so on.

1. At the bottom of Program.cs , add statements that enumerate the call signs, writing each one as an element in a single XML file, as shown in the following code:

SectionTitle("Writing to XML streams");

// Define a file path to write to.

string xmlFile = Combine(CurrentDirectory, "streams.xml");

// Declare variables for the filestream and XML writer. FileStream? xmlFileStream = null;

XmlWriter? xml = null; try

{

xmlFileStream = File.Create(xmlFile);

// Wrap the file stream in an XML writer helper and tell it

// to automatically indent nested elements. xml = XmlWriter.Create(xmlFileStream,

new XmlWriterSettings { Indent = true });

// Write the XML declaration. xml.WriteStartDocument();

// Write a root element. xml.WriteStartElement("callsigns");

// Enumerate the strings, writing each one to the stream. foreach (string item in Viper.Callsigns)

{

xml.WriteElementString("callsign", item);

}

// Write the close root element. xml.WriteEndElement();

}

catch (Exception ex)

{

// If the path doesn't exist the exception will be caught. WriteLine($"{ex.GetType()} says {ex.Message}");

}

finally

{

if (xml is not null)

{

xml.Close();

WriteLine("The XML writer's unmanaged resources have been disposed.");

}

if (xmlFileStream is not null)

{

xmlFileStream.Close();

WriteLine("The file stream's unmanaged resources have been disposed.");

}

}

OutputFileInfo(xmlFile);

1. Optionally, right-click in the Close method of xmlFileStream , select Go To Implementation, and note the implementations of the Dispose , Close , and Dispose(bool) methods, as shown in the following code:

public void Dispose() => Close(); public virtual void Close()

{

// When initially designed, Stream required that all cleanup logic

// went into Close(), but this was thought up before IDisposable

// was added and never revisited. All subclasses

// should put their cleanup now in Dispose(bool). Dispose(true);

GC.SuppressFinalize(this);

}

protected virtual void Dispose(bool disposing)

{

// Note: Never change this to call other virtual methods on Stream

// like Write, since the state on subclasses has already been

// torn down. This is the last code to run on cleanup for a stream.

}

The Close and Dispose(bool) methods are virtual in the Stream class because they are designed to be overridden in a derived class, like FileStream , to do the work of releasing unmanaged resources.

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

**** File Info ****

The XML writer's unmanaged resources have been disposed. The file stream's unmanaged resources have been disposed. File: streams.xml

Path: C:\cs12dotnet8\Chapter09\WorkingWithStreams\bin\Debug\net8.0 Size: 320 bytes.

/------------------

Husker

Starbuck

Apollo

Boomer

Bulldog

Athena

Helo

Racetrack

-------------------/

Good Practice: Before calling the Dispose method, check that the object is not null .

Simplifying disposal by using the using statement‌

You can simplify the code that needs to check for a null object and then call its Dispose method by using the using statement. Generally, I would recommend using using rather than manually calling Dispose because it’s less code to write, unless you need a greater level of control.Confusingly, there are two uses for the using keyword: importing a namespace and generating a finally statement that calls Dispose on an object implementing

IDisposable .The compiler changes a using statement block into a try - finally statement without a catch statement. You can use nested try statements; so, if you do want to catch any exceptions, you can, as shown in the following code example:

using (FileStream file2 = File.OpenWrite( Path.Combine(path, "file2.txt")))

{

using (StreamWriter writer2 = new StreamWriter(file2))

{

try

{

writer2.WriteLine("Welcome, .NET!");

}

catch(Exception ex)

{

WriteLine($"{ex.GetType()} says {ex.Message}");

}

} // Automatically calls Dispose if the object is not null.

} // Automatically calls Dispose if the object is not null.

You can even simplify the code further by not explicitly specifying the braces and indentation for the using statements, as shown in the following code:

using FileStream file2 = File.OpenWrite( Path.Combine(path, "file2.txt"));

using StreamWriter writer2 = new(file2); try

{

writer2.WriteLine("Welcome, .NET!");

}

catch(Exception ex)

{

WriteLine($"{ex.GetType()} says {ex.Message}");

}

Compressing streams‌

XML is relatively verbose, so it takes up more space in bytes than plain text. Let's see how we can squeeze the XML using a common compression algorithm known as GZIP.In .NET Core 2.1, Microsoft introduced an implementation of the Brotli compression algorithm. In performance, Brotli is like the algorithm used in DEFLATE and GZIP, but the output is about 20% denser.Let's compare the two compression algorithms:

Add a new class file named Program.Compress.cs .

In Program.Compress.cs , write statements to use instances of GZipStream or BrotliStream to create a compressed file containing the same XML elements as before, and then decompress it while reading it and outputting to the console, as shown in the following code:

using Packt.Shared; // To use Viper.

using System.IO.Compression; // To use BrotliStream, GZipStream. using System.Xml; // To use XmlWriter, XmlReader.

partial class Program

{

private static void Compress(string algorithm = "gzip")

{

// Define a file path using the algorithm as file extension. string filePath = Combine(

CurrentDirectory, $"streams.{algorithm}"); FileStream file = File.Create(filePath); Stream compressor;

if (algorithm == "gzip")

{

compressor = new GZipStream(file, CompressionMode.Compress);

}

else

{

compressor = new BrotliStream(file, CompressionMode.Compress);

}

using (compressor)

{

using (XmlWriter xml = XmlWriter.Create(compressor))

{

xml.WriteStartDocument(); xml.WriteStartElement("callsigns"); foreach (string item in Viper.Callsigns)

{

xml.WriteElementString("callsign", item);

}

}

} // Also closes the underlying stream. OutputFileInfo(filePath);

// Read the compressed file. WriteLine("Reading the compressed XML file:"); file = File.Open(filePath, FileMode.Open); Stream decompressor;

if (algorithm == "gzip")

{

decompressor = new GZipStream(

file, CompressionMode.Decompress);

}

else

{

decompressor = new BrotliStream( file, CompressionMode.Decompress);

}

using (decompressor)

using (XmlReader reader = XmlReader.Create(decompressor)) while (reader.Read())

{

// Check if we are on an element node named callsign. if ((reader.NodeType == XmlNodeType.Element)

&& (reader.Name == "callsign"))

{

reader.Read(); // Move to the text inside element. WriteLine($"{reader.Value}"); // Read its value.

}

// Alternative syntax with property pattern matching:

// if (reader is { NodeType: XmlNodeType.Element,

// Name: "callsign" })

}

}

}

1. In Program.cs , add calls to Compress with parameters to use gzip and brotli

algorithms, as shown in the following code:

SectionTitle("Compressing streams"); Compress(algorithm: "gzip"); Compress(algorithm: "brotli");

1. Run the code, and compare the sizes of the XML file and the compressed XML file using

gzip and brotli algorithms, as shown in the following output:

**** File Info **** File: streams.gzip

Path: C:\cs12dotnet8\Chapter09\WorkingWithStreams\bin\Debug\net8.0 Size: 151 bytes.

/------------------

?

z?{??}En?BYjQqf~???????Bj^r~Jf^??RiI??????MrbNNqfz^1?i?QZ??Zd?@H?$%?&gc?t,?????*????H?????t?&?d?

------------------/

Reading the compressed XML file: Husker

Starbuck Apollo Boomer Bulldog

Athena Helo Racetrack

**** File Info **** File: streams.brotli

Path: C:\cs12dotnet8\Chapter09\WorkingWithStreams\bin\Debug\net8.0 Size: 117 bytes.

/-------------------

??d?&?_????\@?Gm????/?h>?6????? ??^? ???wE?'?t?+??F??]

?T?\?~??A?J?Q?q6 ?‐??

???

--------------------/

Reading the compressed XML file: Husker

Starbuck Apollo Boomer Bulldog Athena Helo Racetrack

To summarize:

image

Uncompressed: 320 bytes

image

image

GZIP-compressed: 151 bytes Brotli compressed: 117 bytes

As well as choosing a compression mode, you can also choose a compression level. You can learn more about this at the following link: https://learn.microsoft.com/en- us/dotnet/api/system.io.compression.compressionlevel.

Reading and writing with random access handles‌

For the first 20 years of .NET's life, the only API to work directly with files was the stream classes. These work great for automated tasks that only need to process data sequentially. But when a human interacts with the data, they often want to jump around and return multiple times to the same location. With .NET 6 and later, there is a new API for working with files without needing a file stream and in a random access way. Let's see a simple example:

Use your preferred code editor to add a new Console App / console project named

WorkingWithRandomAccess to the Chapter09 solution:

In the project file, add an element to import the System.Console class statically and globally.

In Program.cs , delete the existing statements, and then get a handle to a file named

coffee.txt , as shown in the following code:

using Microsoft.Win32.SafeHandles; // To use SafeFileHandle. using System.Text; // To use Encoding.

using SafeFileHandle handle = File.OpenHandle(path: "coffee.txt",

mode: FileMode.OpenOrCreate, access: FileAccess.ReadWrite);

1. Write some text encoded as a byte array, and then store it in a read-only memory buffer to the file, as shown in the following code:

string message = "Café £4.39";

ReadOnlyMemory buffer = new(Encoding.UTF8.GetBytes(message)); await RandomAccess.WriteAsync(handle, buffer, fileOffset: 0);

1. To read from the file, get the length of the file, allocate a memory buffer for the contents using that length, and then read the file, as shown in the following code:

long length = RandomAccess.GetLength(handle); Memory contentBytes = new(new byte[length]);

await RandomAccess.ReadAsync(handle, contentBytes, fileOffset: 0); string content = Encoding.UTF8.GetString(contentBytes.ToArray()); WriteLine($"Content of file: {content}");

1. Run the code, and note the content of the file, as shown in the following output:

Content of file: Café £4.39

Encoding and decoding text‌

Text characters can be represented in different ways. For example, the alphabet can be encoded using Morse code into a series of dots and dashes for transmission over a telegraph line.In a similar way, text inside a computer is stored as bits (ones and zeros) representing a code point within a code space. Most code points represent a single character, but they can also have other meanings like formatting.For example, ASCII has a code space with 128 code points. .NET uses a standard called Unicode to encode text internally. Unicode has more than 1 million code points.Sometimes, you will need to move text outside .NET for use by systems that do not use Unicode or a variation of it, so it is important to learn how to convert between encodings.Some common text encodings used by computers are shown in Table 9.6:

Encoding Description

ASCII This encodes a limited range of characters using the lower seven bits of a byte. UTF-8 This represents each Unicode code point as a sequence of one to four bytes.

UTF-7 This is designed to be more efficient over 7-bit channels than UTF-8, but it has security and robustness issues, so UTF-8 is recommended over UTF-7.

UTF-16 This represents each Unicode code point as a sequence of one or two 16-bit integers.

UTF-32 This represents each Unicode code point as a 32-bit integer and is, therefore, a fixed-length encoding unlike the other Unicode encodings, which are all variable- length encodings.

ANSI/ISO This provides support for a variety of code pages that are used to support a

encodings specific language or group of languages.

Table 9.6: Common text encodings

Good Practice: In most cases today, UTF-8 is a good default, which is why it is literally the default encoding, that is, Encoding.Default . You should avoid using Encoding.UTF7 because it is not secure. Due to this, the C# compiler will warn you when you try to use UTF-7. Of course, you might need to generate text using that encoding for compatibility with another system, so it needs to remain an option in .NET.

Encoding strings as byte arrays‌

Let's explore text encodings:

Use your preferred code editor to add a new Console App / console project named

WorkingWithEncodings to the Chapter09 solution.

In the project file, add an element to statically and globally import the System.Console

class.

In Program.cs , delete the existing statements, import the System.Text namespace, add statements to encode a string using an encoding chosen by the user, loop through each byte, and then decode it back into a string and output it, as shown in the following code:

using System.Text; // To use Encoding. WriteLine("Encodings");

WriteLine("[1] ASCII");

WriteLine("[2] UTF-7");

WriteLine("[3] UTF-8");

WriteLine("[4] UTF-16 (Unicode)");

WriteLine("[5] UTF-32");

WriteLine("[6] Latin1");

WriteLine("[any other key] Default encoding"); WriteLine();

Write("Press a number to choose an encoding."); ConsoleKey number = ReadKey(intercept: true).Key; WriteLine(); WriteLine();

Encoding encoder = number switch

{

ConsoleKey.D1 or ConsoleKey.NumPad1 => Encoding.ASCII, ConsoleKey.D2 or ConsoleKey.NumPad2 => Encoding.UTF7, ConsoleKey.D3 or ConsoleKey.NumPad3 => Encoding.UTF8, ConsoleKey.D4 or ConsoleKey.NumPad4 => Encoding.Unicode, ConsoleKey.D5 or ConsoleKey.NumPad5 => Encoding.UTF32, ConsoleKey.D6 or ConsoleKey.NumPad6 => Encoding.Latin1,

_ => Encoding.Default

};

// Define a string to encode string message = "Café £4.39";

WriteLine($"Text to encode: {message} Characters: {message.Length}.");

// Encode the string into a byte array. byte[] encoded = encoder.GetBytes(message);

// Check how many bytes the encoding needed. WriteLine("{0} used {1:N0} bytes.",

encoder.GetType().Name, encoded.Length); WriteLine();

// Enumerate each byte. WriteLine("BYTE | HEX | CHAR"); foreach (byte b in encoded)

{

WriteLine($"{b,4} | {b,3:X} | {(char)b,4}");

}

// Decode the byte array back into a string and display it. string decoded = encoder.GetString(encoded); WriteLine($"Decoded: {decoded}");

1. Run the code, press 1 to choose ASCII, and note that when outputting the bytes, the pound sign ( £ ) and accented e ( é ) cannot be represented in ASCII, so it uses a question mark instead:

Text to encode: Café £4.39 Characters: 10 ASCIIEncodingSealed used 10 bytes.

BYTE

|

HEX

|

CHAR

67

|

43

|

C

97

|

61

|

a

102

|

66

|

f

63

|

3F

|

?

32

|

20

|

63

|

3F

|

?

52

|

34

|

4

46

|

2E

|

.

51

|

33

|

3

57

|

39

|

9

Decoded: Caf? ?4.39

1. Rerun the code and press 3 to choose UTF-8. Note that UTF-8 requires 2 extra bytes for the two characters that need 2 bytes each (12 bytes instead of 10 bytes in total), but

it can encode and decode the é and £ characters:

Text to encode: Café £4.39 Characters: 10 UTF8EncodingSealed used 12 bytes.

BYTE

|

HEX

|

CHAR

67

|

43

|

C

97

|

61

|

a

102

|

66

|

f

195

|

C3

|

Ã

169

|

A9

|

©

32

|

20

|

194

|

C2

|

Â

163

|

A3

|

£

52

|

34

|

4

46

|

2E

|

.

51

|

33

|

3

57

|

39

|

9

Decoded: Café £4.39

1. Rerun the code and press 4 to choose Unicode (UTF-16). Note that UTF-16 requires 2 bytes for every character, so 20 bytes in total, and it can encode and decode the é and £ characters. This encoding is used internally by .NET to store char and string values.

Encoding and decoding text in files‌

When using stream helper classes, such as StreamReader and StreamWriter , you can specify the encoding you want to use. As you write to the helper, the text will be automatically encoded, and as you read from the helper, the bytes will be automatically decoded.To specify an encoding, pass the encoding as a second parameter to the helper type's constructor, as shown in the following code:

StreamReader reader = new(stream, Encoding.UTF8); StreamWriter writer = new(stream, Encoding.UTF8);

Good Practice: Often, you won't have the choice of which encoding to use because you will generate a file for use by another system. However, if you do, pick one that uses the least number of bytes but can store every character you need.

Serializing object graphs‌

An object graph is a structure of multiple objects that are related to each other, either through a direct reference or indirectly through a chain of references.Serialization is the process of converting a live object graph into a sequence of bytes using a specified format. Deserialization is the reverse process. You would use serialization to save the current state of a live object so that you can recreate it in the future, for example, saving the current state of a game so that you can continue at the same place tomorrow. The stream produced from a serialized object is usually stored in a file or database.There are dozens of formats you can choose for serialization, but the two most common text-based human- readable formats are eXtensible Markup Language (XML) and JavaScript Object Notation (JSON). There are also more efficient binary formats like Protobuf used by gRPC.

Good Practice: JSON is more compact and is best for web and mobile applications. XML is more verbose but is better supported in more legacy systems. Use JSON to minimize the size of serialized object graphs. JSON is also a good choice when sending object graphs to web applications and mobile applications because JSON is the native serialization format for JavaScript, and mobile apps often make calls over limited bandwidth, so the number of bytes is important.

.NET has multiple classes that will serialize to and from XML and JSON. We will start by looking at XmlSerializer and JsonSerializer .

Serializing as XML‌

Let's start by looking at XML, probably the world's most used serialization format (for now). To show a typical example, we will define a custom class to store information about a person and then create an object graph, using a list of Person instances with nesting:

Use your preferred code editor to add a new Console App / console project named

WorkingWithSerialization to the Chapter09 solution.

In the project file, add elements to statically and globally import the System.Console ,

System.Environment , and System.IO.Path classes.

Add a new class file named Program.Helpers.cs .

In Program.Helpers.cs , add a partial Program class with a SectionTitle and an

OutputFileInfo method, as shown in the following code:

// null namespace to merge with auto-generated Program. partial class Program

{

private static void SectionTitle(string title)

{

ConsoleColor previousColor = ForegroundColor; ForegroundColor = ConsoleColor.DarkYellow; WriteLine($"*** {title} ***"); ForegroundColor = previousColor;

}

private static void OutputFileInfo(string path)

{

WriteLine("**** File Info ****"); WriteLine($"File: {GetFileName(path)}"); WriteLine($"Path: {GetDirectoryName(path)}");

WriteLine($"Size: {new FileInfo(path).Length:N0} bytes."); WriteLine("/ ");

WriteLine(File.ReadAllText(path)); WriteLine(" /");

}

}

1. Add a new class file named Person.cs to define a Person class with a Salary property that is protected , meaning it is only accessible to itself and derived classes. To populate the salary, the class has a constructor with a single parameter to set the initial salary, as shown in the following code:

namespace Packt.Shared; public class Person

{

public Person(decimal initialSalary)

{

Salary = initialSalary;

}

public string? FirstName { get; set; } public string? LastName { get; set; } public DateTime DateOfBirth { get; set; }

public HashSet? Children { get; set; } protected decimal Salary { get; set; }

}

1. In Program.cs , delete the existing statements, and then import namespaces to work with XML serialization and the Person class, as shown in the following code:

using System.Xml.Serialization; // To use XmlSerializer. using Packt.Shared; // To use Person.

1. In Program.cs , add statements to create an object graph of Person instances, as shown in the following code:

List people = new()

{

new(initialSalary: 30_000M)

{

FirstName = "Alice", LastName = "Smith",

DateOfBirth = new(year: 1974, month: 3, day: 14)

},

new(initialSalary: 40_000M)

{

FirstName = "Bob", LastName = "Jones",

DateOfBirth = new(year: 1969, month: 11, day: 23)

},

new(initialSalary: 20_000M)

{

FirstName = "Charlie", LastName = "Cox",

DateOfBirth = new(year: 1984, month: 5, day: 4), Children = new()

{

new(initialSalary: 0M)

{

FirstName = "Sally", LastName = "Cox",

DateOfBirth = new(year: 2012, month: 7, day: 12)

}

}

}

};

SectionTitle("Serializing as XML");

// Create serializer to format a "List of Person" as XML. XmlSerializer xs = new(type: people.GetType());

// Create a file to write to.

string path = Combine(CurrentDirectory, "people.xml"); using (FileStream stream = File.Create(path))

{

// Serialize the object graph to the stream. xs.Serialize(stream, people);

} // Closes the stream.

OutputFileInfo(path);

1. Run the code, view the result, and note that an exception is thrown, as shown in the following output:

Unhandled Exception: System.InvalidOperationException: Packt.Shared.Person cannot be serialized

1. In Person.cs , add a statement to define a parameterless constructor , as shown in the following code:

// A parameterless constructor is required for XML serialization. public Person() { }

The constructor does not need to do anything, but it must exist so that the XmlSerializer can call it to instantiate new Person instances during the deserialization process.

1. Run the code and view the result, and note that the object graph is serialized as XML elements, like Bob , and that the Salary property is not included because it is not a public property, as shown in the following output:

**** File Info **** File: people.xml

Path: C:\cs12dotnet8\Chapter09\WorkingWithSerialization\bin\Debug\net8.0

Size: 793 bytes.

/------------------

public string? FirstName { get; set; } [XmlAttribute("lname")]

public string? LastName { get; set; } [XmlAttribute("dob")]

public DateTime DateOfBirth { get; set; }

1. Run the code, and note that the size of the file has reduced from 793 to 488 bytes, a space-saving of more than a third. This reduction was achieved by outputting property values as XML attributes, as shown in the following output:

**** File Info **** File: people.xml

Path: C:\cs12dotnet8\Chapter09\WorkingWithSerialization\bin\Debug\net8.0 Size: 488 bytes.

/------------------

------------------/

Deserializing XML files‌

Now, let's try deserializing the XML file back into live objects in memory:

1. In Program.cs , add statements to open the XML file, and then deserialize it, as shown in the following code:

SectionTitle("Deserializing XML files");

using (FileStream xmlLoad = File.Open(path, FileMode.Open))

{

// Deserialize and cast the object graph into a "List of Person". List? loadedPeople =

xs.Deserialize(xmlLoad) as List; if (loadedPeople is not null)

{

foreach (Person p in loadedPeople)

{

WriteLine("{0} has {1} children.", p.LastName, p.Children?.Count ?? 0);

}

}

}

1. Run the code, and note that the people are loaded successfully from the XML file and then enumerated, as shown in the following output:

Smith has 0 children. Jones has 0 children. Cox has 1 children.

More Information: There are many other attributes defined in the System.Xml.Serialization namespace that can be used to control the XML generated. A good place to start is the official documentation for the XmlAttributeAttribute class found here: https://learn.microsoft.com/en- us/dotnet/api/system.xml.serialization.xmlattributeattribute. Do not get this class confused with the XmlAttribute class in the System.Xml namespace. That is used to represent an XML attribute when reading and writing XML, using XmlReader and XmlWriter .

If you don't use any annotations, XmlSerializer performs a case-insensitive match using the property name when deserializing.

Good Practice: When using XmlSerializer , remember that only the public fields and properties are included, and the type must have a parameterless constructor. You can customize the output with attributes.

Serializing with JSON‌

One of the most popular .NET libraries to work with the JSON serialization format is Newtonsoft.Json, known as Json.NET. It is mature and powerful. Newtonsoft.Json is so popular that it overflowed the bounds of the 32-bit integer used for the download count in the NuGet package manager, as shown in the following tweet in Figure 9.5:

image

Figure 9.5: Negative 2 billion downloads for Newtonsoft.Json in August 2022

Let's see it in action:

1. In the WorkingWithSerialization project, add a package reference for the latest version of Newtonsoft.Json , as shown in the following markup:

Build the WorkingWithSerialization project to restore packages.

In Program.cs , add statements to create a text file, and then serialize the people into the file as JSON, as shown in the following code:

SectionTitle("Serializing with JSON");

// Create a file to write to.

string jsonPath = Combine(CurrentDirectory, "people.json"); using (StreamWriter jsonStream = File.CreateText(jsonPath))

{

Newtonsoft.Json.JsonSerializer jss = new();

// Serialize the object graph into a string. jss.Serialize(jsonStream, people);

} // Closes the file stream and release resources. OutputFileInfo(jsonPath);

1. Run the code, and note that JSON requires fewer than half the number of bytes compared to XML with elements. It's even smaller than the XML file, which uses attributes (366 compared to 488), as shown in the following output:

**** File Info **** File: people.json

Path: C:\cs12dotnet8\Chapter09\WorkingWithSerialization\bin\Debug\net8.0 Size: 366 bytes.

/------------------

[{"FirstName":"Alice","LastName":"Smith","DateOfBirth":"1974-03-14T00:00:00","Children":null},{"

------------------/

High-performance JSON processing‌

.NET Core 3 introduced a new namespace to work with JSON, System.Text.Json , which is optimized for performance by leveraging APIs like Span .Also, older libraries like Json.NET are implemented by reading UTF-16. It would be more performant to read and write JSON documents using UTF-8 because most network protocols, including HTTP, use UTF-8, and you can avoid transcoding UTF-8 to and from Json.NET's Unicode string values.With the new API, Microsoft achieved between 1.3x and 5x improvement, depending on the scenario.The

original author of Json.NET, James Newton-King, joined Microsoft and is working with them to develop their new JSON types. As he says in a comment discussing the new JSON APIs, "Json.NET isn't going away," as shown in Figure 9.6:

image

Figure 9.6: A comment by the original author of Json.NET

Deserializing JSON files‌

Let's see how to use the modern JSON APIs to deserialize a JSON file:

1. In the WorkingWithSerialization project, at the top of Program.cs , import the new JSON class to perform serialization, using an alias to avoid conflicting names with the Json.NET one we used before, as shown in the following code:

using FastJson = System.Text.Json.JsonSerializer;

1. In Program.cs , add statements to open the JSON file, deserialize it, and output the names and counts of the children of the people, as shown in the following code:

SectionTitle("Deserializing JSON files");

await using (FileStream jsonLoad = File.Open(jsonPath, FileMode.Open))

{

// Deserialize object graph into a "List of Person". List? loadedPeople =

await FastJson.DeserializeAsync(utf8Json: jsonLoad, returnType: typeof(List)) as List;

if (loadedPeople is not null)

{

foreach (Person p in loadedPeople)

{

WriteLine("{0} has {1} children.", p.LastName, p.Children?.Count ?? 0);

}

}

}

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

Smith has 0 children. Jones has 0 children. Cox has 1 children.

Good Practice: Choose Json.NET for developer productivity and a large feature set, or System.Text.Json for performance. You can review a list of the differences at the following link: https://learn.microsoft.com/en-us/dotnet/standard/serialization/system- text-json-migrate-from-newtonsoft-how-to#table-of-differences-between-newtonsoftjson- and-systemtextjson.

Controlling JSON processing‌

There are many options to take control of how JSON is processed, as shown in the following list:

image

image

Including and excluding fields. Setting a casing policy.

image

Selecting a case-sensitivity policy.

image

Choosing between compact and prettified whitespace.

Let's see some in action:

Use your preferred code editor to add a new Console App / console project named

ControllingJson to the Chapter09 solution.

In the project file, add elements to statically and globally import the System.Console ,

System.Environment , and System.IO.Path classes.

In the ControllingJson project, add a new class file named Book.cs .

In Book.cs , define a class named Book , as shown in the following code:

using System.Text.Json.Serialization; // To use [JsonInclude]. namespace Packt.Shared;

public class Book

{

// Constructor to set non-nullable property. public Book(string title)

{

Title = title;

}

// Properties.

public string Title { get; set; } public string? Author { get; set; }

// Fields.

[JsonInclude] // Include this field. public DateTime PublishDate; [JsonInclude] // Include this field. public DateTimeOffset Created; public ushort Pages;

}

1. In Program.cs , delete the existing statements, and then import the namespaces to work with high-performance JSON and Book , as shown in the following code:

using Packt.Shared; // To use Book.

using System.Text.Json; // To use JsonSerializer.

1. In Program.cs , add statements to create an instance of the Book class and serialize it to JSON, as shown in the following code:

Book csharpBook = new(title:

"C# 12 and .NET 8 - Modern Cross-Platform Development Fundamentals")

{

Author = "Mark J Price",

PublishDate = new(year: 2023, month: 11, day: 14),

Pages = 823,

Created = DateTimeOffset.UtcNow,

};

JsonSerializerOptions options = new()

{

IncludeFields = true, // Includes all fields. PropertyNameCaseInsensitive = true, WriteIndented = true,

PropertyNamingPolicy = JsonNamingPolicy.CamelCase,

};

string path = Combine(CurrentDirectory, "book.json"); using (Stream fileStream = File.Create(path))

{

JsonSerializer.Serialize(

utf8Json: fileStream, value: csharpBook, options);

}

WriteLine("**** File Info ****"); WriteLine($"File: {GetFileName(path)}"); WriteLine($"Path: {GetDirectoryName(path)}");

WriteLine($"Size: {new FileInfo(path).Length:N0} bytes."); WriteLine("/ ");

WriteLine(File.ReadAllText(path)); WriteLine(" /");