CHAPTER 34 Web Applications using Razor Pages

This chapter builds on what you learned in the previous chapter and completes the AutoLot.Web Razor Page based application. The underlying architecture for Razor Page based applications is very similar to MVC style applications, with the main difference being that they are page based instead of controller based. This chapter will highlight the differences as the AutoLot.Web application is built, and assumes that you have read the previous chapters on ASP.NET Core.

■Note The sample code for this chapter is in the Chapter 34 directory of this book’s repo. Feel free to continue working with the solution you started in the previous ASP.NET Core chapters.

Anatomy of a Razor Page
Unlike MVC style applications, views in Razor Page based applications are part of the page. To demonstrate, add a new empty Razor Page named RazorSyntax by right clicking the Pages directory in the AutoLot.Web project in Visual Studio, select Add ➤ Razor Page, and chose the Razor Page – Empty template. You will see two files created, RazorSyntax.cshtml and RazorSyntax.cshtml.cs. The RazorSyntax.cshtml file is the view for the page and the RazorSyntax.cshtml.cs file is the code behind file for the view.
Before proceeding, add the following global using statements to the GlobalUsings.cs file in the AutoLot.Web project:

global using AutoLot.Models.Entities; global using Microsoft.AspNetCore.Mvc;
global using Microsoft.AspNetCore.Mvc.RazorPages; global using AutoLot.Services.DataServices.Interfaces; global using Microsoft.Build.Framework;

Razor Page PageModel Classes and Page Handler Methods
The code behind the file for a Razor Page derives from the PageModel base class and is named with the Model suffix, like RazorSyntaxModel. The PageModel base class, like the Controller base class in MVC style applications, provides many helper methods useful for building web applications. Unlike

© Andrew Troelsen, Phil Japikse 2022
A. Troelsen and P. Japikse, Pro C# 10 with .NET 6, https://doi.org/10.1007/978-1-4842-7869-7_34

1559

the Controller class, Razor Pages are tied to a single view, have directory structure based routes, and have a single set of page handler methods to service the HTTP get (OnGet()/OnGetAsync()) and post (OnPost()/OnPostAsync()) requests.
Change the scaffolded RazorSyntaxModel class so the OnGet() page handler method is asynchronous and update the name to OnGetAsync(). Next, add an async OnPostAsync() page handler method for HTTP Post requests:

namespace AutoLot.Web.Pages;

public class RazorSyntaxModel : PageModel
{
public async Task OnGetAsync()
{
}
public async Task OnPostAsync()
{
}
}

■Note The default names can be changed. This will be covered later in this chapter.

Notice how the page handler methods don’t return a value like their action method counterparts. When the page handler method does return a value, the page implicitly returns the view that the page is associated with. Razor Page handler methods also support returning an IActionResult, which then requires explicitly returning an IActionResult. If the method is to return the class’s view, the Page() method is returned. The method could also redirect to another page. Both scenarios are shown in this code sample:

public async Task OnGetAsync()
{
return Page();
}
public async Task OnPostAsync()
{
return RedirectToPage("Index")
}

Derived PageModel classes support both method and constructor injection. When using method injection, the parameter must be marked with the [FromService] attribute, like this:

public async Task OnGetAsync([FromServices] ICarDataService carDataService)
{
//Get a car instance
}

Since PageModel classes are focused on a single view, it is more common to use constructor injection instead of method injection. Update the RazorSyntaxModel class by adding a constructor that takes an instance of the ICarDataService and assigns it to a class level field:

private readonly ICarDataService _carDataService;

public RazorSyntaxModel(ICarDataService carDataService)
{
_carDataService = carDataService;
}

If you inspect the Page() method, you will see that there isn’t an overload that takes an object. While the related View() method in MVC is used to pass the model to the view, Razor Pages use properties on the PageModel class to send data to the view. Add a new public property named Entity of type Car to the RazorSyntaxModel class:

public Car Entity { get; set; }

Now, use the data service to get a Car record and assign it to the public property (if the UseApi flag in
appsettings.Development.json is set to true, make sure AutoLot.Api is running):

public async Task OnGetAsync()
{
Entity = await _carDataService.FindAsync(6); return Page();
}

Razor Pages can use implicit binding to get data from a view, just like MVC action methods:

public async Task OnPostAsync(Car entity)
{
//do something interesting return RedirectToPage("Index");
}

Razor Pages also support explicit binding:

public async Task OnPostAsync()
{
var newCar = new Car();
if (await TryUpdateModelAsync(newCar, "Entity", c => c.Id,
c => c.TimeStamp, c => c.PetName,
c => c.Color,
c => c.IsDrivable, c => c.MakeId,
c => c.Price
))
{
//do something interesting
}
}

However, the common practice is to declare the property used by the HTTP get method as a
BindProperty:

[BindProperty]
public Car Entity { get; set; }

This property will then be implicitly bound during HTTP post requests, and the
OnPost()/OnPostAsync() methods use the bound property:

public async Task OnPostAsync()
{
await _carDataService.UpdateAsync(Entity); return RedirectToPage("Index");
}

Razor Page Views
Razor Pages views are specific for a Razor PageModel, begin with the @page directive and are typed to the code behind file, like this for the scaffolded RazorSyntax page:

@page
@model AutoLot.Web.Pages.RazorSyntaxModel @{
}

Note that the view is not bound to the BindProperty (if one exists), but rather the PageModel derived class. The properties on the PageModel derived class (like the Entity property on the RazorSyntax page) are an extension of the @Model. To create the form necessary to test the different binding scenarios, add the following to the RazorSyntax.cshtml view, run the app, and navigate to https://localhost:5021/ RazorSyntax:

Razor Syntax

Note that the property doesn’t need to be a BindProperty to access the values in the view. It only needs to be a BindProperty for the HTTP post method to implicitly bind the values.
Just like with MVC based applications, HTML, CSS, JavaScript, and Razor all work together in Razor Page views. All of the basic Razor syntax explored in the previous chapter is supported in Razor Page views, including tag helpers and HTML helpers. The only difference is in referring to the properties on the model, as previously demonstrated. To confirm this, update the view by adding the following from the Chapter 33 example, with the changes in bold (for the full discussion on the syntax, please refer to the previous chapter):

Razor Syntax

@for (int i = 0; i < 15; i++)
{
//do something
}
@{
//Code Block
var foo = "Foo"; var bar = "Bar";
var htmlString = "

• one
• two

";
}
@foo
@htmlString
@foo.@bar
@foo.ToUpper()
@Html.Raw(htmlString)

@{
@:Straight Text

Lines without HTML tag

}

Email Address Handling:
foo@foo.com
@@foo
test@foo
test@(foo)
@
Multiline Comments Hi.
@
@functions {
public static IList SortList(IList strings) { var list = from s in strings orderby s select s;
return list.ToList();
}
}
@{
var myList = new List {"C", "A", "Z", "F"}; var sortedList = SortList(myList);
}
@foreach (string s in sortedList)
{
@s@: 
}

This will be bold: @b("Foo")

The Car named @Model.Entity.PetName is a @Model. Entity.Color@Model.Entity.MakeNavigation.Name

Display For examples Make:
@Html.DisplayFor(x=>x.Entity.MakeNavigation) Car:
@Html.DisplayFor(c=>c.Entity) @Html.EditorFor(c=>c.Entity)
Note the change in the last two lines. The _DisplayForModel()/EditorForModel() methods behave differently in Razor Pages since the view is bound to the PageModel, and not the entity/viewmodel like in MVC applications.

Razor Views
MVC style razor views (without a derived PageModel class as the code behind) and partial views are also supported in Razor Page applications. This includes the _ViewStart.cshtml, _ViewImports.cshtml (both in the \Pages directory) and the _Layout.cshtml files, located in the Pages\Shared directory. All three provide the same functionality as in MVC based applications. Layouts with Razor Pages will be covered shortly.

The _ViewStart and _ViewImports Views
The _ViewStart.cshtml executes its code before any other Razor Page view is rendered and is used to set the default layout. The _ViewStart.cshtml file is shown here:

@{
Layout = "_Layout";
}

The _ViewImports.cshtml file is used for importing shared directives, like @using statements. The contents apply to all views in the same directory or subdirectory of the _ViewImports file. This file is the view equivalent of a GlobalUsings.cs file for C# code.

@using AutoLot.Web @namespace AutoLot.Web.Pages
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

The @namespace declaration defines the default namespace where the application’s pages are located.

The Shared Directory
The Shared directory under Pages holds partial views, display and editor templates, and layouts that are available to all Razor Pages.

The DisplayTemplates Folder
Display templates work the same in MVC and Razor Pages. They are placed in a directory named DisplayTemplates and control how types are rendered when the DisplayFor() method is called. The search path starts in the Pages{CurrentPageRoute}\DisplayTemplates directory and, if it’s not found, it then looks in the Pages\Shared\DisplayTemplates folder. Just like with MVC, the engine looks for a template with the same name as the type being rendered or looks to a template that matches the name passed into the method.

The DateTime Display Template
Create a new folder named DisplayTemplates under the Pages\Shared folder. Add a new view named DateTime.cshtml into that folder. Clear out all of the generated code and comments and replace them with the following:

@model DateTime? @if (Model == null)
{
@:Unknown
}
else
{
if (ViewData.ModelMetadata.IsNullableValueType)
{
@:@(Model.Value.ToString("d"))
}
else
{
@:@(((DateTime)Model).ToString("d"))
}
}

Note that the @model directive that strongly types the view uses a lowercase m. When referring to the assigned value of the model in Razor, an uppercase M is used. In this example, the model definition is nullable. If the value for the model passed into the view is null, the template displays the word Unknown. Otherwise, it displays the date in Short Date format, using the Value property of a nullable type or the actual model itself.
With this template in place, if you run the application and navigate to the RazorSyntax page, you can see that the BuiltDate value is formatted as a Short Date.

The Car Display Template
Create a new directory named Cars under the Pages directory, and add a directory named DisplayTemplates under the Cars directory. Add a new view named Car.cshtml into that folder. Clear out all of the generated code and comments and replace them with the following code, which displays a Car entity:

@model AutoLot.Models.Entities.Car

@Html.DisplayNameFor(model => model.MakeId)

@Html.DisplayFor(model => model.MakeNavigation.Name)

@Html.DisplayNameFor(model => model.Color)

@Html.DisplayFor(model => model.Color)

@Html.DisplayNameFor(model => model.PetName)

@Html.DisplayFor(model => model.PetName)

@Html.DisplayNameFor(model => model.Price)

@Html.DisplayFor(model => model.Price)

@Html.DisplayNameFor(model => model.DateBuilt)

@Html.DisplayFor(model => model.DateBuilt)

@Html.DisplayNameFor(model => model.IsDrivable)

@Html.DisplayFor(model => model.IsDrivable)

The DisplayNameFor() HTML helper displays the name of the property unless the property is decorated with either the Display(Name="") or DisplayName("") attribute, in which case the display value is used. The DisplayFor() method displays the value for the model’s property specified in the expression. Notice that the navigation property for MakeNavigation is being used to get the make name.
To use a template from another directory structure, you have to specify the name of the view as well as the full path and file extension. To use this template on the RazorSyntax view, update the DisplayFor() method to the following:

@Html.DisplayFor(c=>c.Entity,"Cars/DisplayTemplates/Car.cshtml")

Another option is to move the display templates to the Pages\Shared\DisplayTemplates directory

The Car with Color Display Template
Copy the Car.cshtml view to another view named CarWithColors.cshtml in the Cars\DisplayTemplates directory. The difference is that this template changes the color of the Color text based on the model’s Color property value. Update the new template’s

The EditorTemplates Folder
The EditorTemplates folder works the same as the DisplayTemplates folder, except the templates are used for editing.

The Car Edit Template
Create a new directory named EditorTemplates under the Pages\Cars directory. Add a new view named Car.cshtml into that folder. Clear out all of the generated code and comments and replace them with the following code, which represents the markup to edit a Car entity:

@model Car

Editor templates are invoked with the EditorFor() HTML helper. To use this with the RazorSyntax
page, update the call to EditorFor() to the following:

@Html.EditorFor(c=>c.Entity,"Cars/EditorTemplates/Car.cshtml")

View CSS Isolation
Razor Pages also support CSS isolation. Right click on the \Pages directory, and select Add ➤ New Item, navigate to ASP.NET Core/Web/Content in the left rail, and select Style Sheet and name it Index.cshtml. css. Update the content to the following:

h1 {
background-color: blue;
}

This change makes the tag on the Index Razor Page blue but doesn’t affect any other pages.
The same rules apply in Razor Pages as MVC with view CSS isolation: the CSS file is only generated when running in Development or when the site is published. To see the CSS in other environments, you have to opt-in:

//Enable CSS isolation in a non-deployed session if (!builder.Environment.IsDevelopment())
{
builder.WebHost.UseWebRoot("wwwroot"); builder.WebHost.UseStaticWebAssets();
}

Layouts
Layouts in Razor Pages function the same as they do in MVC applications, except they are located in Pages\Shared and not Views\Shared. _ViewStart.cshtml is used to specify the default layout for a directory structure, and Razor Page views can explicitly define their layout using a Razor block:

@{
Layout = "_MyCustomLayout";
}

Injecting Data
Add the following to the top of the _Layout.cshtml file, which injects the IWebHostEnvironment: @inject IWebHostEnvironment _env

Next, update the footer to show the environment that the application is currently running in:

© 2021 - AutoLot.Web - @_env.EnvironmentName - Privacy

Partial Views
The main difference with partial views in Razor Pages is that a Razor Page view can’t be rendered as a partial. In Razor Pages, they are used to encapsulate UI elements and are loaded from another view or a view component. Next, we are going to split the layout into partials to make the markup easier to maintain.

Create the Partials
Create a new directory named Partials under the Shared directory. Right click on the new directory and select Add ➤ New Item. Enter Razor View in the search box and select Razor View -Empty. Create three empty views named _Head.cshtml, _JavaScriptFiles.cshtml, and _Menu.cshtml.
Cut the content in the layout that is between the tags and paste it into the _Head.cshtml
file. In _Layout.cshtml, replace the deleted markup with the call to render the new partial:

For the menu partial, cut all the markup between the

tags (not the
tags) and paste it into the _Menu.cshtml file. Update the _Layout to render the Menu partial.

The final step at this time is to cut out the

The final change is to update the location of jquery.validation and add the and

Add and Configure WebOptimizer
Open the Program.cs file in the AutoLot.Web project and add the following line (just before the app. UseStaticFiles() call):

app.UseWebOptimizer();

The next step is to configure what to minimize and bundle. The open source libraries already have the minified versions downloaded through Library Manager, so the only files that need to be minified are the project specific files, including the generated CSS file if you are using CSS isolation. In the Program.cs file, add the following code block before var app = builder.Build():

if (builder.Environment.IsDevelopment() || builder.Environment.IsEnvironment("Local"))
{
builder.Services.AddWebOptimizer(false,false);
/*
builder.Services.AddWebOptimizer(options =>
{

});
*/
}

options.MinifyCssFiles("AutoLot.Web.styles.css"); options.MinifyCssFiles("css/site.css"); options.MinifyJsFiles("js/site.js");

else
{
builder.Services.AddWebOptimizer(options =>
{
options.MinifyCssFiles("AutoLot.Web.styles.css"); options.MinifyCssFiles("css/site.css"); options.MinifyJsFiles("js/site.js");
});
}

In the development scope, the code is setup for you to comment/uncomment the different options so you can replicate the production environment without switching to production.
The final step is to add the WebOptimizer tag helpers into the system. Add the following line to the end of the _ViewImports.cshtml file:

@addTagHelper *, WebOptimizer.Core

Tag Helpers
Razor Pages views (and layout and partial views) also support Tag helpers. They function the same as in MVC applications, with only a few differences. Any tag helper that is involved in routing uses page-
centric attributes instead of MVC centric attributes. Table 34-1 lists the tag helpers that use routing, their corresponding HTML helper, and the available Razor Page attributes. The differences will be covered in detail after the table.

Table 34-1. Commonly Used Built-in Tag Helpers

Tag Helper HTML Helper Available Attributes
Form Html.BeginForm Html.BeginRouteForm Html.AntiForgeryToken asp-route—for named routes (can’t be used with controller, page, or action attributes).asp-antiforgery—if the antiforgery should be added (true by default).asp-area—the name of the area.asp- route-—adds the parameter to the route, e.g., asp-route-id="1".asp-page—the name of the Razor Page.asp- page-handler—the name of the Razor Page handler.asp-all- route-data—dictionary for additional route values.
Form Action (button
or input type=image) N/A Asp-route—for named routes (can’t be used with controller, page, or action attributes).asp-antiforgery—if the antiforgery should be added (true by default).asp-area—the name of the area. asp- route-—adds the parameter to the route, e.g., asp-route-id="1".asp-page—the name of the Razor Page.asp- page-handler—the name of the Razor Page handler.asp-all- route-data—dictionary for additional route values.
Anchor Html.ActionLink asp-route—for named routes (can’t be used with controller, page, or action attributes). asp-area—the name of the area. asp- protocol—HTTP or HTTPS.asp-fragment—URL fragment.asp- host—the host name.asp-route-—adds the parameter to the route, e.g., asp-route-id="1".
asp-page—the name of the Razor Page.
asp-page-handler—the name of the Razor Page handler.asp- all-route-data—dictionary for additional route values.

Enabling Tag Helpers
Tag helpers must be enabled in your project in the _ViewImports.html file by adding the following line (which was added by the default template):

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

The Form Tag Helper
With Razor Pages, the

Another option available is to specify the name of the page handler method. When modifying the name, the format On() (OnPostCreateNewCar()) or OnAsync() (OnPostCreateNewCarAsync()) must be followed. With the HTTP post method renamed, the handler method is specified like this:

All Razor Page HTTP post handler methods automatically check for the antiforgery token, which is added whenever a tag helper is used.

The Form Action Button/Image Tag Helper
The form action tag helper is used on buttons and images to change the action for the form that contains them and supports the asp-page and asp-page-handler attributes in the same manner as the

CHAPTER 32

RESTful Services with ASP.NET Core

The previous chapter introduced ASP.NET Core. After that introduction to the new features and implementing some cross cutting concerns, in this chapter, we will complete the AutoLot.Api RESTful service.

■Note The sample code for this chapter is in the Chapter 32 directory of this book’s repo. Feel free to continue working on the solution you started in Chapter 31.

Introducing ASP.NET Core RESTful Services
The ASP.NET MVC framework started gaining traction almost immediately upon release, and Microsoft released ASP.NET Web API with ASP.NET MVC 4 and Visual Studio 2012. ASP.NET Web API 2 was released with Visual Studio 2013 and then was updated to version 2.2 with Visual Studio 2013 Update 1.
From the beginning, ASP.NET Web API was designed to be a service-based framework for building REpresentational State Transfer (RESTful) services. It is based on the MVC framework minus the V (view), with optimizations for creating headless services. These services can be called by any technology, not just those under the Microsoft umbrella. Calls to a Web API service are based on the core HTTP verbs (Get, Put, Post, Delete) through a uniform resource identifier (URI) such as the following:

http://www.skimedic.com:5001/api/cars

If this looks like a uniform resource locator (URL), that’s because it is! A URL is simply a URI that points to a physical resource on a network.
Calls to Web API use the Hypertext Transfer Protocol (HTTP) scheme on a particular host (in this example, www.skimedic.com) on a specific port (5001 in the preceding example), followed by the path (api/ cars) and an optional query and fragment (not shown in this example). Web API calls can also include text in the body of the message, as you will see throughout this chapter. As discussed in the previous chapter, ASP.NET Core unified Web API and MVC into one framework.

© Andrew Troelsen, Phil Japikse 2022
A. Troelsen and P. Japikse, Pro C# 10 with .NET 6, https://doi.org/10.1007/978-1-4842-7869-7_32

1407

Controller Actions with RESTful Services
Recall that actions return an IActionResult (or Task for async operations). In addition to the helper methods in ControllerBase that return specific HTTP status codes, action methods can return content as formatted JavaScript Object Notation (JSON) responses.

■Note Strictly speaking, action methods can return a wide range of formats. JSON is covered in this book because it is the most common.

Formatted JSON Response Results
Most RESTful APIs receive data from, and send data back to, clients using JSON (pronounced “jay-sawn”). A simple JSON example, consisting of two values, is shown here:

[
"value1", "value2"
]

■Note Chapter 19 covers JSON serialization in depth using System.Text.Json.

APIs also use HTTP status codes to communicate success or failure. Some of the HTTP status helper methods available in the ControllerBase class were listed in the Chapter 30 in Table 30-3. Successful requests return status codes in the 200 range, with 200 (OK) being the most common success code. In fact, it is so common that you don’t have to explicitly return an OK. If there isn’t an exception thrown and the code does not specify a status code, a 200 will be returned to the client along with any data.
To set up the following examples (and the rest of this chapter), add the following to the GlobalUsing.cs file:

global using Microsoft.AspNetCore.Mvc;

Next, add a new controller named ValuesController.cs in the Controllers directory of the AutoLot.
Api project and update the code to match the following:

[Route("api/[controller]")] [ApiController]
public class ValuesController : ControllerBase
{
}

■Note If using Visual Studio, there is a scaffolder for controllers. To access this, right-click the Controllers folder in the AutoLot.Api project and select Add ➤ Controller. Select Common ➤ API in the left rail and then API Controller – Empty.

This code sets the route for the controller using a literal (api) and a token ([controller]). This route template will match URLs like www.skimedic.com/api/values. The next attribute (ApiController) opts in to several API-specific features in ASP.NET Core (covered in the next section). Finally, the controller inherits from ControllerBase. As discussed previously, ASP.NET Core rolled all of the different controller types available in classic ASP.NET into one, named Controller, with a base class ControllerBase. The
Controller class provides view-specific functionality (the V in MVC), while ControllerBase supplies all the rest of the core functionality for MVC-style applications.
There are several ways to return content as JSON from an action method. The following examples all return the same JSON along with a 200 status code. The differences are largely stylistic. Add the following code to your ValuesController class:

[HttpGet]
public IActionResult Get()
{
return Ok(new string[] { "value1", "value2" });
}
[HttpGet("one")]
public IEnumerable Get1()
{
return new string[] { "value1", "value2" };
}
[HttpGet("two")]
public ActionResult<IEnumerable> Get2()
{
return new string[] { "value1", "value2" };
}
[HttpGet("three")] public string[] Get3()
{
return new string[] { "value1", "value2" };
}
[HttpGet("four")]
public IActionResult Get4()
{
return new JsonResult(new string[] { "value1", "value2" });
}

To test this, run the AutoLot.Api application, and you will see all the methods from ValuesController listed in the Swagger UI, as shown in Figure 32-1. Recall that when determining routes, the Controller suffix is dropped from the name, so the endpoints on the ValuesController are mapped as Values, not ValuesController.

Figure 32-1. The Swagger documentation page

To execute one of the methods, click the Get button, the Try it out button, and then the Execute button.
Once the method has executed, the UI is updated to show the results, with just the relevant portion of the Swagger UI shown in Figure 32-2.

Figure 32-2. The Swagger server response information

You will see that executing each method produces the same JSON results.

Configuring JSON Handling
The AddControllers() method can be extended to customize JSON handling. The default for ASP.NET Core is to camel case JSON (first letter small, each subsequent word character capitalized like “carRepo”). This matches most of the non-Microsoft frameworks used for web development. However, prior versions of ASP. NET used Pascal casing (first letter small, each subsequent word character capitalized like “CarRepo”). The change to camel casing was a breaking change for many applications that were expecting Pascal casing.
There are two serialization properties that can be set that help with this issue. The first is to make the JSON Serializer use Pascal casing by setting its PropertyNamingPolicy to null instead of JsonNamingPolicy. CamelCase. The second change is to use case insensitive property names. When this option is enabled, JSON coming into the app can be Pascal or camel cased. To make these changes, call AddJsonOptions() on the AddControllers() method:

builder.Services.AddControllers()
.AddJsonOptions(options =>
{
options.JsonSerializerOptions.PropertyNamingPolicy = null; options.JsonSerializerOptions.PropertyNameCaseInsensitive = true;
});

The next change is to make sure the JSON is more readable by writing it indented:

.AddJsonOptions(options =>
{
options.JsonSerializerOptions.PropertyNamingPolicy = null; options.JsonSerializerOptions.PropertyNameCaseInsensitive = true; options.JsonSerializerOptions.WriteIndented = true;
});

Before making the final change, add the following global using to the GlobalUsings.cs file:

global using System.Text.Json.Serialization;

The final change (new to .NET 6) is to have the JSON serializer ignore reference cycles:

.AddJsonOptions(options =>
{
options.JsonSerializerOptions.PropertyNamingPolicy = null; options.JsonSerializerOptions.PropertyNameCaseInsensitive = true; options.JsonSerializerOptions.WriteIndented = true; options.JsonSerializerOptions.ReferenceHandler = ReferenceHandler.IgnoreCycles;
});

The ApiController Attribute
The ApiController attribute, added in ASP.NET Core 2.1, provides REST-specific rules, conventions, and behaviors when combined with the ControllerBase class. These conventions and behaviors are outlined in the following sections. It’s important to note that this works in base class scenarios as well. For example, if you have a custom base class decorated with the ApiController attribute, any derived controllers will behave as if the attribute is applied directly to them.

[ApiController]
public abstract class BaseCrudController : ControllerBase
{
}

//ApiController attribute is implicitly implied on this controller as well public class CarsController : BaseCrudController
{
}

Lastly, the attribute can be applied at the assembly level, which then applies the attribute to every controller in the project. To apply the attribute to every controller in the project, add the following attribute to the top of the Program.cs file:

[assembly: ApiController]

Attribute Routing Requirement
When using the ApiController attribute, the controller must use attribute routing. This is just enforcing what many consider to be a best practice.

Automatic 400 Responses
If there is an issue with model binding, the action will automatically return an HTTP 400 (Bad Request) response code. This behavior is equivalent to the following code:

if (!ModelState.IsValid)
{
return BadRequest(ModelState);
}

ASP.NET Core uses the ModelStateInvalidFilter action filter to do the preceding check. When there is a binding or a validation error, the HTTP 400 response in the body includes details for the errors, which is a serialized instance of the ValidationProblemDetails class, which complies with the RFC 7807 specification (https://datatracker.ietf.org/doc/html/rfc7807). This class derives from HttpProblemDetails, which derives from ProblemDetails. The entire hierarchy chain for the classes is shown here:

public class ProblemDetails
{
public string? Type { get; set; } public string? Title { get; set; } public int? Status { get; set; } public string? Detail { get; set; } public string? Instance { get; set; }
public IDictionary<string, object?> Extensions { get; } = new Dictionary<string, object?>(StringComparer.Ordinal);
}

public class HttpValidationProblemDetails : ProblemDetails
{
public IDictionary<string, string[]> Errors { get; } = new Dictionary<string, string[]>(StringComparer.Ordinal);
}

public class ValidationProblemDetails : HttpValidationProblemDetails
{
public new IDictionary<string, string[]> Errors => base.Errors;
}

To see the automatic 400 error handling in action, update the ValuesController.cs file with the following HTTP Post action:

[HttpPost]
public IActionResult BadBindingExample(WeatherForecast forecast)
{
return Ok(forecast);
}

Run the app, and on the Swagger page, click the POST version of the /api/Values end point, click Try it out, but before clicking Execute, clear out the autogenerated request body. This will cause a binding failure, and return the following error details:

{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1", "title": "One or more validation errors occurred.", "status": 400,
"traceId": "00-2c35757698267491ad0a8554ac51ccd1-dbdfe43357cd6d3f-00", "errors": {
"": [
"A non-empty request body is required.”
]
}
}

This behavior can be disabled through configuration in the ConfigureServices() method of the
Startup.cs class.

Services.AddControllers()
.AddJsonOptions( / omitted for brevity /)
.ConfigureApiBehaviorOptions(options =>
{
//suppress automatic model state binding errors
options.SuppressModelStateInvalidFilter = true;
});

When disabled, you can still send error information as an instance of ValidationProblemDetails.
Update the top level statements to disable the automatic 400 response, and then update the
BadBindingExample() action method to the following:

[HttpPost]
public IActionResult BadBindingExample(WeatherForecast forecast)
{
return ModelState.IsValid ? Ok(forecast) : ValidationProblem(ModelState);
}

When you run the app and execute the BadBindingExample() code, you will see that the response contains the same JSON as the automatically handled error.

Binding Source Parameter Inference
The model binding engine will infer where the values are retrieved based on the conventions listed in Table 32-1.

Table 32-1. Binding Source Inference Conventions

Source Parameters Bound
FromBody Inferred for complex type parameters except for built-in types with special meaning, such as IFormCollection or CancellationToken. Only one FromBody parameter can exist, or an
exception will be thrown. If binding is required on a simple type (e.g., string or int), then the
FromBody attribute is still required.
FromForm Inferred for action parameters of types IFormFile and IFormFileCollection. When a parameter is marked with FromForm, the multipart/form-data content type is inferred.
FromRoute Inferred for any parameter name that matches a route token name.
FromQuery Inferred for any other action parameters.

This behavior can be disabled through configuration in the ConfigureServices() method of the
Startup.cs class.

Services.AddControllers().ConfigureApiBehaviorOptions(options =>
{
//suppress all binding inference
options.SuppressInferBindingSourcesForParameters= true;
//suppress multipart/form-data content type inference
options. SuppressConsumesConstraintForFormFileParameters = true;
});

Problem Details for Error Status Codes
ASP.NET Core transforms an error result (status of 400 or higher) into a result of the same ProblemDetails
shown earlier. To test this behavior, add another method to the ValuesController as follows:

[HttpGet("error")]
public IActionResult Error()
{
return NotFound();
}

Run the app and use the Swagger UI to execute the new Error endpoint. The result is still a 404 (NotFound) status code, but additional information is returned in the body of the response. The following shows an example response (your traceId will be different):

{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4", "title": "Not Found",
"status": 404,
"traceId": "00-42432337d88a53a2f38bc0ab0e473f89-63d4e7b153a30b2d-00"
}

This behavior can be disabled through configuration in the ConfigureServices() method of the
Startup.cs class.

services.AddControllers()
.ConfigureApiBehaviorOptions(options =>
{
//omitted for brevity
/’Don't create a problem details error object if set to true
options.SuppressMapClientErrors = true;
});

When the behavior is disabled, the call to the Error endpoint returns a 404 without any additional information.
When there is a client error (and the mapping of client errors is not suppressed), the Link and the Title text can be set to custom values that are more user friendly. For example, 404 errors can change the ProblemDetails Link to https://httpstatuses.com/404 and the Title to “Invalid Location” with the following code:

services.AddControllers()
.ConfigureApiBehaviorOptions(options =>
{
/’Don't create a problem details error object if set to true options.SuppressMapClientErrors = false; options.ClientErrorMapping[StatusCodes.Status404NotFound].Link =
"https://httpstatuses.com/404"; options.ClientErrorMapping[StatusCodes.Status404NotFound].Title =
"Invalid location";
});

This updates the return values to the following:

{
"type": "https://httpstatuses.com/404", "title": "Invalid location",
"status": 404,
"traceId": "00-e4cf79ad92807354bcc1f1bbe0faf92a-6b6a9d0578c15a77-00"
}

Reset the Settings
After you have completed testing the different options, update the code to the settings used in the rest of this chapter (and book), listed here:

builder.Services.AddControllers()
.AddJsonOptions(/omitted for brevity/)
.ConfigureApiBehaviorOptions(options =>
{
//suppress automatic model state binding errors options.SuppressModelStateInvalidFilter = true;
//suppress all binding inference
//options.SuppressInferBindingSourcesForParameters= true;
//suppress multipart/form-data content type inference
//options. SuppressConsumesConstraintForFormFileParameters = true; options.SuppressMapClientErrors = false;

options.ClientErrorMapping[StatusCodes.Status404NotFound].Link = "https://httpstatuses.com/404"; options.ClientErrorMapping[StatusCodes.Status404NotFound].Title = "Invalid location";
});

API Versioning
When building APIs, it’s important to remember that humans don’t interact with your end points, programs do. If an application UI changes, people can usually figure out the changes and keep on using your application. If an API changes, the client program just breaks. If your API is public facing, has more than one client, or you plan on making a change, you should add versioning support.

Microsoft’s REST API Guidelines
Microsoft has published guidelines for REST APIs (located at https://github.com/Microsoft/api- guidelines/blob/vNext/Guidelines.md) and that guidance contains a section on versioning. In order to be compliant with the guidelines, APIs must support explicit versioning.
API versions are comprised of a major version and a minor version and are reported/requested as Major.Minor, such as 1.0, 1.5, etc. If the minor version is zero, it can be left off. In other words, 1 is the same as 1.0. In addition to the major and minor version, a status can be added to the end of the version to indicate a version not yet production quality, such as 1.0-Beta or 1.0.Beta. Note that the status can be separated either by a period or a dash. When a version has a minor version of zero and a status, then the version can
be specified as Major.Minor-Status (1.0-Beta) or Major-Status (1-Beta), using either dash or a period as the status separator).
In addition to Major.Minor-Status versions, there is also a group format that is an optional feature that is supported through non URL segment versioning. The group version format is defined as YYYY-MM-DD. The group format should not replace Major.Minor-Status versioning.
There are two options to specify the version in an API call, embedded in the URL (at the end of the service root), or as a query string parameter at the end of the URL. The following examples show calls to the version 1.0 API for the AutoLot.Api (presuming the host is skimedic.com):

www.skimedic.com/api/v1.0/cars www.skimedic.com/api/cars?api-version=1.0

The following two examples call the same endpoint without specifying the minor version (since the minor version is zero):

www.skimedic.com/api/v1/cars www.skimedic.com/api/cars?api-version=1

While APIs can use either URL embedding or query string parameters, the guidelines require that APIs be consistent. In other words, don’t have some end points that use query strings and others that use URL embedding. It is permissible for all of the endpoints to support both methods.

■Note The guidelines are definitely worth reading as you build .NET Core rESTful services. Again, the guideline can be read at https://github.com/Microsoft/api-guidelines/blob/vNext/ Guidelines.md

Add Versioning NuGet Packages
To add full support for ASP.NET Core versioning, there are two NuGet packages that need to be added into your API projects. The first is the Microsoft.AspNetCore.Mvc.Versioning package which provides the version attributes, the AddApiVersioning() method, and the ApiVersion class. The second is the Microsoft.
AspNetCore.Mvc.Versioning.Explorer NuGet package, which makes the AddVersionedApiExplorer() method available. Both of these packages were added to AutoLot.Api when the projects and solution were created.
For the rest of this section, add the following global using statements into the GlobalUsings.cs

global using Microsoft.AspNetCore.Mvc.ApiExplorer; global using Microsoft.AspNetCore.Mvc.Versioning;

The ApiVersion Class
The ApiVersion class is the heart of API versioning support. It provides the container to hold the major and minor version and optional group and status information. It also provides methods to parse strings into ApiVersion instances and output properly formatted version string and overloads for equality and comparison operations. The class is listed here for reference.

public class ApiVersion
{
//Constructors allowing for all combinations of group and versions
public ApiVersion( DateTime groupVersion )
public ApiVersion( DateTime groupVersion, string status ) public ApiVersion( int majorVersion, int minorVersion )
public ApiVersion( int majorVersion, int minorVersion, String? status )
public ApiVersion( DateTime groupVersion, int majorVersion, int minorVersion )
public ApiVersion( DateTime groupVersion, int majorVersion, int minorVersion, String? status)
//static method to return the same as ApiVersion(1,0)
public static ApiVersion Default { get; }
//static method to return ApiVersion(null,null,null,null)
public static ApiVersion Neutral { get; }
//Properties for the version information public DateTime? GroupVersion { get; } public int? MajorVersion { get; }
public int? MinorVersion { get; } //(defaults to zero if null)
public string? Status { get; }
//checks the status for valid format (all alpha-numeric, no special characters or spaces)
public static bool IsValidStatus( String? status )
//Parsing strings into ApiVersion instances
public static ApiVersion Parse( string text )
public static bool TryParse( string text, [NotNullWhen( true )] out ApiVersion? version )
//Output properly formatted version string
public virtual string ToString( string format ) => ToString( format, InvariantCulture ); public override string ToString() => ToString( null, InvariantCulture );
//Equality overrides to quickly compare two versions
public override bool Equals( Object? obj ) => Equals( obj as ApiVersion ); public static bool operator ==( ApiVersion? version1, ApiVersion? version2 ) => public static bool operator !=( ApiVersion? version1, ApiVersion? version2 ) => public static bool operator <( ApiVersion? version1, ApiVersion? version2 ) =>

public static bool operator <=( ApiVersion? version1, ApiVersion? version2 ) => public static bool operator >( ApiVersion? version1, ApiVersion? version2 ) => public static bool operator >=( ApiVersion? version1, ApiVersion? version2 ) => public virtual bool Equals( ApiVersion? other ) => other != null && GetHashCode public virtual int CompareTo( ApiVersion? other )
}

Add API Version Support
The root of version support is added with the AddApiVersioning() method. This is a mega method that adds in a host of services into the DI container. To add standard API versioning support into the AutoLot.Api project, call this method on the IServiceCollection, like this (no need to add this to the Program.cs file at this time, as it will be done with an extension method shortly):

builder.Services.AddApiVersioning();

For more robust version support, the version support can be configured with the ApiBehaviorOptions class. Before using this, let’s add an extension method to hold all of the version configuration code. Start by creating a new folder named ApiVersionSupport into the project. In this folder, add a new public static class named ApiVersionConfiguration.
Namespace AutoLot.Api.ApiVersionSupport; public static class ApiVersionConfiguration
{
//implementation goes here
}

Add the new namespace to the GlobalUsings.cs file:

global using AutoLot.Api.ApiVersionSupport;

Add an extension method for the IServiceCollection that also takes in an ApiVersion object that will be used to set the default version. If a default version isn’t specified, create a new instance of the ApiVersion object with the version set to 1.0:

public static IServiceCollection AddAutoLotApiVersionConfiguration( this IServiceCollection services, ApiVersion defaultVersion = null)
{
defaultVersion ??= ApiVersion.Default;
//remaining implementation goes here return services;
}

Next, add in the call to AddApiVersioning() after the if statement for the default version:

if (defaultVersion == null)
{
defaultVersion = ApiVersion.Default;
}
services.AddApiVersioning();

This method takes an optional Action that can be used to configure all of the version options. Before adding the options, let’s examine what’s available. Table 32-2 lists the available options for versioning:

Table 32-2. The APIVersioningOptions properties

Option Meaning in Life
RouteConstraintName The route token when using URL versioning. Defaults to
apiVersion.
ReportApiVersions Indicates if system version information is sent in HTTP responses. When true, the HTTP headers api-supported- versions and api-deprecated-versions are added for all valid service routes. Defaults to false.
AssumeDefaultVersionWhenUnspecified If set to true, uses the default API version when version information is not specified in the request. Version is based on the result of the call IApiVersionSelector.SelectVersion(). Defaults to false.
DefaultApiVersion Sets the default API version to use when version information is not specified in the request and AssumeDefaultVersionWhenUnspecified is set to true. The default is ApiVersion.Default (1.0).
ApiVersionReader Gets or sets the ApiVersionReader to use. Can use QueryStringApiVersionReader, HeaderApiVersionReader, MediaTypeApiVersionReader, UrlSegmentApIVersionReader. The default is QueryStringApiVersionReader.
ApiVersionSelector Gets or sets the ApiVersionSelector. Defaults to
DefaultApiVersionSelector.
UseApiBehavior When true, API versioning policies only apply to controllers that have the ApiController attribute. Defaults to true.

Now that you understand the available options you can update the call to AddApiVersioning().
The following code first sets the default version from the parameter (or uses the default 1.0 version if the parameter is null). Then it sets the flag to use the default version if the client didn’t specify a version. Next it filters out controllers without the ApiController attribute, reports the supported API versions in response headers. The final block enables all methods available for clients to specify the version in requests (make sure to comment out the original call to add versioning):

public static IServiceCollection AddAutoLotApiVersionConfiguration( this IServiceCollection services, ApiVersion defaultVersion = null)
{
if (defaultVersion == null)
{
defaultVersion = ApiVersion.Default;
}
//services.AddApiVersioning();

services.AddApiVersioning( options =>
{
//Set Default version options.DefaultApiVersion = defaultVersion;
options.AssumeDefaultVersionWhenUnspecified = true; options.UseApiBehavior = true;
// reporting api versions will return the headers "api-supported-versions"
// and "api-deprecated-versions" options.ReportApiVersions = true;
//This combines all of the avalialbe option as well as
// allows for using "v" or "api-version" as options for
// query string, header, or media type versioning options.ApiVersionReader = ApiVersionReader.Combine(
new UrlSegmentApiVersionReader(),
new QueryStringApiVersionReader(), //defaults to "api-version" new QueryStringApiVersionReader("v"),
new HeaderApiVersionReader("api-version"), new HeaderApiVersionReader("v"),
new MediaTypeApiVersionReader(), //defaults to "v" new MediaTypeApiVersionReader("api-version")
);
});
//remaining implementation goes here return services;
}

The previous code sample enables all of the available ApiVersionReader options. As you can see, each of the non-URL segment options are specified twice. The first call for each pair enables the reader that uses api-version as the key. The second call takes a parameter into the constructor that instructs the
reader to look for a custom key, in these examples, the simple key of v is accepted. When building real world
applications, you probably wouldn’t want to enable all of these options, they are shown here as an example of different reader configurations.

Update the Top Level Statements
The next step is to add the extension method to the top level statements in the Program.cs file. Add the call to the extension method into file right after the AddEndpointApiExplorer() (which adds in the ApiDescriptionProvider for end points):

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddAutoLotApiVersionConfiguration(new ApiVersion(1, 0));

API Versions and Naming Convention Updates
When API versioning is enabled, controllers can be named with their version included, and it will be stripped off just like the Controller suffix. This means that you can have ValuesController and
Values2Controller in your project, and the route for both is mysite.com/api/Values. It’s important to
understand that the number in the name has no relation on the actual version served by the controller,

it’s merely an update to the convention so you can separate controller classes by version and still have the same route.

The API Version Attributes
Now that versioning support is enabled, you can start decorating your controllers and action methods with version attributes. Table 32-3 lists the available attributes.

Table 32-3. API Versioning Attributes

Attribute Meaning in Life

ApiVersion Controller or Action level attribute that sets the API version that the controller/ action method will accept. Can be used multiple times to indicate more than one version is accepted. Versions in ApiVersion attributes are discoverable.
ApiVersionNeutral Controller level attribute that opts out of versioning. Query string version requests are ignored. Any well-formed URL when using URL versioning will be accepted, even if the placeholder represents an invalid version.
MapToApiVersion Action level attribute that maps the action to a specific version when multiple versions are specified at the controller level. Versions in MapToApiVersion attributes aren’t discoverable.
AdvertiseApiVersions Advertises additional versions beyond what is contained in the app instance.
Used when API versions are split across deployments and API information can’t be aggregated through the API Version Explorer.

It's important to understand that once versioning is enabled, it’s enabled for all API controllers. If a controller doesn’t have a version specified, it will use the default version (1.0 in the current configuration). To test this, run the application and run the following CURL commands, all of which produce the same result (recall that omitting the minor version is the same as specifying zero):

curl -G https://localhost:5011/WeatherForecast
curl -G https://localhost:5011/WeatherForecast?api-version=1 curl -G https://localhost:5011/WeatherForecast?api-version=1.0

Now, update the call to this:

curl -G https://localhost:5011/WeatherForecast?api-version=2.0

When asking for version 2.0, the return value shows that it’s an unsupported version:

{"error":{"code":"UnsupportedApiVersion","message":"The HTTP resource that matches the request URI 'https://localhost:5011/WeatherForecast' does not support the API version '2.0'.","innerError":null}}

To change the weather forecast endpoint to be available regardless of requested version, update the controller with the [ApiVersionNeutral] attribute:

[ApiVersionNeutral] [ApiController] [Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
//omitted for brevity
}

Now, regardless of the version requested (or no version requested), the forecast is returned.

Version Interleaving
A controller and/or action method can support more than one version, which is referred to as version interleaving. Let’s start by updating the ValuesController to specifically support version 1.0:

[ApiVersion("1.0")] [ApiController] [Route("api/[controller]")]
public class ValuesController : ControllerBase
{
//omitted for brevity
}

If you want the ValuesController to also support version 2.0, you can simply stack another
ApiVersion attribute. The following change updates the controller and all of its methods to support version
1.0 and version 2.0:

[ApiVersion("1.0")]
[ApiVersion("2.0")] [ApiController] [Route("api/[controller]")]
public class ValuesController : ControllerBase
{
//omitted for brevity
}

Now, suppose you want to add a method to this controller that wasn’t in version 1.0. There are two way to do this. The first is to add the method into the controller and use the ApiVersion attribute:

[HttpGet("{id}")]
[ApiVersion("2.0")]
public IActionResult Get(int id)
{
return Ok(new[] { "value1", "value2" });
}

The other option is to use the MapToApiVersion attribute, like this:

[HttpGet("{id}")] [MapToApiVersion("2.0")]
public IActionResult Get(int id)
{
return Ok(new[] { "value1", "value2" });
}

The difference between the two is very subtle, but important. In both instances, the /api/ Values/1?api-version=2.0 route will hit the end point. However, versions in MapToApiVersion attributes aren’t reported if they don’t already exist in an ApiVersion attribute. To demonstrate, comment out the [ApiVersion("2.0")] attribute, then hit the endpoint with the following CURL:

curl -G https://localhost:5011/api/Values/1?api-version=2.0 -i

The -i adds the response headers to the output. As you can see from the following output, even though the call was successful, only version 1.0 is reported:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; v=2.0 Date: Thu, 11 Nov 2021 05:29:10 GMT
Server: Kestrel
Transfer-Encoding: chunked api-supported-versions: 1.0 ["values1","value2"]

Replace the [MapToApiVersion("2.0")] attribute on the Get(int id) method with the [ApiVersion("2.0")] attribute and run the same command. You will now see that both version 1.0 and 2.0 are reported in the headers as supported versions.

Controller Splitting
While version interleaving is fully supported by the tooling, it can lead to very messy controllers that become difficult to support over time. A more common approach is to use controller splitting. Leave all of the version
1.0 action methods in the ValuesController, but create a Values2Controller to hold all of the version 2.0
methods, like this:

[ApiVersion("2.0")] [ApiController] [Route("api/[controller]")]
public class Values2Controller : ControllerBase
{
[HttpGet("{id}")]
public IActionResult Get(int id)
{
return Ok(new[] { "value1", "value2" });

}
}

[ApiVersion("1.0")] [ApiController] [Route("api/[controller]")]
public class ValuesController : ControllerBase
{
//omitted for brevity
}

As discussed with the updated naming conventions, both controllers base routes are defined as /api/ Values. The separation doesn’t affect the exposed API, just provides a mechanism to clean up the code base.

Query String Version Requests and Routing
API versions (except with URL segment routing) come into play when a route is ambiguous. If a route is serviceable from two endpoints, the selection process will look for an explicit API version that matches the requested version. If an explicit match is not found, an implicit match is searched. If no match is found, then the route will fail.
As an example, the following two Get() methods are serviced by the same route of /api/Values:

[ApiVersion("2.0")] [ApiController] [Route("api/[controller]”)]
public class Values2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok(new[] { "Version2:value1", "Version2:value2" });
}
}

[ApiVersion("1.0")] [ApiController] [Route("api/[controller]")]
public class ValuesController : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok(new[] { "value1", "value2" });
}
}

If you run the app and execute the following two CURL commands, they behave as expected:

curl -G https://localhost:5011/api/Values?api-version=1.0 -i curl -G https://localhost:5011/api/Values?api-version=2.0 -i

If you take the version information out of either request, it will execute the ValuesController version since version 1.0 is the default. However, if you update the Values2Controller’s attributes by adding the [ApiVersion("1.0")] attribute, the request fails with the following error:

//Updated attributes for Values2Controller [ApiVersion("1.0")]
[ApiVersion("2.0")] [ApiController] [Route("api/[controller]")]
public class Values2Controller : ControllerBase

//Error returned from CURL request (just the relevant part of the message) Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException: The request matched multiple endpoints. Matches:

AutoLot.Api.Controllers.Values2Controller.Get (AutoLot.Api) AutoLot.Api.Controllers.ValuesController.Get (AutoLot.Api)

Attribute Precedence
As previously stated, the ApiVersion attribute can be used at the controller or action level. The previous routing example, with duplicate [ApiVersion("1.0")] attributes at the controller level, failed due to an ambiguous match. Update the Values2Controller to move the [ApiVersion("1.0")] attribute to the Get() method like this:

[ApiVersion("2.0")] [ApiController] [Route(“api/[controller]")]
public class Values2Controller : ControllerBase
{
//omitted for brevity [ApiVersion("1.0")] [HttpGet]
public IActionResult Get()
{
return Ok(new[] { "Version2:value1", "Version2:value2" });
}
}

With this change, executing the CURL that is requesting the version 1.0 Get() method succeeds and returns the values from the Values2Controller. This is due to the order of precedence for the ApiVersion attribute. When applied at the controller level, the version specified is implicitly applied to all of the action methods in the controller. When the attribute is applied at the action level, the version is explicitly applied to the method. As discussed previously, explicit versions take precedence over implicit versions. As a final step, remove the [ApiVersion("1.0")] from the Values2Controller’s Get action method.

Getting the API Version in Requests
When using version interleaving, it might be important to know the requested version. Fortunately, this is a simple endeavor. There are two methods to get the requested version. The first is calling the
GetRequestedApiVersion() method on the HttpContext, and the second (introduced in ASP.NET Core 3.0) is to use model binding. Both are shown here in the updated Get() method in the Values2Controller:

[HttpGet("{id}")]
public IActionResult Get(int id, ApiVersion versionFromModelBinding)
{
var versionFromContext = HttpContext.GetRequestedApiVersion();
return Ok(new[] { versionFromModelBinding.ToString(), versionFromContext.ToString() });
}

When executed, the output is the formatted version 2.0 strings:

[ "2.0", "2.0" ]

Route Updates for URL Segment Versioning
Each of the previous examples used query string versioning. In order to use URL segment versioning, the Route attribute needs to be updated so the versioning engine knows what route parameter represents the version. This is accomplished by adding a route that uses the {version:apiVersion} route token, as follows:

[ApiVersion("2.0")] [ApiController] [Route("api/[controller]")]
[Route("api/v{version:apiVersion}/[controller]")]
public class Values2Controller : ControllerBase
{
//omitted for brevity
}

Notice that the previous example has two routes defined. This is necessary to support URL segment versioning and non-URL segment routing. If the app will only support URL segment versioning, the [Route("api/[controller]")] attribute can be removed.

URL Segment Versioning and Version Status Values
Recall that a version can be defined with a text status, like Beta. This format is also supported with URL segment versioning by simply including the status in the URL. For example, update the Values2Controller to add a version 2.0-Beta:

[ApiVersion("2.0")]
[ApiVersion("2.0-Beta")] [ApiController] [Route("api/[controller]")]
[Route("api/v{version:apiVersion}/[controller]")] public class Values2Controller : ControllerBase
{

//omitted for brevity
}

To request the 2.0-Beta version of the API Calling into the API, you can use either a period or a dash as the separator. Both of these calls will successfully call into the 2.0-Beta version of the API:

rem separated by a dash
curl -G https://localhost:5011/api/v2.0-Beta/Values/1 -i rem separated by a period
curl -G https://localhost:5011/api/v2.0.Beta/Values/1 -i

Deprecating Versions
As versions are added, it is a good practice to remove older, unused versions. However, you don’t want to surprise anyone by suddenly deleting versions. The best way to handle older versions is to deprecate them. This informs the clients that this version will go away at some point in the future, and it’s best to move to a different (presumably newer) version.
To mark a version as deprecated, simply add Deprecated = true to the ApiVersion attribute. Adding the following to the ValuesController marks version 0.5 as deprecated:

[ApiVersion("0.5", Deprecated = true)] [ApiVersion("1.0")]
[ApiController] [Route("api/[controller]")]
[Route("api/v{version:apiVersion}/[controller]")] public class ValuesController : ControllerBase
{
//omitted for brevity
}

The deprecated versions are reported as such in the headers, letting clients know that the version will be retired in the future:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; v=2.0-beta Date: Thu, 11 Nov 2021 19:04:02 GMT
Server: Kestrel
Transfer-Encoding: chunked
api-supported-versions: 1.0, 2.0-Beta, 2.0
api-deprecated-versions: 0.5

Unsupported Version Requests
As a reminder, if a client calls into the API with a valid, unambiguous route, but an unsupported version, the application will respond with an HTTP 400 (Bad Request) with the message shown after the CURL command:

curl -G https://localhost:5011/api/v2.0.RC/Values/1 -i

{"error":{"code":"UnsupportedApiVersion","message":"The HTTP resource that matches the request URI 'https://localhost:5011/api/v2.0.RC/Values/1' does not support the API version '2.0.RC'.","innerError":null}}

Add the API Version Explorer
If you don’t plan on adding version support to your Swagger documentation, you can consider your versioning configuration complete at this point. However, to document the different versions available, an instance of the IApiVersionDescriptionProvider must be added into the DI container using the
AddVersionedApiExplorer() extension method. This method takes an Action that is used to set options for the explorer. Table 32-4 lists the ApiExplorerOptions’ properties:

Table 32-4. Some of the APIExplorerOptions properties

Option Meaning in Life
GroupNameFormat Gets or sets the format used to create group names from API versions. Default value is null.
SubstitutionFormat Gets or sets the format used to format the API version substituted in route templates. Default value is “VVV”, which formats major version and optional minor version.
SubstitueApiVersionInUrl Gets or sets value indicating whether the API version parameter should be substituted in route templates. Defaults to false.
DefaultApiVersionParameterDescription Gets or sets the default description used for API version parameters. Defaults to “The requested API version”.
AddApiVersionParametersWhenVersionNeutral Gets or sets a value indicating whether API version parameters are added when an API is version-neutral. Defaults to false.
DefaultApiVersion Gets or sets the default version when request does not specify version information. Defaults to ApiVersion. Default (1.0).
AssumeDefaultVersionWhenUnspecified Gets or sets a value indicating whether a default version is assumed when a client does not provide a service API version. Default derives from the property of the same name on the ApiVersioningOptions.
ApiVersionParameterSource Gets or sets the source for defining API version parameters.

Add the call to the AddVersionedApiExplorer () method into the AddAutoLotApiVersionConfiguration() method in the ApiVersionConfiguration class. The following code sets the default version, uses the default version if the client doesn’t provide one, sets the reported version format to “v'Major.Minor-Status”, and enables version substitution in URLs:

public static IServiceCollection AddAutoLotApiVersionConfiguration(

this IServiceCollection services, ApiVersion defaultVersion = null)
{
//omitted for brevity
// add the versioned api explorer, which also adds IApiVersionDescriptionProvider service services.AddVersionedApiExplorer(
options =>
{
options.DefaultApiVersion = defaultVersion; options.AssumeDefaultVersionWhenUnspecified = true;
// note: the specified format code will format the version as "'v'major[.minor] [-status]"
options.GroupNameFormat = "'v'VVV";
// note: this option is only necessary when versioning by url segment. the SubstitutionFormat
// can also be used to control the format of the API version in route templates options.SubstituteApiVersionInUrl = true;
});
}

Update the Swagger/OpenAPI Settings
Swagger (also known as OpenAPI) is an open standard for documenting RESTful APIs. Two of the main open source libraries for adding Swagger into the ASP.NET Core APIs are Swashbuckle and NSwag. Since ASP.NET Core version 5,Swashbuckle has been included as part of the new project template (albeit a very basic implementation). Swashbuckle generates a swagger.json document for your application that contains information for the site, each endpoint, and any objects involved in the endpoints.
Swashbuckle also provides an interactive UI called Swagger UI that presents the contents of the swagger.json file, as you have already used in previous examples. This experience can be enhanced by adding additional application documentation into the generated swagger.json file.
To get started, add the following global using statements to the GlobalUsings.cs file:

global using Microsoft.Extensions.Options; global using Microsoft.OpenApi.Any;
global using Microsoft.OpenApi.Models;
global using Swashbuckle.AspNetCore.Annotations; global using Swashbuckle.AspNetCore.SwaggerGen; global using System.Reflection;
global using System.Text.Json;

Add the XML Documentation File
.NET can generate an XML documentation file from your project by examining the method signatures as well as developer written documentation for methods contained in triple-slash (///) comments. You must opt-in to the generation of this file.
To enable the creation of the XML documentation file using Visual Studio, right-click the AutoLot.Api project and open the Properties window. Select Build/Output in the left rail, check the XML documentation file check box, and enter AutoLot.Api.xml for the filename, as shown in Figure 32-3.

Figure 32-3. Adding the XML documentation file and suppressing 1591

Also, enter 1591 in the “Suppress warnings” text box, as shown in Figure 32-4. This setting turns off compiler warnings for methods that don’t have triple slash XML comments.

Figure 32-4. Adding the XML documenation file and suppressing 1591

■Note The 1701 and 1702 warnings are carryovers from the early days of classic .NET that are exposed by the .NET Core compilers.

Updating the settings makes the following changes to the project file (shown in bold):

net6.0
disable
enable
True
AutoLot.Api.xml

1701;1702;1591


1701;1702;1591

The same process can be done directly in the project file with a more concise format:

AutoLot.Api.xml
1701;1702;1591;1573

Once the project is built, the generated file will be created in the root directory of the project. Lastly, set the generated XML file to always get copied to the output directory.

Always

To add custom comments that will be added to the documentation file, add triple-slash (///) comments to the Get() method of the ValuesController to this:

///

/// This is one of several examples for returning JSON:
///

/// [
/// "value1",
/// "value2"
/// ]
/// 

///
/// List of strings [HttpGet]
public IActionResult Get()
{
return Ok(new string[“ { "value"", "value2" });
}

When you build the project, a new file named AutoLot.Api.xml is created in the root of the project.
Open the file to see the comments you just added.

<?xml vers"on="1.0"?>

AutoLot.Api

This is one of several examples for returning JSON:

 [
"value1", "value2"
]

List of strings

■Note when using Visual Studio, if you enter three backslashes before a class or method definition, Visual Studio will stub out the initial XML comments for you.

The XML comments will be merged into the generated swagger.json file shortly.

The Application’s Swagger Settings
There are several customizable settings for the Swagger page, such as the title, description, and contact information. Instead of hard-coding these in the app, they will be made configurable using the Options pattern.
Start by creating a new folder named Swagger in the root of the AutoLot.Api project. In this folder, create another folder named Models. In the Models folder, create a new class named SwaggerVersionDescription.cs and update the class to the following:
namespace AutoLot.Api.Swagger.Models; public class SwaggerVersionDescription
{
public int MajorVersion { get; set; } public int MinorVersion { get; set; } public string Status {get;set;}
public string Description { get; set; }
}

Next, create another class named SwaggerApplicationSettings.cs and update the class to the following:
namespace AutoLot.Api.Swagger.Models; public class SwaggerApplicationSettings
{
public string Title { get; set; }
public List Descriptions { get; set; } = new List();
public string ContactName { get; set; } public string ContactEmail {get; set; }
}

The settings are added to the appsettings.json file since they won’t alter between environments:

{
"AllowedHosts": "*", "SwaggerApplicationSettings": {
"Title": "AutoLot APIs", "Descriptions": [
{
"MajorVersion": 0,
"MinorVersion": 0, "Status": "",
"Description": "Unable to obtain version description."
},
{
"MajorVersion": 0,
"MinorVersion": 5, "Status": "",
"Description": "Deprecated Version 0.5"
},
{
"MajorVersion": 1,
"MinorVersion": 0, "Status": "",
"Description": "Version 1.0"
},
{
"MajorVersion": 2,
"MinorVersion": 0, "Status": "",
"Description": "Version 2.0"
},
{
"MajorVersion": 2,
"MinorVersion": 0, "Status": "Beta",
"Description": "Version 2.0-Beta"
}
],
"ContactName": "Phil Japikse", "ContactEmail": "blog@skimedic.com"
}
}

Update the GlobalUsings.cs file to include the new namespaces:

global using AutoLot.Api.Swagger;
global using AutoLot.Api.Swagger.Models;

Following the pattern of using extension methods to register services, create a new public static class named SwaggerConfiguration in the Swagger folder. Next, add a new public static extension method named AddAndConfigureSwagger() that extends the IServiceCollection, takes the IConfiguration

instance, the path and name for the generated AutoLot.Api.xml file, and a bool to enable/disable the security features in Swagger UI:

namespace AutoLot.Api.Swagger;

public static class SwaggerConfiguration
{
public static void AddAndConfigureSwagger( this IServiceCollection services, IConfiguration config,
string xmlPathAndFile, bool addBasicSecurity)
{
//implementation goes here
}
}

Now that the extension method is set up, register the settings using the Options pattern:

public static void AddAndConfigureSwagger( this IServiceCollection services, IConfiguration config,
string xmlPathAndFile, bool addBasicSecurity)
{
services.Configure( config.GetSection(nameof(SwaggerApplicationSettings)));
}

Finally, call the extension method in the Program.cs file just before the call to AddSwaggerGen():

builder.Services.AddAndConfigureSwagger( builder.Configuration,
Path.Combine(AppContext.BaseDirectory, $"{Assembly.GetExecutingAssembly().GetName(). Name}.xml"),
true);
builder.Services.AddSwaggerGen();

The SwaggerDefaultValues Operation Filter
When APIs are versioned (as this one is), the Swagger code that came with the default ASP.NET Core RESTful service template isn’t set up to handle the versions. Fortunately, the solution is provided by the good folks at Microsoft on the DotNet GitHub site (see the note for the link).

■Note The original version of the SwaggerDefaultValues.cs and ConfigureSwaggerOptions.cs classes are from the DotNet Github site in the versioning sample, which is located here https://github. com/dotnet/aspnet-api-versioning/blob/master/samples/aspnetcore/SwaggerSample/ SwaggerDefaultValues.cs

In the Swagger folder create a new class named SwaggerDefaultValues.cs and update the class to the following (which is direct from the sample with some minor cleanup):

namespace AutoLot.Api.Swagger;

public class SwaggerDefaultValues : IOperationFilter
{
public void Apply(OpenApiOperation operation, OperationFilterContext context)
{
var apiDescription = context.ApiDescription;
//operation.Deprecated = (operation.Deprecated | apiDescription.IsDeprecated()) operation.Deprecated |= apiDescription.IsDeprecated();
foreach (var responseType in context.ApiDescription.SupportedResponseTypes)
{
var responseKey = responseType.IsDefaultResponse ? "default" : responseType. StatusCode.ToString();
var response = operation.Responses[responseKey]; foreach (var contentType in response.Content.Keys)
{
if (responseType.ApiResponseFormats.All(x => x.MediaType != contentType))
{
response.Content.Remove(contentType);
}
}
}
if (operation.Parameters == null)
{
return;
}

foreach (var parameter in operation.Parameters)
{
var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);
parameter.Description ??= description.ModelMetadata?.Description;
if (parameter.Schema.Default == null && description.DefaultValue != null)
{
var json = JsonSerializer.Serialize(description.DefaultValue, description. ModelMetadata.ModelType);
parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson(json);
}
parameter.Required |= description.IsRequired;
}
}
}

The ConfigureSwaggerOptions Class
The next class to add is also provided from the ASP.NET Core samples, but modified here to use the SwaggerApplicationSettings. Create a public class named ConfigureSwaggerOptions in the Swagger folder and make it implement IConfigureOptions, like this:

namespace AutoLot.Api.Swagger;

public class ConfigureSwaggerOptions : IConfigureOptions
{
public void Configure(SwaggerGenOptions options)
{
throw new NotImplementedException();
}
}

In the constructor, take an instance of the IApiVersionDescriptionProvider and the OptionsMonitor for the SwaggerApplicationSettings, and assign each to a class level variable (the code in bold is updated from the sample):

readonly IApiVersionDescriptionProvider _provider;
private readonly SwaggerApplicationSettings _settings;

public ConfigureSwaggerOptions( IApiVersionDescriptionProvider provider,
IOptionsMonitor settingsMonitor)
{
_provider = provider;
_settings = settingsMonitor.CurrentValue;
}

The Configure() method loops through the API’s versions, generating a Swagger document for each version. Add the following method (once again, the code in bold is added to the provided sample):

public void Configure(SwaggerGenOptions options)
{
foreach (var description in _provider.ApiVersionDescriptions)
{
options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description,
_settings));
}
}
internal static OpenApiInfo CreateInfoForApiVersion( ApiVersionDescription description, SwaggerApplicationSettings settings)
{
throw new NotImplementedException();
}

The CreateInfoForApiVersion() method creates an instance of the OpenApiInfo object for each version. The OpenApiInfo holes the descriptive information for the application, such as the title, version information, description, etc. The code in bold is either custom information hardcoded for this app or leverages the SwaggerApplicationSettings to set the configured values:

internal static OpenApiInfo CreateInfoForApiVersion( ApiVersionDescription description, SwaggerApplicationSettings settings)

{
var versionDesc = settings.Descriptions.FirstOrDefault(x => x.MajorVersion == (description.ApiVersion.MajorVersion??0)
&& x.MinorVersion == (description.ApiVersion.MinorVersion ?? 0)
&& (string.IsNullOrEmpty(description.ApiVersion.Status) || x.Status==description. ApiVersion.Status));
var info = new OpenApiInfo()
{
Title = settings.Title,
Version = description.ApiVersion.ToString(), Description = $"{versionDesc?.Description}",
Contact = new OpenApiContact() { Name = settings.ContactName, Email = settings. ContactEmail },
TermsOfService = new System.Uri("https://www.linktotermsofservice.com"),
License = new OpenApiLicense() { Name = "MIT", Url = new System.Uri("https://opensource. org/licenses/MIT") }
};
if (description.IsDeprecated)
{
info.Description += "

This API version has been deprecated.

";
}

return info;
}

With these classes in place, add the following line to the AddAndConfigureSwagger() method so the
SwaggerGenOptions are into the DI container:

public static void AddAndConfigureSwagger( this IServiceCollection services, IConfiguration config,
string xmlPathAndFile, bool addBasicSecurity)
{
services.Configure(config.GetSection(nameof(SwaggerApplication Settings)));
services.AddTransient<IConfigureOptions, ConfigureSwaggerOptions>();
}

Update the SwaggerGen() Call
The default template simply called AddSwaggerGen(), in the Program.cs file top level statements, which adds very basic support. Remove that line from the top level statements and add it to the AddAndConfigureSwagger() method. In the following code, annotations are enabled, the OperationFilter is set, and XML comments are included. If security is not enabled, the method ends there. If security is requested, the rest of the method adds support for basic authentication into the Swagger UI. The call is listed here:

services.AddSwaggerGen(c =>
{
c.EnableAnnotations(); c.OperationFilter(); c.IncludeXmlComments(xmlPathAndFile);
if (!addBasicSecurity)
{
return;
}
c.AddSecurityDefinition("basic", new OpenApiSecurityScheme
{
Name = "Authorization",
Type = SecuritySchemeType.Http, Scheme = "basic",
In = ParameterLocation.Header,
Description = "Basic Authorization header using the Bearer scheme."
});
c.AddSecurityRequirement(new OpenApiSecurityRequirement
{
{
new OpenApiSecurityScheme
{
Reference = new OpenApiReference
{
Type = ReferenceType.SecurityScheme, Id = "basic"
}
},
new List {}
}
});
});

Update the UseSwaggerUI() Call
The final step is to replace the UseSwaggerUI() call in the Program.cs file with a version that leverages all of the framework we just built. In the call, the instance of the IApiVersionDescriptionProvider is retrieved from the DI container and is used to loop through the API versions supported by the application, creating a new Swagger UI endpoint for each version.
Update the call to UseSwaggerUI() with the following code:

app.UseSwaggerUI(
options =>
{
using var scope = app.Services.CreateScope();
var versionProvider = scope.ServiceProvider.GetRequiredService();
// build a swagger endpoint for each discovered API version
foreach (var description in versionProvider.ApiVersionDescriptions)

{

}
});

options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());

View the Results in the Swagger UI
Now that everything is in place, run the application and examine the Swagger UI. The first thing you will notice is that the version displayed in the UI is 0.5 (the deprecated version). This is because the UI displays the lowest version reported as the default. You can see the red message that the version has been deprecated, the description and contact information from the SwaggerApplicationSettings, a button to Authorize (for basic authentication), and all of the deprecated end points are grayed out and displayed with the font struck through. It's important to note that even though the endpoints look disabled, the page is still fully functional. All of the updates are merely cosmetic. Examine Figure 32-5 to see all of the updates to the UI:

Figure 32-5. Updates to the Swagger UI page

Now, select version 1.0 with the version selector (Figure 32-6), and you will see all of the endpoints return to normal font and coloration and the red deprecated warning is gone.

Figure 32-6. The version selector on the Swagger UI page

If you examine the HTTP Get /api/Values endpoint, you can see the XML comments have been incorporated into the UI, as show in Figure 32-7.

Figure 32-7. XML documentation integrated into Swagger UI

Another change is in the list of endpoints. With version 1.0 selected, you can see that there are two lines for each of the endpoints (Figure 32-8). This is because the app has URL segment versioning and non-URL segment versioning enabled.

Figure 32-8. Two entries for each end point

The final change to examine has to do with executing the end points. When expanding one of the endpoints that use URL segment versioning (like /api/v1/Values), you see the normal Try it out button, and if you click that, you will see the option to enter any URL parameters (like id). However, with one of the non- URL segment routing end points (like /api/Values), when you expand the method, you see all of the version options available for input (Figure 32-9) in addition to any URL parameters. When you click Try it out, you have the option to enter an API version using one of the four methods.

Figure 32-9. Two entries for each end point

The authorize button will be covered later in this chapter.

Additional Documentation Options for API Endpoints
There are additional attributes that augment the Swagger documentation. The Produces attribute indicates the content-type for the endpoint. The ProducesResponseType attribute uses the StatusCodes enumeration to indicate a possible return code for an endpoint. Update the Get() method of the ValuesController to specify application/json as the return type and that the action result will return either a 200 OK, a 400 Bad Request, or a 401 Unauthorized.

[HttpGet]
[Produces("application/json")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes. Status401Unauthorized)] public ActionResult<IEnumerable> Get()
{
return new string[] {"value1", "value2"};
}

While the ProducesResponseType attribute adds the response codes to the documentation, the information can’t be customized. Fortunately, Swashbuckle adds the SwaggerResponse attribute for just this purpose. Update the Get() method to the following:

[HttpGet] [Produces("application/json")]
[ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes. Status401Unauthorized)] [SwaggerResponse(200, "The execution was successful")] [SwaggerResponse(400, "The request was invalid")] [SwaggerResponse(401, "Unauthorized access attempted")] public ActionResult<IEnumerable> Get()
{
return new string[] {"value1", "value2"};
}

Before the Swagger annotations will be picked up and added to the generated documentation, they must be enabled. They were already enabled in the AddAndConfigureSwagger() method. Now, when you view the responses section of the Swagger UI, you will see the customized messaging, as shown in Figure 32-10.

Figure 32-10. Updated responses in Swagger UI

■Note There is a lot of additional customization that Swashbuckle supports. Consult the docs at https:// github.com/domaindrivendev/Swashbuckle.AspNetCore for more information.

Building The BaseCrudController
The majority of the functionality of the AutoLot.Api application can be categorized as one of the following methods:
•GetOne()
•GetAll()
•UpdateOne()
•AddOne()
•DeleteOne()
The main API methods will be implemented in a generic base API controller. Update the GlobalUsings.cs
file by adding the following:

global using AutoLot.Dal.Exceptions; global using AutoLot.Dal.Repos; global using AutoLot.Dal.Repos.Base;
global using AutoLot.Dal.Repos.Interfaces; global using AutoLot.Models.Entities; global using AutoLot.Models.Entities.Base;

Next, create a new folder named Base in the Controllers directory. In this folder, add a new class named BaseCrudController.cs and update the class definition to the following:

namespace AutoLot.Api.Controllers.Base [ApiController]

[Route("api/[controller]")] [Route("api/v{version:apiVersion}/[controller]")]
public abstract class BaseCrudController<TEntity, TController> : ControllerBase where TEntity : BaseEntity, new()
where TController : class
{
//implementation goes here
}

Add the following global using statement into the GlobalUsings.cs file:

global using AutoLot.Api.Controllers.Base;

The class is public and abstract and inherits ControllerBase. The class accepts two generic parameters. The first type is constrained to derive from BaseEntity and have a default constructor, and the second must be a class (for the logging framework). As discussed earlier, when the ApiController attribute is added to a base class, derived controllers get the functionality provided by the attribute.

The Constructor
The next step is to add two protected class-level variables: one to hold an instance of IRepo and the other to hold an instance of IAppLogging. Both of these should be set using a constructor.

protected readonly IBaseRepo MainRepo; protected readonly IAppLogging Logger;
protected BaseCrudController(IAppLogging logger, IBaseRepo repo)
{
MainRepo = repo;
Logger = logger;
}

The entity type for the repo matches the entity type for the derived controller. For example, the CarsController will be using the CarRepo. This allows for type specific work to be done in the derived controllers, but encapsulating simple CRUD operations in the base controller.

The Get Methods
There are four HTTP Get methods, GetOnBad(), GetOneFuture(), GetOne() and GetAll(). In this app, assume that the GetOneBad() method is deprecated as part of the 0.5 version. The GetOneFuture() is part of the next beta release (2.0-Beta), while the GetOne() and GetAll() methods are part of the version 1.0 production API.
Add the GetAllBad() method like this:

///

/// All records [Produces("application/json")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)]

[ProducesResponseType(StatusCodes.Status401Unauthorized)] [SwaggerResponse(200, "The execution was successful")] [SwaggerResponse(400, "The request was invalid")] [SwaggerResponse(401, "Unauthorized access attempted")] [ApiVersion("0.5", Deprecated = true)]
[HttpGet]
public ActionResult<IEnumerable> GetAllBad()
{
throw new Exception("I said not to use this one");
}

■Note when a version is deprecated, you must add the Deprecated flag to all of the ApiVersion
attributes in your application to guarantee that Swagger will report the versions correctly.

Next, add in the future implementation of GetAllFuture() like this:

///

/// All records [Produces("application/json")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status401Unauthorized)] [SwaggerResponse(200, "The execution was successful")] [SwaggerResponse(400, "The request was invalid")]
[SwaggerResponse(401, "Unauthorized access attempted access attempted")] [ApiVersion("2.0-Beta")]
[HttpGet]
public ActionResult<IEnumerable> GetAllFuture()
{
throw new NotImplementedException("I'm working on it");
}

Now it’s time to build the real get methods. First, add the GetAll() method. This method serves as the endpoint for the derived controller’s get all route (e.g., /Cars).

///

/// All records [Produces("application/json")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status401Unauthorized)] [SwaggerResponse(200, "The execution was successful")] [SwaggerResponse(400, "The request was invalid")] [SwaggerResponse(401, "Unauthorized access attempted")]

[ApiVersion("1.0")] [HttpGet]
public ActionResult<IEnumerable> GetAll()
{
return Ok(MainRepo.GetAllIgnoreQueryFilters());
}

The next method gets a single record, based on the id, which is passed in as a required route parameter (e.g. /Cars/5).

///

/// Primary key of the record /// Single record [Produces("application/json")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status204NoContent)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status401Unauthorized)] [SwaggerResponse(200, "The execution was successful")] [SwaggerResponse(204, "No content")] [SwaggerResponse(400, "The request was invalid")] [SwaggerResponse(401, "Unauthorized access attempted")] [ApiVersion("1.0")]
[HttpGet("{id}")]
public ActionResult GetOne(int id)
{
var entity = MainRepo.Find(id); if (entity == null)
{
return NoContent();
}
return Ok(entity);
}

The route value is automatically assigned to the id parameter (implicit [FromRoute]).

The UpdateOne Method
The HTTP Put verb represents an update to a record. The method is listed here, with explanation to follow:

///

///
/// Sample body:
///

/// {
/// "Id": 1,
/// "TimeStamp": "AAAAAAAAB+E="

/// "MakeId": 1,
/// "Color": "Black",
/// "PetName": "Zippy",
/// "MakeColor": "VW (Black)",
/// }
/// 

///
/// Primary key of the record to update /// Entity to update /// Single record [Produces("application/json")] [ProducesResponseType(StatusCodes.Status200OK)] [ProducesResponseType(StatusCodes.Status400BadRequest)] [ProducesResponseType(StatusCodes.Status401Unauthorized)] [SwaggerResponse(200, "The execution was successful")] [SwaggerResponse(400, "The request was invalid")] [SwaggerResponse(401, "Unauthorized access attempted")] [HttpPut("{id}")]
[ApiVersion("1.0")]
public IActionResult UpdateOne(int id, TEntity entity)
{
if (id != entity.Id)
{
return BadRequest();
}
if (!ModelState.IsValid)
{
return ValidationProblem(ModelState);
}
try
{
MainRepo.Update(entity);
}
catch (CustomException ex)
{
//This shows an example with the custom exception
//Should handle more gracefully return BadRequest(ex);
}
catch (Exception ex)
{
//Should handle more gracefully return BadRequest(ex);
}
return Ok(entity);
}

The method starts by setting the route as an HttpPut request based on the derived controller’s route with the required Id route parameter. The route value is assigned to the id parameter (implicit [FromRoute]), and the entity is assigned from the body of the request (implicit [FromBody]).

The method checks to make sure the route value (id) matches the id in the body. If it doesn’t, a BadRequest is returned. If it does, the explicit check for ModelState validity is used. If the ModelState isn’t valid, a 400 (BadRequest) will be returned to the client. Remember that the explicit check for ModelState validity isn’t needed if the implicit check is enabled with the ApiController attribute.
If all is successful to this point, the repo is used to update the record. If the update fails with an exception, a 400 is returned to the client. If all succeeds, a 200 (OK) is returned to the client with the updated record passed in as the body of the response.

■Note The exception handling in this example (and the rest of the examples as well) is woefully inadequate. Production applications should leverage all you have learned up to this point in the book as well as exception filters (introduced later in this chapter) to gracefully handle problems as the requirements dictate.

The AddOne Method
The HTTP Post verb represents an insert to a record. The method is listed here, with an explanation to follow:

///

/// {
/// "Id": 1,
/// "TimeStamp": "AAAAAAAAB+E="
/// "MakeId": 1,
/// "Color": "Black",
/// "PetName": "Zippy",
/// "MakeColor": "VW (Black)",
/// }
/// 

/// {
/// "Id": 1,
/// "TimeStamp": "AAAAAAAAB+E="
/// }
/// 

CHAPTER 31

Diving Into ASP.NET Core

This chapter takes a deep look into the new features in ASP.NET Core. As you learn about the features, you will add them to the projects created in the previous chapter, Introducing ASP.NET Core.

What’s New in ASP.NET Core
In addition to supporting the base functionality of ASP.NET MVC and ASP.NET Web API, Microsoft has added a host of new features and improvements over the previous frameworks. In addition to the unification of frameworks and controllers, a new style of web applications is now supported using Razor pages. Listed here are some additional improvements and innovations:
•Razor Page based web applications
•Environment awareness
•Minimal templates with top level statements
•Cloud-ready, environment-based configuration system
•Built-in dependency injection
•The Options pattern
•The HTTP Client Factory
•Flexible development and deployment models
•Lightweight, high-performance, and modular HTTP request pipeline
•Tag helpers (covered in a later chapter)
•View components (covered in a later chapter)
•Vast improvements in performance
•Integrated logging

Razor Pages
Another option for creating web applications with ASP.NET Core is using Razor pages. Instead of using the MVC pattern, Razor page applications are (as the name suggests) page-centric. Each Razor page consists of two files, the page file (e.g. Index.cshtml) is the view, and the PageModel C# class (e.g. Index.cshtml.cs), which serves as the code behind file for the page file.

© Andrew Troelsen, Phil Japikse 2022
A. Troelsen and P. Japikse, Pro C# 10 with .NET 6, https://doi.org/10.1007/978-1-4842-7869-7_31

1355

■Note Razor page based web applications also support partial and layout views, which will be covered in detail in later chapters.

The Razor Page File
Just like MVC based web applications, the Razor page file is responsible for rendering the content of the page, and receiving input from the user. It should be lightweight, and hand off work to the PageModel class. Razor page files will be explored in depth in Chapter 34.

The PageModel Class
Like the Controller class for MVC style applications, the PageModel class provides helper methods for Razor page based web applications. Razor pages derive from the PageModel class, and are typically named with the Model suffix, like CreateModel. The Model suffix is dropped when routing to a page. Table 31-1 lists the most commonly used methods and Table 31-2 lists the HTTP Status Code Helpers.

Table 31-1. Some of the Helper Methods Provided by the Controller Class

Helper Method Meaning in Life
HttpContext Returns the HttpContext for the currently executing action.
Request Returns the HttpRequest for the currently executing action.
Response Returns the HttpResponse for the currently executing action.
RouteData Returns the RouteData for the currently executing action (routing is covered later in this chapter).
ModelState Returns the state of the model in regard to model binding and validation (both covered later in this chapter).
Url Returns an instance of the IUrlHelper, providing access to building URLs for ASP.NET Core MVC applications and services.
ViewData TempData Provide data to the view through the ViewDataDictionary and
TempDataDictionary
Page Returns a PageResult (derived from ActionResult) as the HTTP response.
PartialView Returns a PartialViewResult to the response pipeline.
ViewComponent Returns a ViewComponentResult to the response pipeline.
OnPageHandlerSelected Executes when a page handler method is selected but before model binding.
OnPageHandlerExecuting Executes before a page handler method executes.
OnPageHandlerExecutionAsync Async version of OnPageHandlerExecuting.
OnPageHandlerExecuted Executes after a page handler method executes.
(continued)

Table 31-1. (continued)

Helper Method Meaning in Life
OnPageHandlerSelectionAsync Async version of OnPageHandlerSelected.
User Returns the ClaimsPrincipal user.
Content Returns a ContentResult to the response. Overloads allow for adding a content type and encoding definition.
File Returns a FileContentResult to the response.
Redirect A series of methods that redirect the user to another URL by returning a
RedirectResult.
LocalRedirect A series of methods that redirect the user to another URL only if the URL is local. More secure than the generic Redirect methods.
RedirectToAction RedirectToPage RedirectToRoute A series of methods that redirect to another action method, Razor Page, or named route. Routing is covered later in this chapter.
TryUpdateModelAsync Used for explicit model binding.
TryValidateModel Used for explicit model validation.

Table 31-2. Some of the HTTP Status Code Helper Methods Provided by the PageModelClass

Helper Method HTTP Status Code Action Result Status Code
NotFound NotFoundResult 404
Forbid ForbidResult 403
BadRequest BadRequestResult 400
StatusCode(int)StatusCode(int, object) StatusCodeResultObjectResult Defined by the int parameter.

You might be surprised to see some familiar methods from the Controller class. Razor page based applications share many of the features of MVC style applications as you have seen and will continue to see throughout these chapters.

Page Handler Methods
As discussed in the routing section, Razor pages define handler methods to handle HTTP Get and Post requests. The PageModel class supports both synchronous and asynchronous handler methods. The verb handled is based on the name of the method, with OnPost()/OnPostAsync() handling HTTP post requests, and OnGet()/OnGetAsync() handling HTTP get requests. The async versions are listed here:

public class DeleteModel : PageModel
{
public async Task OnGetAsync(int? id)
{
//handle the get request here
}

public async Task OnPostAsync(int? id)
{
//handle the post request here
}
}

The names of the handler methods can be changed, and multiple handler methods for each HTTP verb can exist, however overloaded versions with the same name are not permitted. This will be covered in Chapter 34.

Environmental Awareness
ASP.NET Core applications’ awareness of their execution environment includes host environment variables and file locations through an instance of IWebHostEnvironment, which implement the IHostEnvironment interface. Table 31-3 shows the properties available through these interfaces.

Table 31-3. The IWebHostEnvironment Properties

Property Functionality Provided
ApplicationName Gets or sets the name of the application. Defaults to the name of the entry assembly.
ContentRootPath Gets or sets the absolute path to the directory that contains the application content files.
ContentRootFileProvider Gets or sets an IFileProvider pointing to the ContentRootPath.
EnvironmentName Gets or sets the name of the environment. Sets to the value of the ASPNETCORE_ ENVIRONMENT environment variable.
WebRootFileProvider Gets or sets an IFileProvider pointing at the WebRootPath.
WebRootPath Gets or sets the absolute path to the directory that contains the web-servable application content files.

In addition to accessing the relevant file paths, IWebHostEnvironment is used to determine the runtime environment.

Determining the Runtime Environment
ASP.NET Core automatically reads the value of the environment variable named ASPNETCORE_ENVIRONMENT
to set the runtime environment. If the ASPNETCORE_ENVIRONMENT variable is not set, ASP.NET Core sets the value to Production. The value set is accessible through the EnvironmentName property on the IWebHostEnvironment.
While developing ASP.NET Core applications, this variable is typically set using the launchSettings. json file or the command line. Downstream environments (staging, production, etc.) typically use standard operating system environment variables.
You are free to use any name for the environment or the three that are supplied by the Environments
static class.

public static class Environments
{
public static readonly string Development = "Development"; public static readonly string Staging = "Staging";
public static readonly string Production = "Production";
}

The HostEnvironmentEnvExtensions class provides extensions methods on the IHostEnvironment for working with the environment name property. Table 31-4 lists the convenience methods available.

Table 31-4. The HostEnvironmentEnvExtensions Methods

Method Functionality Provided
IsProduction Returns true if the environment variable is set to Production (case insensitive)
IsStaging Returns true if the environment variable is set to Staging (case insensitive)
IsDevelopment Returns true if the environment variable is set to Development (case insensitive)
IsEnvironment Returns true if the environment variable matches the string passed into the method (case insensitive)

These are some examples of using the environment setting:
•Determining which configuration files to load
•Setting debugging, error, and logging options
•Loading environment-specific JavaScript and CSS files
Examine the Program.cs file in the AutoLot.Mvc project. Near the end of the file, the environment is checked to determine if the standard exception handler and HSTS (HTTP Strict Transport Security Protocol) should be used:

if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Home/Error"); app.UseHsts();
}

Update this block to flip it around:

if (app.Environment.IsDevelopment())
{
}
else
{
app.UseExceptionHandler("/Home/Error"); app.UseHsts();
}

Next, add the developer exception page into the pipeline when the app is running development. This provides debugging details like the stack trace, detailed exception information, etc. The standard exception handler renders a simple error page.

if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error"); app.UseHsts();
}

Update the AutoLot.Web project block to the following (notice the different route for the error handle in the Razor page based application):

if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error"); app.UseHsts();
}

The AutoLot.Api project is a little different. It is checking for the development environment, and if it is running in development, Swagger and SwaggerUI are added into the pipeline. For this app, we are going to move the Swagger code out of the if block so it will always be available (leave the if block there, as it will be used later in this chapter):

if (app.Environment.IsDevelopment())
{
//more code to be placed here later
}
app.UseSwagger(); app.UseSwaggerUI();

Since there isn’t a UI associated with RESTful services, there isn’t any need for the developer exception page. Swagger will be covered in depth in the next chapter.

■Note Whether the Swagger pages are available outside of the development environment is a business decision. We are moving the Swagger code to run in all environments so that the Swagger page is always available as you work through this book. Swagger will be covered in depth in the next chapter.

You will see many more uses for environment awareness as you build the ASP.NET Core applications in this book.

The WebAppBuilder and WebApp
Unlike classic ASP.NET MVC or ASP.NET Web API applications, ASP.NET Core applications are .NET console applications that create and configure a WebApplication, which is an instance of IHost. The creation of configuration of the IHost is what sets the application up to listen and respond to HTTP requests.
The default templates for ASP.NET Core 6 MVC, Razor, and Service application are minimal. These files will be added to as you progress through the ASP.NET Core chapters.

■Note prior to .net 6 and C# 10, a WebHost was created in the Main() method of the Program.cs file and configured for your application in the Startup.cs file. With the release of .net 6 and C# 10, the aSp.net Core template uses top level statements in the Program.cs file for creation and configuration and doesn’t have a Startup.cs file.

The Program.cs File with RESTful Services
Open the Program.cs class in the AutoLot.Api application, and examine the contents, shown here for reference:

var builder = WebApplication.CreateBuilder(args);
// Add services to the container. builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(); var app = builder.Build();
// Configure the HTTP request pipeline. if (app.Environment.IsDevelopment())
{
//more code to be placed here later
}
app.UseSwagger(); app.UseSwaggerUI();

app.UseHttpsRedirection(); app.UseAuthorization(); app.MapControllers();

app.Run();

If you are coming from a previous version of ASP.NET Core, the preceding code was split between the Program.cs file and the Startup.cs file. With ASP.NET Core 6, those file are combined into top level statements in the Program.cs file. The code before the call to builder.Build() was contained in the
Program.cs file and the ConfigureServices() method in the Startup.cs file and is responsible for creating

the WebApplicationBuilder and registering services in the dependency injection container. The code including the builder.Build() call and the rest of the code in the file was contained in the Configure() method and is responsible for the configuration of the HTTP pipeline.
The CreateBuilder() method compacts the most typical application setup into one method call. It configures the app (using environment variables and appsettings JSON files), it configures the default logging provider, and it sets up the dependency injection container. The returned WebApplicationBuilder is used to register services, add additional configuration information, logging support, etc.
The next set of methods adds the necessary base services into the dependency injection container for building RESTful services. The AddControllers() method adds in support for using controllers and action methods, the AddEndpointsApiExplorer() method provides information about the API (and is used by Swagger), and AddSwaggerGen() creates the basic OpenAPI support.

■Note When adding services into the Dependency injection container, make sure to add them into the top level statements using the comment //Add services to the container.they must be added before the builder.Build() method is called.

The builder.Build() method generates the WebApplication and sets up the next group of method calls to configure the HTTP pipeline. The Environment section was discussed previously. The next set of calls ensures all requests use HTTPS, enables the authorization middleware, and maps the controllers to their endpoints. Finally, the Run() method starts the application and gets everything ready to receive web requests and respond to them.

The Program.cs File with MVC Style Applications
Open the Program.cs class in the AutoLot.Mvc application, and examine the contents, shown here for reference (with differences from the AutoLot.Api application’s file in bold):

var builder = WebApplication.CreateBuilder(args);

// Add services to the container. builder.Services.AddControllersWithViews(); var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error"); app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute( name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

The first difference is the call to AddControllersWithViews(). ASP.NET Core RESTful services use the same controller/action method pattern as MVC style applications, just without views. This adds support for views into the application. The calls for Swagger and the API Explorer are omitted, as they are used by API service.
The next difference is the call to UserExceptionHandler() when the application is not running in a development environment. This is a user friendly exception handler that displays simple information
(and no technical debugging data). That is followed by the UseHsts() method, which turns on HTTP Strict Transport Security, preventing users to switch back to HTTP once they have connected. It also prevents them from clicking through warnings regarding invalid certificates.
The call to UseStaticFiles() enables static content (images, JavaScript files, CSS files, etc.) to be rendered through the application. This call is not in the API style applications, as they don’t typically have a need to render static content. The final changes add end point routing support and the default route to the application.

The Program.cs File with Razor Page Based Applications
Open the Program.cs class in the AutoLot.Web application, and examine the contents, shown here for reference (with the differences from the AutoLot.Mvc application shown in bold):

var builder = WebApplication.CreateBuilder(args);
// Add services to the container.

builder.Services.AddRazorPages();
var app = builder.Build();

// Configure the HTTP request pipeline. if (app.Environment.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error"); app.UseHsts();
}
app.UseHttpsRedirection(); app.UseStaticFiles(); app.UseRouting(); app.UseAuthorization(); app.MapRazorPages(); app.Run();

There are only three differences between this file and the initial file for the AutoLot.Mvc application. Instead of adding support for controllers with views, there is a call to AddRazorPages() to add support for Razor pages, add routing for razor pages with the call to the MapRazorPages() method, and there isn’t a default route configured.

Application Configuration
Previous versions of ASP.NET used the web.config file to configure services and applications, and developers accessed the configuration settings through the System.Configuration class. Of course, all configuration settings for the site, not just application-specific settings, were dumped into the web.config file making it a (potentially) complicated mess.
ASP.NET Core leverages the new .NET JSON-based configuration system first introduced in Chapter 16.
As a reminder, it’s based on simple JSON files that hold configuration settings. The default file for configuration is the appsettings.json file. The initial version of appsettings.json file (created by the ASP. NET Core web application and API service templates) simply contains configuration information for the logging, as well as allowing all hosts (e.g. https://localhost:xxxx) to bind to the app:

{
"Logging": {
"LogLevel": {
"Default": "Information", "Microsoft.AspNetCore": "Warning",
}
},
"AllowedHosts": "*"
}

The template also creates an appsettings.Development.json file. The configuration system works in conjunction with the runtime environment awareness to load additional configuration files based
on the runtime environment. This is accomplished by instructing the configuration system to load a file named appsettings.{environmentname}.json after the appSettings.json file. When running under Development, the appsettings.Development.json file is loaded after the initial settings file. If the environment is Staging, the appsettings.Staging.json file is loaded, etc. It is important to note that when more than one file is loaded, any settings that appear in both files are overwritten by the last file loaded; they are not additive.
For each of the web application projects, add the following connection string information (updating the actual connection string to match your environment from Chapter 23 into the appsettings.Development. json files:

"ConnectionStrings": {
"AutoLot": "Server=.,5433;Database=AutoLot;User ID=sa;Password=P@ssw0rd;"
}

■Note each item in the JSon must be comma delimited. When you add in the ConnectionStrings item, make sure to add a comma after the curly brace that proceeds the item you are adding.

Next, copy each of the appsettings.Development.json files to a new file named appsettings.
Production.json into each of the web application projects. Update the connection string entries to the following:

"ConnectionStrings": { "AutoLot": "It’s a secret"
},

This shows part of the power of the new configuration system. The developers don’t have access to the secret production information (like connection strings), just the non-secret information, yet everything can still be checked into source control.

■Note in production scenarios using this pattern, the secrets are typically tokenized. the build and release process replaces the tokens with the production information.

All configuration values are accessible through an instance of IConfiguration, which is available through the ASP.NET Core dependency injection system. In the top level statements prior to the web application being built, the configuration is available from the WebApplicationBuilder like this:

var config = builder.Configuration;

After the web application is built, the IConfiguration instance is available from the WebApplication
instance:

var config = app.Configuration;

Settings can be accessed using the traditional methods covered in Chapter 16. There is also a shortcut for getting application connection strings.

config.GetConnectionString("AutoLot")

Additional configuration features, including the Options pattern, will be discussed later in this chapter.

Built-in Dependency Injection
Dependency injection (DI) is a mechanism to support loose coupling between objects. Instead of directly creating dependent objects or passing specific implementations into classes and/or methods, parameters are defined as interfaces. That way, any implementation of the interface can be passed into the classes or methods and classes, dramatically increasing the flexibility of the application.
DI support is one of the main tenets in the rewrite ASP.NET Core. Not only do the top level statements in the Program.cs file (covered later in this chapter) accept all the configuration and middleware services through dependency injection, your custom classes can (and should) also be added to the service container to be injected into other parts of the application. When an item is configured into the ASP.NET Core DI container, there are three lifetime options, as shown in Table 31-5.

Table 31-5. Lifetime Options for Services

Lifetime Option Functionality Provided
Transient Created each time they are needed.
Scoped Created once for each request. Recommended for Entity Framework DbContext objects.
Singleton Created once on first request and then reused for the lifetime of the object. This is the recommended approach versus implementing your class as a Singleton.

■Note if you want to use a different dependency injection container, aSp.net Core was designed with that flexibility in mind. Consult the docs to learn how to plug in a different container: https://docs.microsoft. com/en-us/aspnet/core/fundamentals/dependency-injection.

Services are added into the DI container by adding them to the IServiceCollection for the application.
When using the top level statements template in .NET 6 web applications, the IServiceCollection is instantiated by the WebApplicationBuilder, and this instance is used to add services into the container.
When adding services to the DI container, make sure to add them before the line that builds the
WebApplication object:

var app = builder.Build();

■Note in pre-.net 6 web applications, the startup process involved both a Program.cs class and another class named Startup.cs (by convention). in .net 6, all of the configuration is done in top level statements in the Program.cs file. this will be covered in the section Configuring the Web application.

Adding Web App Support To The Dependency Injection Container
When creating MVC based web applications, the AddControllersWithView() method adds in the necessary services to support the MVC pattern in ASP.NET Core. The following code (in the Program.cs file of the AutoLot.Mvc project) accesses the IServiceCollection of the WebApplicationBuilder and adds the required DI support for controllers and views:

var builder = WebApplication.CreateBuilder(args);
// Add services to the container. builder.Services.AddControllersWithViews();

RESTful service web applications don’t use views but do need controller support, so they use the AddControllers() method. The API template for ASP.NET Core also adds in support for Swagger (a .NET implementation of OpenAPI) and the ASP.NET Core end point explorer:

var builder = WebApplication.CreateBuilder(args);
// Add services to the container. builder.Services.AddControllers(); builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen();

■Note Swagger and openapi will be covered in the next chapter.

Finally, Razor page based applications must enable Razor page support with the
AddRazorPages() method:

var builder = WebApplication.CreateBuilder(args);
// Add services to the container. builder.Services.AddRazorPages();

Adding Derived DbContext Classes into the DI Container
Registering a derived DbContext class in an ASP.NET Core application allows the DI container to handle the initialization and lifetime of the context. The AddDbContext<>()/AddDbContextPool() methods add a properly configured context class into the DI container. The AddDbContextPool() version creates a pool of instances that are cleaned between requests, ensuring that there isn’t any data contamination between
requests. This can improve performance in your application, as it eliminates the startup cost for creating a context once it is added to the pool.
Start by adding the following global using statements into the GlobalUsings.cs for the AutoLot.Api, AutoLot.Mvc, AutoLot.Web projects:

global using AutoLot.Dal.EfStructures; global using AutoLot.Dal.Initialization; global using Microsoft.EntityFrameworkCore;

The following code (which must be added into each of the Program.cs files in the web projects) gets the connection string from the JSON configuration file and adds the ApplicationDbContext as a pooled resource into the services collection:

var connectionString = builder.Configuration.GetConnectionString("AutoLot"); builder.Services.AddDbContextPool(
options => options.UseSqlServer(connectionString,
sqlOptions => sqlOptions.EnableRetryOnFailure().CommandTimeout(60)));

Now, whenever an instance of the ApplicationDbContext is needed, the dependency injection (DI) system will take care of the creation (or getting it from the pool) and recycling of the instance (or returning it to the pool).
EF Core 6 introduced a set of minimal APIs for adding derived DbContext classes into the services collection. Instead of the previous code, you can use the following short cut:

builder.Services.AddSqlServer(connectionString, options =>
{
options.EnableRetryOnFailure().CommandTimeout(60);
});

Note that the minimal API doesn’t have the same level of capabilities. Several features, like DbContext pooling are not supported. For more information on the minimal APIs, refer to the documentation located here: https://docs.microsoft.com/en-us/ef/core/what-is-new/ef-core-6.0/ whatsnew#miscellaneous-improvements.

Adding Custom Services To The Dependency Injection Container
Application services (like the repositories in the AutoLot.Dal project) can be added into the DI container using one of the lifetime options from Table 31-5. For example, to add the CarRepo as a service into the DI container, you would use the following

services.AddScoped<ICarRepo, CarRepo>();

The previous example added a scoped service (AddScoped<>()) into the DI container specifying the service type (ICarRepo) and the concrete implementation (CarRepo) to inject. You could add all of the repos into all of the web applications in the Program.cs file directly, or you can create an extension method to encapsulate the calls. This process keeps the Program.cs file cleaner.
Before creating the extension method, update the GlobalUsings.cs file in the AutoLot.Services project to the following:

global using AutoLot.Dal.Repos; global using AutoLot.Dal.Repos.Base;
global using AutoLot.Dal.Repos.Interfaces;

global using AutoLot.Models.Entities; global using AutoLot.Models.Entities.Base;

global using Microsoft.AspNetCore.Builder;

global using Microsoft.Extensions.DependencyInjection; global using Microsoft.Extensions.Configuration; global using Microsoft.Extensions.Hosting;
global using Microsoft.Extensions.Logging;

global using Serilog;
global using Serilog.Context;
global using Serilog.Core.Enrichers; global using Serilog.Events;
global using Serilog.Sinks.MSSqlServer;

global using System.Data;
global using System.Runtime.CompilerServices;

Next, create a new folder named DataServices in the AutoLot.Services project. In this folder, create a new public static class named DataServiceConfiguration. Update this class to the following:
namespace AutoLot.Services.DataServices; public static class DataServiceConfiguration
{
public static IServiceCollection AddRepositories(this IServiceCollection services)
{
services.AddScoped<ICarDriverRepo, CarDriverRepo>(); services.AddScoped<ICarRepo, CarRepo>(); services.AddScoped<ICreditRiskRepo, CreditRiskRepo>();
services.AddScoped<ICustomerOrderViewModelRepo, CustomerOrderViewModelRepo>();

services.AddScoped<ICustomerRepo, CustomerRepo>(); services.AddScoped<IDriverRepo, DriverRepo>(); services.AddScoped<IMakeRepo, MakeRepo>(); services.AddScoped<IOrderRepo, OrderRepo>(); services.AddScoped<IRadioRepo, RadioRepo>(); return services;
}
}

Next, add the following to the GlobalUsings.cs file in each web application (AutoLot.Api, AutoLot.Mvc, AutoLot.Web):

global using AutoLot.Services.DataServices;

Finally, add the following code to the top level statements in each of the web applications, making sure to add them above the line that builds the WebApplication:

builder.Services.AddRepositories();

Dependency Hierarchies
When there is a chain of dependencies, all dependencies must be added into the DI container, or a run- time error will occur when the DI container tries to instantiate the concrete class. If you recall from our repositories, they each had a public constructor that took an instance of the ApplicationDbContext, which was added into the DI container before adding in the repositories. If ApplicationDbContext was not in the DI container, then the repositories that depend on it can’t be constructed.

Injecting Dependencies
Services in the DI container can be injected into class constructors and methods, into Razor views, and Razor pages and PageModel classes. When injecting into the constructor of a controller or PageModel class, add the type to be injected into the constructor, like this:

//Controller
public class CarsController : Controller
{
private readonly ICarRep _repo; public CarsController(ICarRepo repo)
{
_repo = repo;
}
//omitted for brevity
}

//PageModel
public class CreateModel : PageModel
{
private readonly ICarRepo _repo;

public CreateModel(ICarRepo repo)
{
_repo = repo;
}
//omitted for brevity
}

Method injection is supported for action methods and page handler methods. To distinguish between a binding target and a service from the DI container, the FromServices attribute must be used:

//Controller
public class CarsController : Controller
{
[HttpPost] [ValidateAntiForgeryToken]
public async Task CreateAsync([FromServices]ICarRepo repo)
{
//do something
}
//omitted for brevity
}

//PageModel
public class CreateModel : PageModel
{
public async Task OnPostAsync([FromServices]ICarRepo repo)
{
//do somethng
}
//omitted for brevity
}

■Note You might be wondering when you should use constructor injection vs method injection, and the answer, of course, is “it depends”. i prefer to use constructor injection for services used throughout the class and method injection for more focused scenarios.

To inject into an MVC view or a Razor page view, use the @inject command:

@inject ICarRepo Repo

Getting Dependencies in Program.cs
You might be wondering how to get dependencies out of the DI container when you are in the top level statements in the Program.cs file. For example, if you want to initialize the database, you need an instance of the ApplicationDbContext. There isn’t a constructor, action method, page handler method, or view to inject the instance into.

In addition to the traditional DI techniques, services can also be retrieved directly from the application’s ServiceProvider. The WebApplication exposes the configured ServiceProvider through the Services property. To get a service, first create an instance of the IServiceScope. This provides a lifetime container
to hold the service. Then get the ServiceProvider from the IServiceScope, which will then provide the services within the current scope.
Suppose you want to selectively clear and reseed the database when running in the development environment. To set this up, first add the following line to the appsettings.Development.json files in each of the web projects:

"RebuildDatabase": true,

Next, add the following line to each of the appsettings.Production.json files in each of the web projects:

"RebuildDatabase": false,

In the development block of the if statement in Program.cs, if the configured value for RebuildDatabase is true, then create a new IServiceScope to the an instance of the ApplicationDbContext and use that to call the ClearAndReseedDatabase() method (example shown from the AutoLot.Mvc project):

if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
//Initialize the database
if (app.Configuration.GetValue("RebuildDatabase"))
{
using var scope = app.Services.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService(); SampleDataInitializer.ClearAndReseedDatabase(dbContext);
}
}

Make the exact same changes to the Program.cs file in the AutoLot.Web project. The Program.cs file update in the AutoLot.Api project is shown here:

if (app.Environment.IsDevelopment())
{
//Initialize the database
if (app.Configuration.GetValue("RebuildDatabase"))
{
using var scope = app.Services.CreateScope();
var dbContext = scope.ServiceProvider.GetRequiredService(); SampleDataInitializer.ClearAndReseedDatabase(dbContext);
}
}

Build the Shared Data Services
To wrap up the discussion on dependency injection, we are going to build a set of data services that will be used by both the AutoLot.Mvc and AutoLot.Web projects. The goal of the services is to present a single set of interfaces for all data access. There will be two concrete implementations of the interfaces, one that will call into the AutoLot.Api project and another one that will call into the AutoLot.Dal code directly. The concrete implementations that are added into the DI container will be determined by a project configuration setting.

The Interfaces
Start by creating a new directory named Interfaces in the DataServices directory of the AutoLot.Services project. Next, add the following IDataServiceBase interface into the Interfaces directory:

namespace AutoLot.Services.DataServices.Interfaces;

public interface IDataServiceBase where TEntity : BaseEntity, new()
{
Task<IEnumerable> GetAllAsync(); Task FindAsync(int id);
Task UpdateAsync(TEntity entity, bool persist = true); Task DeleteAsync(TEntity entity, bool persist = true); Task AddAsync(TEntity entity, bool persist = true);
//implemented ghost method since it won’t be used by the API data service void ResetChangeTracker() {}
}

The IMakeDataService interface simply implements the IDataServiceBase interface:

namespace AutoLot.Services.DataServices.Interfaces;

public interface IMakeDataService : IDataServiceBase
{
}

The ICarDataService interface implements the IDataServiceBase interface and adds a method to get Car records by Make Id:
namespace AutoLot.Services.DataServices.Interfaces; public interface ICarDataService : IDataServiceBase
{
Task<IEnumerable> GetAllByMakeIdAsync(int? makeId);
}

Add the following global using statement into the GlobalUsing.cs file:

global using AutoLot.Services.DataServices.Interfaces;

The AutoLot.Dal Direct Implementation
Start by creating a new directory named Dal in the DataServices directory, and add a new directory named Base in the Dal directory. Add a new class named DalServiceBase, make it public abstract and implement the IDataServiceBase interface:

namespace AutoLot.Services.DataServices.Dal.Base;

public abstract class DalDataServiceBase : IDataServiceBase where TEntity : BaseEntity, new()
{
//implementation goes here
}

Add a constructor that takes in an instance of the IBaseRepo and assign it to a class level variable:

protected readonly IBaseRepo MainRepo;
protected DalDataServiceBase(IBaseRepo mainRepo)
{
MainRepo = mainRepo;
}

Recall that all of the create, read, update, and delete (CRUD) methods on the base interface were defined as Task or Task. They are defined this way because calls to a RESTful service are asynchronous calls. Also recall that the repo methods that were built with the AutoLot.Dal are not async. The reason for that was mostly for teaching purposes, and not to introduce additional friction into learning EF Core. As the rest of the data services implementation is complete, you can either leave the repo methods synchronous (as they will be shown here) or refactor the repos to add in async versions of the methods.
The base methods call the related methods in the MainRepo:

public async Task<IEnumerable> GetAllAsync()
=> MainRepo.GetAllIgnoreQueryFilters();
public async Task FindAsync(int id) => MainRepo.Find(id);
public async Task UpdateAsync(TEntity entity, bool persist = true)
{
MainRepo.Update(entity, persist); return entity;
}
public async Task DeleteAsync(TEntity entity, bool persist = true)
=> MainRepo.Delete(entity, persist);
public async Task AddAsync(TEntity entity, bool persist = true)
{
MainRepo.Add(entity, persist); return entity;
}

The final method resets the ChangeTracker on the context, clearing it out for reuse:

public void ResetChangeTracker()
{
MainRepo.Context.ChangeTracker.Clear();
}

Add the following global using statements into the GlobalUsings.cs file:

global using AutoLot.Services.DataServices.Dal; global using AutoLot.Services.DataServices.Dal.Base;

Add a new class named MakeDalDataService.cs in the Dal directory and update it to match the following:

namespace AutoLot.Services.DataServices.Dal;

public class MakeDalDataService : DalDataServiceBase,IMakeDataService
{
public MakeDalDataService(IMakeRepo repo):base(repo) { }
}

Finally, add a class named CarDalDataService.cs and update it to match the following, which implements the one extra method from the interface:

namespace AutoLot.Services.DataServices.Dal;

public class CarDalDataService : DalDataServiceBase,ICarDataService
{
private readonly ICarRepo _repo;
public CarDalDataService(ICarRepo repo) : base(repo)
{
_repo = repo;
}
public async Task<IEnumerable> GetAllByMakeIdAsync(int? makeId) => makeId.HasValue
? _repo.GetAllBy(makeId.Value)
: MainRepo.GetAllIgnoreQueryFilters();
}

The API Initial Implementation
Most of the implementation for the API version of the data services will be completed after you create the HTTP client factory in the next section. This section will just create the classes to illustrate toggling
implementations for interfaces. Start by creating a new directory named Api in the DataServices directory, and add a new directory named Base in the Api directory. Add a new class named ApiServiceBase, make it public abstract and implement the IDataServiceBase interface:

namespace AutoLot.Services.DataServices.Api.Base;

public abstract class ApiDataServiceBase : IDataServiceBase where TEntity : BaseEntity, new()
{
protected ApiDataServiceBase()
{
}

public async Task<IEnumerable> GetAllAsync()
=> throw new NotImplementedException();
public async Task FindAsync(int id) => throw new NotImplementedException(); public async Task UpdateAsync(TEntity entity, bool persist = true)
{
throw new NotImplementedException();
}

public async Task DeleteAsync(TEntity entity, bool persist = true)
=> throw new NotImplementedException();
public async Task AddAsync(TEntity entity, bool persist = true)
{
throw new NotImplementedException();
}
}

Add the following global using statement into the GlobalUsings.cs file:

global using AutoLot.Services.DataServices.Api; global using AutoLot.Services.DataServices.Api.Base;

Add a new class named MakeDalDataService.cs in the Dal directory and update it to match the following:

namespace AutoLot.Services.DataServices.Api;

public class MakeApiDataService : ApiDataServiceBase, IMakeDataService
{
public MakeApiDataService():base()
{
}
}

Finally, add a class named CarDalDataService.cs and update it to match the following, which implements the one extra method from the interface:

namespace AutoLot.Services.DataServices.Api;

public class CarApiDataService : ApiDataServiceBase, ICarDataService
{
public CarApiDataService() :base()
{
}

public async Task<IEnumerable> GetAllByMakeIdAsync(int? makeId) => throw new NotImplementedException();
}

Adding the Data Services to the DI Container
The final step is to add the ICarDataService and IMakeDataService into the services collection. Start by adding the following line into the appsettings.Development.json and appsettings.Production.json files in the AutoLot.Mvc and AutoLot.Web project:

"RebuildDatabase": false,
"UseApi": false,

Add the following global using statements to the GlobalUsings.cs file in both the AutoLot.Mvc and AutoLot.Web projects:

global using AutoLot.Services.DataServices.Api; global using AutoLot.Services.DataServices.Dal;

Finally, add a new public static method named AddDataServices() to the DataServiceConfiguration class. In this method, check the value of the UseApi configuration flag, and if it is set to true, add the API versions of the data services classes into the services collection. Otherwise use the data access layer versions:

public static IServiceCollection AddDataServices( this IServiceCollection services, ConfigurationManager config)
{
if (config.GetValue("UseApi"))
{
services.AddScoped<ICarDataService, CarApiDataService>(); services.AddScoped<IMakeDataService, MakeApiDataService>();
}
else
{
services.AddScoped<ICarDataService, CarDalDataService>(); services.AddScoped<IMakeDataService, MakeDalDataService>();
}
return services;
}

Call the new extension method in the top level statements in Program.cs in the AutoLot.Mvc and AutoLot.Web projects:

builder.Services.AddRepositories();
builder.Services.AddDataServices(builder.Configuration);

The Options Pattern in ASP.NET Core
The options pattern provides a mechanism to instantiate classes from configured settings and inject the configured classes into other classes through dependency injection. The classes are injected into another class using one of the versions of IOptions. There are several versions of this interface, as shown in Table 31-6.

Table 31-6. Some of the IOptions Interfaces

Interface Description
IOptionsMonitor Retrieves options and supports the following: notification of changes (with OnChange), configuration reloading, named options (with Get and CurrentValue), and selective options invalidation.
IOptionsMonitorCache Caches instances of T with support for full/partial invalidation/reload.
IOptionsSnaphot Recomputes options on every request.
IOptionsFactory Creates new instances of T.
IOptions Root interface. Doesn’t support IOptionsMonitor. Left in for backward compatibility.

Using the Options Pattern
A simple example is to retrieve car dealer information from the configuration, configure a class with that data, and inject it into a controller’s action method for display. By placing the information into the settings file, the data is customizable without having to redeploy the site.
Start by adding the dealer information into the appsettings.json files for the AutoLot.Mvc and AutoLot.Web projects:

{
"Logging": {
"LogLevel": {
"Default": "Information", "Microsoft.AspNetCore": "Warning"
}
},
"AllowedHosts": "*",
"DealerInfo": {
"DealerName": "Skimedic's Used Cars", "City": "West Chester",
"State": "Ohio"
}
}

Next, we need to create a view model to hold dealer information. Create a new folder named ViewModels in the AutoLot.Services project. In that folder, add a new class named DealerInfo.cs. Update the class to the following:

namespace AutoLot.Services.ViewModels; public class DealerInfo
{
public string DealerName { get; set; } public string City { get; set; } public string State { get; set; }
}

■Note the class to be configured must have a public parameterless constructor and be non-abstract. properties are bound but fields are not. Default values can be set on the class properties.

Next, add the following global using statements to the AutoLot.Mvc and AutoLot.Web GlobalUsings. cs files:

global using AutoLot.Services.ViewModels; global using Microsoft.Extensions.Options;

The Configure<>() method of the IServiceCollection maps a section of the configuration files to a specific type. That type can then be injected into classes and views using the options pattern. In the
Program.cs files for the AutoLot.Mvc and AutoLot.Web Program.cs files, add the following after the line used to configure the repositories:

builder.Services.Configure(builder.Configuration.GetSection(nameof(Deal erInfo)));

Now that the DealerInfo is configured, instances are retrieved by injection one of the IOptions interfaces into the class constructor, controller action method, or Razor page handler method. Notice that what is injected in is not an instance of the DealerInfo class, but an instance of the IOptions interface. To get the configured instance, the CurrentValue (IOptionsMonitor) or Value
(IOptionsSnapshot) must be used. The following example uses method injection to pass an instance if IOptionsMonitor into the HomeController’s Index method in the AutoLot.Mvc project, then gets the CurrentValue and passes the configured instance of the DealerInfo class to the view (although the view doesn’t do anything with it yet).

public IActionResult Index([FromServices] IOptionsMonitor dealerMonitor)
{
var vm = dealerMonitor.CurrentValue;
return View(vm);
}

The following example replicates the process for the Index Razor page in the Pages folder in the AutoLot.Web project. Instead of passing the instance to the view, it is assigned to a property on the page. Update the Index.cshtml.cs by adding the same injection into the OnGet() method:

public DealerInfo DealerInfoInstance { get; set; }
public void OnGet([FromServices]IOptionsMonitor dealerOptions)
{
DealerInfoInstance = dealerOptions.CurrentValue;
}

■Note For more information on the options pattern in aSp.net Core, consult the documentation: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/ options?view=aspnetcore-6.0.

The HTTP Client Factory
ASP.NET Core 2.1 introduced the IHTTPClientFactory, which can be used to create and configure HttPClient instances. The factory manages the pooling and lifetime of the underlying HttpClientMessageHandler instance, abstracting that away from the developer. It provides four mechanisms of use:
•Basic usage
•Named clients,
•Typed clients, and
•Generated clients.
After exploring the basic, named client, and typed client usages, we will build the API service wrappers that will be utilized by the data services built earlier in this chapter.

■Note For information on generating clients, consult the documentation: https://docs.microsoft. com/en-us/aspnet/core/fundamentals/http-requests?view=aspnetcore-6.0.

Basic Usage
The basic usage registers the IHttpClientFactory with the services collection, and then uses the injected factory instance to create HttPClient instances. This method is a convenient way to refactor an existing application that is creating HttPClient instances. To implement this basic usage, add the following line into the top level statements in Program.cs (no need to actually do this, as the projects will use Typed clients):

builder.Services.AddHttpClient();

Then in the class that needs an HttpClient, inject the IHttpClientFactory into the constructor, and then call CreateClient():
namespace AutoLot.Services.DataServices.Api.Examples; public class BasicUsageWithIHttpClientFactory
{
private readonly IHttpClientFactory _clientFactory;
public BasicUsageWithIHttpClientFactory(IHttpClientFactory clientFactory)
{
_clientFactory = clientFactory;
}
public async Task DoSomethingAsync()
{
var client = _clientFactory.CreateClient();
//do something interesting with the client
}
}

Named Clients
Named clients are useful when your application uses distinct HttpClient instances, especially when they are configured differently. When registering the IHttpClientFactory, a name is provided along with any specific configuration for that HttpClient usage. To create a client named AutoLotApi, add the following into the top level statements in Program.cs (no need to actually do this, as the projects will use Typed clients):

using AutoLot.Services.DataServices.Api.Examples; builder.Services.AddHttpClient(NamedUsageWithIHttpClientFactory.API_NAME, client =>
{
//add any configuration here
});

Then in the class that needs an HttpClient, inject the IHttpClientFactory into the constructor, and then call CreateClient() passing in the name of the client to be created. The configuration from the AddHttpClient() call is used to create the new instance:
namespace AutoLot.Services.DataServices.Api.Examples; public class NamedUsageWithIHttpClientFactory
{
public const string API_NAME = "AutoLotApi"; private readonly IHttpClientFactory _clientFactory;
public NamedUsageWithIHttpClientFactory(IHttpClientFactory clientFactory)
{
_clientFactory = clientFactory;
}
public async Task DoSomethingAsync()
{
var client = _clientFactory.CreateClient(API_NAME);
//do something interesting with the client
}
}

Typed Clients
Typed clients are classes that accept an HttpClient instance through injection into its constructor. Since the typed client is a class, it can be added into the service collection and injected into other classes,
fully encapsulating the calls using an HttpClient. As an example, suppose you have a class named
ApiServiceWrapper that takes in an HttpClient and implements IApiServiceWrapper as follows:
namespace AutoLot.Services.DataServices.Api.Examples; public interface IApiServiceWrapperExample
{
//interesting methods places here
}

public class ApiServiceWrapperExample : IApiServiceWrapperExample
{
protected readonly HttpClient Client;
public ApiServiceWrapperExample(HttpClient client)
{
Client = client;
//common client configuration goes here
}
//interesting methods implemented here
}

With the interface and the class in place, they can be added to the service collection as follows:

builder.Services.AddHttpClient<IApiServiceWrapperExample,ApiServiceWrapperExample>();

Inject the IApiServiceWrapper interface into the class that needs to make calls to the API and use the methods on the class instance to call to the API. This pattern completely abstracts the HttpClient away from the calling code:
namespace AutoLot.Services.DataServices.Api.Examples; public class TypedUsageWithIHttpClientFactory
{
private readonly IApiServiceWrapperExample _serviceWrapper;

public TypedUsageWithIHttpClientFactory(IApiServiceWrapperExample serviceWrapper)
{
_serviceWrapper = serviceWrapper;
}
public async Task DoSomethingAsync()
{
//do something interesting with the service wrapper
}
}

In addition to the configuration options in the constructor of the class, the call to AddHttpClient() can also configure the client:

builder.Services.AddHttpClient<IApiServiceWrapperExample,ApiServiceWrapperExample>(client=>
{
//configuration goes here
});

The AutoLot API Service Wrapper
The AutoLot API service wrapper uses a typed base client and entity specific typed clients to encapsulate all of the calls to the AutoLot.Api project. Both the AutoLot.Mvc and AutoLot.Web projects will use the service wrapper through the data services classes stubbed out earlier in this chapter and completed at the end of this section. The AutoLot.Api project will be finished in the next chapter.

Update the Application Configuration
The AutoLot.Api application endpoints will vary based on the environment. For example, when developing on your workstation, the base URI is https://localhost:5011. In your integration environment, the URI might be https://mytestserver.com. The environmental awareness, in conjunction with the updated configuration system, will be used to add these different values.
The appsettings.Development.json file will add the service information for the local machine. As code moves through different environments, the settings would be updated in each environment’s specific file to match the base URI and endpoints for that environment. In this example, you only update the settings for the development environment. In the appsettings.Development.json files in the AutoLot.Mvc and AutoLot.Web projects, add the following after the ConnectionStrings entry (changes in bold):

"ConnectionStrings": {
"AutoLot": "Server=.,5433;Database=AutoLot;User ID=sa;Password=P@ssw0rd;"
},
"ApiServiceSettings": {
"Uri": "https://localhost:5011/", "UserName": "AutoLotUser", "Password": "SecretPassword", "CarBaseUri": "api/v1/Cars", "MakeBaseUri": "api/v1/Makes", "MajorVersion": 1,
"MinorVersion": 0, "Status": ""
}

■Note Make sure the port number matches your configuration for autoLot.api.

Create the ApiServiceSettings Class
The service settings will be populated from the settings the same way the dealer information was populated. In the AutoLot.Service project, create a new folder named ApiWrapper and in that folder, create a new folder named Models. In this folder, add a class named ApiServiceSettings.cs. The property names of the class need to match the property names in the JSON ApiServiceSettings section. The class is listed here:
namespace AutoLot.Services.ApiWrapper.Models; public class ApiServiceSettings
{
public ApiServiceSettings() { } public string UserName { get; set; } public string Password { get; set; } public string Uri { get; set; }
public string CarBaseUri { get; set; } public string MakeBaseUri { get; set; } public int MajorVersion { get; set; } public int MinorVersion { get; set; } public string Status { get; set; }

public string ApiVersion
=> $"{MajorVersion}.{MinorVersion}" + (!string.IsNullOrEmpty(Status)?$"-
{Status}":string.Empty);
}

■Note api versioning will be covered in depth in Chapter 32.

Add the following global using statement to the GlobalUsings.cs file in the AutoLot.Service project:

global using AutoLot.Services.ApiWrapper.Models;

Register the ApiServiceSettings Class
We are once again going to use an extension method to register everything needed for the API service wrapper, including configuring the ApiServiceSettings.cs using the Options pattern. Create a new folder named Configuration under the ApiWrapper folder, and in that folder create a new public static class named ServiceConfiguration, as shown here:
namespace AutoLot.Services.ApiWrapper.Configuration; public static class ServiceConfiguration
{
public static IServiceCollection ConfigureApiServiceWrapper(this IServiceCollection services, IConfiguration config)
{
services.Configure(config.GetSection(nameof(ApiServiceSettings))); return services;
}
}

Add the following global using statement to the GlobalUsings.cs file for both the AutoLot.Mvc and AutoLot.Web projects:

global using AutoLot.Services.ApiWrapper.Configuration;

Add the following to the top level statements in Program.cs (in both AutoLot.Mvc and AutoLot.Web) before the call to builder.Build():

builder.Services.ConfigureApiServiceWrapper(builder.Configuration);

The API Service Wrapper Base Class and Interface
The ApiServiceWrapperBase class is a generic base class that performs create, read, update, and delete (CRUD) operations against the AutoLot.Api RESTful service. This centralizes communication with the service, configuration of the HTTP client, error handling, and so on. Entity specific classes will inherit from this base class, and those will be added into the services collection.

The IApiServiceWrapperBase Interface
The AutoLot service wrapper interface contains the common methods to call into the AutoLot.Api service. Create a directory named Interfaces in the ApiWrapper directory. Add a new interface named IApiServiceWrapper.cs and update the interface to the code shown here:

namespace AutoLot.Services.ApiWrapper.Interfaces;

public interface IApiServiceWrapperBase where TEntity : BaseEntity, new()
{
Task<IList> GetAllEntitiesAsync(); Task GetEntityAsync(int id); Task AddEntityAsync(TEntity entity); Task UpdateEntityAsync(TEntity entity); Task DeleteEntityAsync(TEntity entity);
}

Add the following global using statement to the GlobalUsings.cs file for the AutoLot.Services project:

global using AutoLot.Services.ApiWrapper.Interfaces;

The ApiServiceWrapperBase Class
Before building the base class, add the following global using statements to the GlobalUsings.cs file:

global using AutoLot.Services.ApiWrapper.Base; global using Microsoft.Extensions.Options; global using System.Net.Http.Headers;
global using System.Net.Http.Json; global using System.Text;
global using System.Text.Json;

Create a new folder named Base in the ApiWrapper directory of the AutoLot.Services project and add a class named ApiServiceWrapperBase. Make the class public and abstract and implement the
IApiServiceWrapperBase interface. Add a protected constructor that takes an instance of HttpClient and IOptionsMonitor and a string for the entity specific endpoint. Add a protected readonly string to hold the ApiVersion from the settings and initialize them all from the constructor
like this:

namespace AutoLot.Services.ApiWrapper.Base;

public abstract class ApiServiceWrapperBase
: IApiServiceWrapperBase where TEntity : BaseEntity, new()
{
protected readonly HttpClient Client; private readonly string _endPoint;
protected readonly ApiServiceSettings ApiSettings; protected readonly string ApiVersion;

protected ApiServiceWrapperBase(
HttpClient client, IOptionsMonitor apiSettingsMonitor, string endPoint)
{
Client = client;
_endPoint = endPoint;
ApiSettings = apiSettingsMonitor.CurrentValue; ApiVersion = ApiSettings.ApiVersion;
}
}

Configuring the HttpClient in the Constructor
The constructor adds the standard configuration to the HttpClient that will be used by all methods, including an AuthorizationHeader that uses basic authentication. Basic authentication will be covered in depth in the next chapter, Restful Services with ASP.NET Core, so for now just understand that basic authentication takes a username and password, concatenates them together (separated by a colon) and Base64 encodes them. The rest of the code sets the BaseAddress for the HttpClient and specifies that the client is expecting JSON.

public ApiServiceWrapperBase(
HttpClient client, IOptionsMonitor apiSettingsMonitor, string endPoint)
{
Client = client;
_endPoint = endPoint;
ApiSettings = apiSettingsMonitor.CurrentValue; ApiVersion = ApiSettings.ApiVersion; Client.BaseAddress = new Uri(ApiSettings.Uri);
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/ json"));
var authToken = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiSettingsMonitor. CurrentValue.UserName}:{apiSettingsMonitor.CurrentValue.Password}")); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("basic", authToken);
}

The Internal Support Methods
The class contains four support methods that are used by the public methods.

The Post and Put Helper Methods
These methods wrap the related HttpClient methods.

internal async Task PostAsJsonAsync(string uri, string json)
{
return await Client.PostAsync(uri, new StringContent(json, Encoding.UTF8, "application/ json"));
}

internal async Task PutAsJsonAsync(string uri, string json)
{
return await Client.PutAsync(uri, new StringContent(json, Encoding.UTF8, "application/ json"));
}

The HTTP Delete Helper Method Call
The final helper method is used for executing an HTTP delete. The HTTP 1.1 specification (and later) allows for passing a body in a delete statement, but there isn’t yet an extension method of the HttpClient for doing this. The HttpRequestMessage must be built up from scratch.
The first step is to then create a request message using object initialization to set Content, Method, and RequestUri. Once this is complete, the message is sent, and the response is returned to the calling code. The method is shown here:

internal async Task DeleteAsJsonAsync(string uri, string json)
{
HttpRequestMessage request = new HttpRequestMessage
{
Content = new StringContent(json, Encoding.UTF8, "application/json"), Method = HttpMethod.Delete,
RequestUri = new Uri(uri)
};
return await Client.SendAsync(request);
}

The HTTP Get Calls
There are two Get calls: one to get all records and one to get a single record. They both follow the same pattern. The GetAsync() method is called to return an HttpResponseMessage. The success or failure of the call is checked with the EnsureSuccessStatusCode() method, which throws an exception if the call did not return a successful status code. Then the body of the response is serialized back into the property type
(either as an entity or a list of entities) and returned to the calling code. The endpoint is constructed from the settings, and the ApiVersion is appended as a query string value. Each of these methods is shown here:

public async Task<IList> GetAllEntitiesAsync()
{
var response = await Client.GetAsync($"{ApiSettings.Uri}{_endPoint}?v={ApiVersion}"); response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<IList>(); return result;
}

public async Task GetEntityAsync(int id)
{
var response = await Client.GetAsync($"{ApiSettings.Uri}{_endPoint}/{id}?v={ApiVersion}"); response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync(); return result;
}

Notice the improvement in serializing the response body into an item (or list of items). Prior versions of ASP.NET Core would have to use the following code instead of the shorter ReadFromJsonAsync() method:

var result = await JsonSerializer.DeserializeAsync<IList>(await response.Content. ReadAsStreamAsync());

The HTTP Post Call
The method to add a record uses an HTTP Post request. It uses the helper method to post the entity as JSON and then returns the record from the response body. The method is listed here:

public async Task AddEntityAsync(TEntity entity)
{
var response = await PostAsJsonAsync($"{ApiSettings.Uri}{_endPoint}?v={ApiVersion}", JsonSerializer.Serialize(entity));
if (response == null)
{
throw new Exception("Unable to communicate with the service");
}

var location = response.Headers?.Location?.OriginalString;
return await response.Content.ReadFromJsonAsync() ?? await GetEntityAsync(entity.Id);
}

There are two lines of note. The first is the line getting the location. Typically, when an HTTP Post call is successful, the service returns an HTTP 201 (Created at) status code. The service will also add the URI of the newly created resource in the Location header. The preceding code demonstrates getting the Location header but isn’t using the location in the code process.
The second line of note is reading the response content and creating an instance of the updated record. The service wrapper method needs to get the updated instance from the service to guarantee server generated values (like Id and TimeStamp) and are updated in the client app. Returning the updated entity in the response from HTTP post calls is not a guaranteed function of a service. If the service doesn’t return the entity, then the method uses the GetEntityAsync() method. It could also use the URI from the location if
necessary, but since the GetEntityAsync() supplies everything needed, getting the location value is merely
for demo purposes.

The HTTP Put Call
The method to update a record uses an HTTP Put request by way of the PutAsJsonAsync() helper method. This method also assumes that the updated entity is in the body of the response, and if it isn’t, calls the GetEntityAsync() to refresh the server generated values.

public async Task UpdateEntityAsync(TEntity entity)
{
var response = await PutAsJsonAsync($"{ApiSettings.Uri}{_endPoint}/{entity. Id}?v={ApiVersion}",
JsonSerializer.Serialize(entity)); response.EnsureSuccessStatusCode();
return await response.Content.ReadFromJsonAsync() ?? await GetEntityAsync(entity.Id);
}

The HTTP Delete Call
The final method to add, is for executing an HTTP Delete. The pattern follows the rest of the methods: use the helper method and check the response for success. There isn’t anything to return to the calling code since the entity was deleted. The method is shown here:

public async Task DeleteEntityAsync(TEntity entity)
{
var response = await DeleteAsJsonAsync($"{ApiSettings.Uri}{_endPoint}/{entity. Id}?v={ApiVersion}",
JsonSerializer.Serialize(entity)); response.EnsureSuccessStatusCode();
}

The Entity Specific Interfaces
In the Interfaces directory, create two new interfaces named ICarApiServiceWrapper.cs and
IMakeApiServiceWrapper.cs. Update the interfaces to the following:

//ICarApiServiceWrapper.cs
namespace AutoLot.Services.ApiWrapper.Interfaces;

public interface ICarApiServiceWrapper : IApiServiceWrapperBase
{
Task<IList> GetCarsByMakeAsync(int id);
}

//IMakeApiServiceWrapper.cs
namespace AutoLot.Services.ApiWrapper.Interfaces;

public interface IMakeApiServiceWrapper : IApiServiceWrapperBase
{
}

The Entity Specific Classes
In the ApiWrapper directory, create two new classes named CarApiServiceWrapper.cs and MakeApiServiceWrapper.cs. The constructor for each class takes an instance of HttpClient and IOptions and passes them into the base class along with the entity specific end point:

//CarApiServiceWrapper.cs
namespace AutoLot.Services.ApiWrapper;

public class CarApiServiceWrapper : ApiServiceWrapperBase, ICarApiServiceWrapper
{
public CarApiServiceWrapper(HttpClient client, IOptionsMonitor apiSettingsMonitor)
: base(client, apiSettingsMonitor, apiSettingsMonitor.CurrentValue.CarBaseUri) { }
}

//MakeApiServiceWrapper.cs
namespace AutoLot.Services.ApiWrapper;

public class MakeApiServiceWrapper : ApiServiceWrapperBase, IMakeApiServiceWrapper
{
public MakeApiServiceWrapper(HttpClient client, IOptionsMonitor apiSettingsMonitor)
: base(client, apiSettingsMonitor, apiSettingsMonitor.CurrentValue.MakeBaseUri) { }
}

The MakeApiServiceWrapper only needs the methods exposed in the ApiServiceWrapperBase to do its job. The CarApiServiceWrapper class has one additional method to get the list of Car records by Make. The method follows the same pattern as the base class’s HTTP Get methods but uses a unique end point:

public async Task<IList> GetCarsByMakeAsync(int id)
{
var response = await Client.GetAsync($"{ApiSettings.Uri}{ApiSettings.CarBaseUri}/bymake/
{id}?v={ApiVersion}"); response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<IList>(); return result;
}

As a last step, register the two typed clients by updating the ConfigureApiServiceWrapper method in the ServiceConfiguration class to the following:

public static IServiceCollection ConfigureApiServiceWrapper(this IServiceCollection services, IConfiguration config)
{
services.Configure(config.GetSection(nameof(ApiServiceSettings))); services.AddHttpClient<ICarApiServiceWrapper, CarApiServiceWrapper>(); services.AddHttpClient<IMakeApiServiceWrapper, MakeApiServiceWrapper>();
return services;
}

Complete the API Data Services
Now that the API service wrappers are complete, it’s time to revisit the API data services and complete the class implementations.

Complete the ApiDataServiceBase Class
The first step to complete the base class is to update the constructor to receive an instance of the IApiServic eWrapperBase interface and assign it to a protected field:

protected readonly IApiServiceWrapperBase ServiceWrapper;
protected ApiDataServiceBase(IApiServiceWrapperBase serviceWrapperBase)
{
ServiceWrapper = serviceWrapperBase;
}

The implementation for each of the CRUD methods calls the related method on the ServiceWrapper:

public async Task<IEnumerable> GetAllAsync()
=> await ServiceWrapper.GetAllEntitiesAsync();
public async Task FindAsync(int id)
=> await ServiceWrapper.GetEntityAsync(id);
public async Task UpdateAsync(TEntity entity, bool persist = true)
{
await ServiceWrapper.UpdateEntityAsync(entity); return entity;
}

public async Task DeleteAsync(TEntity entity, bool persist = true)
=> await ServiceWrapper.DeleteEntityAsync(entity);

public async Task AddAsync(TEntity entity, bool persist = true)
{
await ServiceWrapper.AddEntityAsync(entity); return entity;
}

Complete the Entity Specific Classes
The CarApiDataService and MakeApiDataService classes need their constructors updated to receive their entity specific derived instance of the IApiServiceWrapperBase interface and pass it to the
base class:

public class CarApiDataService : ApiDataServiceBase, ICarDataService
{
public CarApiDataService(ICarApiServiceWrapper serviceWrapper) : base(serviceWrapper) { }
}

public class MakeApiDataService : ApiDataServiceBase, IMakeDataService
{
public MakeApiDataService(IMakeApiServiceWrapper serviceWrapper):base(serviceWrapper) { }
}

The GetAllByMakeIdIdAsync() method determines if a value was passed in for the makeId parameter.
If there is a value, the relevant method on the ICarApiServiceWrapper is called. Otherwise, the base
GetAllAsync() is called:

public async Task<IEnumerable> GetAllByMakeIdAsync(int? makeId)
=> makeId.HasValue
? await ((ICarApiServiceWrapper)ServiceWrapper). GetCarsByMakeAsync(makeId.Value)
: await GetAllAsync();

Deploying ASP.NET Core Applications
Prior versions of ASP.NET applications could only be deployed to Windows servers using IIS as the web server. ASP.NET Core can be deployed to multiple operating systems in multiple ways, using a variety of web servers. ASP.NET Core applications can also be deployed outside of a web server. The high-level options are as follows:
•On a Windows server (including Azure) using IIS
•On a Windows server (including Azure app services) outside of IIS
•On a Linux server using Apache or NGINX
•On Windows or Linux in a container
This flexibility allows organizations to decide the deployment platform that makes the most sense for them, including popular container-based deployment models (such as using Docker), as opposed to being locked into Windows servers.

Lightweight and Modular HTTP Request Pipeline
Following along with the principles of .NET, you must opt in for everything in ASP.NET Core. By default, nothing is loaded into an application. This enables applications to be as lightweight as possible, improving performance, and minimizing the surface area and potential risk.

Logging
Logging in ASP.NET Core is based on an ILoggerFactory. This enables different logging providers to hook into the logging system to send log messages to different locations, such as the Console. The ILoggerFactory is used to create an instance of ILogger, which provides the following methods for logging by way of the LoggerExtensions class:

public static class LoggerExtensions
{
public static void LogDebug(this ILogger logger, EventId eventId, Exception exception, string message, params object[] args)
public static void LogDebug(this ILogger logger, EventId eventId, string message, params object[] args)
public static void LogDebug(this ILogger logger, Exception exception, string message, params object[] args)
public static void LogDebug(this ILogger logger, string message, params object[] args)

public static void LogTrace(this ILogger logger, EventId eventId, Exception exception, string message, params object[] args)
public static void LogTrace(this ILogger logger, EventId eventId, string message, params object[] args)
public static void LogTrace(this ILogger logger, Exception exception, string message, params object[] args)
public static void LogTrace(this ILogger logger, string message, params object[] args)

public static void LogInformation(this ILogger logger, EventId eventId, Exception exception, string message, params object[] args)
public static void LogInformation(this ILogger logger, EventId eventId, string message, params object[] args)
public static void LogInformation(this ILogger logger, Exception exception, string message, params object[] args)
public static void LogInformation(this ILogger logger, string message, params object[] args)

public static void LogWarning(this ILogger logger, EventId eventId, Exception exception, string message, params object[] args)
public static void LogWarning(this ILogger logger, EventId eventId, string message, params object[] args)
public static void LogWarning(this ILogger logger, Exception exception, string message, params object[] args)
public static void LogWarning(this ILogger logger, string message, params object[] args)

public static void LogError(this ILogger logger, EventId eventId, Exception exception, string message, params object[] args)
public static void LogError(this ILogger logger, EventId eventId, string message, params object[] args)
public static void LogError(this ILogger logger, Exception exception, string message, params object[] args)
public static void LogError(this ILogger logger, string message, params object[] args)

public static void LogCritical(this ILogger logger, EventId eventId, Exception exception, string message, params object[] args)
public static void LogCritical(this ILogger logger, EventId eventId, string message, params object[] args)
public static void LogCritical(this ILogger logger, Exception exception, string message, params object[] args)
public static void LogCritical(this ILogger logger, string message, params object[] args)

public static void Log(this ILogger logger, LogLevel logLevel, string message, params object[] args)
public static void Log(this ILogger logger, LogLevel logLevel, EventId eventId, string message, params object[] args)
public static void Log(this ILogger logger, LogLevel logLevel, Exception exception, string message, params object[] args)
public static void Log(this ILogger logger, LogLevel logLevel, EventId eventId, Exception exception, string message, params object[] args)
}

Add Logging with Serilog
Any provider that supplies an ILoggerFactory extension can be used for logging in ASP.NET Core, and Serilog is one such logging framework. The next sections cover creating a logging infrastructure based on Serilog and configuring the ASP.NET Core applications to use the new logging code.

The Logging Settings
To configure Serilog, we are going to use the application configuration files in conjunction with a C# class. Start by adding a new folder named Logging to the AutoLot.Service project. Create a new folder named Settings in the Logging folder, and in that new folder, add a class named AppLoggingSettings. Update the code to the following:
namespace AutoLot.Services.Logging.Settings; public class AppLoggingSettings
{
public GeneralSettings General { get; set; } public FileSettings File { get; set; }
public SqlServerSettings MSSqlServer { get; set; }

public class GeneralSettings
{
public string RestrictedToMinimumLevel { get; set; }
}
public class SqlServerSettings
{
public string TableName { get; set; } public string Schema { get; set; }
public string ConnectionStringName { get; set; }
}

public class FileSettings
{
public string Drive { get; set; } public string FilePath { get; set; } public string FileName { get; set; } public string FullLogPathAndFileName =>

$"{Drive}{Path.VolumeSeparatorChar}{Path.DirectorySeparatorChar}{FilePath}{Path. DirectorySeparatorChar}{FileName}";
}
}

Add the following global using statement to the GlobalUsings.cs file in the AutoLot.Service project.

global using AutoLot.Services.Logging.Settings;

Next, use the following JSON to replace the scaffolded Logging details in the appsettings.
Development.json files for the AutoLot.Api, AutoLot.Mvc, and AutoLot.Web projects:

"AppLoggingSettings": { "MSSqlServer": {
"TableName": "SeriLogs", "Schema": "Logging", "ConnectionStringName": "AutoLot"
},

"File": { "Drive": "c",
"FilePath": "temp", "FileName": "log_AutoLot.txt"
},
"General": {
"RestrictedToMinimumLevel": "Information"
}
},

Next, add the following AppName node to each of the files, customized for each app:

//AutoLot.Api "AppName":"AutoLot.Api - Dev"

//AutoLot.Mvc "AppName":"AutoLot.Mvc - Dev"

//AutoLot.Web "AppName":"AutoLot.Web - Dev"

For reference, here is the complete listing for each project (notice the extra line at the beginning of the AutoLot.Web file – that will be covered in chapter 34):

//AutoLot.Api
{
"AppLoggingSettings": { "MSSqlServer": {
"TableName": "SeriLogs", "Schema": "Logging", "ConnectionStringName": "AutoLot"
},
"File": { "Drive": "c",
"FilePath": "temp", "FileName": "log_AutoLot.txt"
},
"General": {
"RestrictedToMinimumLevel": "Information"
}
},
"ConnectionStrings": {
"AutoLot": "Server=.,5433;Database=AutoLot;User ID=sa;Password=P@ssw0rd;"
},
"RebuildDatabase": true, "AppName": "AutoLot.Api - Dev"
}

//AutoLot.Mvc
{
"AppLoggingSettings": { "MSSqlServer": {

"TableName": "SeriLogs", "Schema": "Logging", "ConnectionStringName": "AutoLot"
},
"File": { "Drive": "c",
"FilePath": "temp", "FileName": "log_AutoLot.txt"
},
"General": {
"RestrictedToMinimumLevel": "Information"
}
},
"ConnectionStrings": {
"AutoLot": "Server=.,5433;Database=AutoLot;User ID=sa;Password=P@ssw0rd;"
},
"RebuildDatabase": true, "UseApi": false, "ApiServiceSettings": {
"Uri": "https://localhost:5011/", "UserName": "AutoLotUser", "Password": "SecretPassword", "CarBaseUri": "api/v1/Cars", "MakeBaseUri": "api/v1/Makes"
},
"AppName": "AutoLot.Mvc - Dev"
}

//AutoLot.Web
{
"DetailedErrors": true, "AppLoggingSettings": {
"MSSqlServer": { "TableName": "SeriLogs", "Schema": "Logging",
"ConnectionStringName": "AutoLot"
},
"File": { "Drive": "c",
"FilePath": "temp", "FileName": "log_AutoLot.txt"
},
"General": {
"RestrictedToMinimumLevel": "Information"
}
},
"ConnectionStrings": {
"AutoLot": "Server=.,5433;Database=AutoLot;User ID=sa;Password=P@ssw0rd;"
},
"RebuildDatabase": true, "UseApi": false,

"ApiServiceSettings": {
"Uri": "https://localhost:5011/", "UserName": "AutoLotUser", "Password": "SecretPassword", "CarBaseUri": "api/v1/Cars", "MakeBaseUri": "api/v1/Makes"
},
"AppName": "AutoLot.Web - Dev"
}

The final step is to clear out the Logging section of each of the appsettings.json files, leaving just the AllowedHosts entry in the AutoLot.Api project, and the AllowedHosts and the DealerInfo in the AutoLot. Mvc and AutoLot.Web projects:

//AutoLot.Api
{
"AllowedHosts": "*"
}

//AutoLot.Mvc
{
"AllowedHosts": "*", "DealerInfo": {
"DealerName": "Skimedic's Used Cars", "City": "West Chester",
"State": "Ohio"
}
}

//AutoLot.Web
{
"AllowedHosts": "*", "DealerInfo": {
"DealerName": "Skimedic's Used Cars", "City": "West Chester",
"State": "Ohio"
}
}

The Logging Configuration
The next step is to configure Serilog. Get started by adding a new folder named Configuration in the Logging folder of the AutoLot.Service project. In this folder add a new class named LoggingConfiguration. Make the class public and static, as shown here:
namespace AutoLot.Services.Logging.Configuration; public static class LoggingConfiguration
{
}

Serilog uses sinks to write to different logging targets. With this mechanism, a single call to SeriLog will write to many places. The targets we will use for logging in the ASP.NET Core apps are a text file, the
database, and the console. The text file and database sinks require configuration, an output template for the text file sink, and a list of fields for the database sink.
To set up the file template, create the following static readonly string:

internal static readonly string OutputTemplate =
@"[{Timestamp:yy-MM-dd HH:mm:ss} {Level}]{ApplicationName}:{SourceContext}{NewLine} Message:{Message}{NewLine}in method {MemberName} at {FilePath}:{LineNumber}{NewLine}
{Exception}{NewLine}";

The SQL Server sink needs a list of columns identified using the SqlColumn type. Add the following code to configure the database columns:

internal static readonly ColumnOptions ColumnOptions = new ColumnOptions
{
AdditionalColumns = new List
{
new SqlColumn {DataType = SqlDbType.VarChar, ColumnName = "ApplicationName"}, new SqlColumn {DataType = SqlDbType.VarChar, ColumnName = "MachineName"},
new SqlColumn {DataType = SqlDbType.VarChar, ColumnName = "MemberName"}, new SqlColumn {DataType = SqlDbType.VarChar, ColumnName = "FilePath"}, new SqlColumn {DataType = SqlDbType.Int, ColumnName = "LineNumber"},
new SqlColumn {DataType = SqlDbType.VarChar, ColumnName = "SourceContext"}, new SqlColumn {DataType = SqlDbType.VarChar, ColumnName = "RequestPath"}, new SqlColumn {DataType = SqlDbType.VarChar, ColumnName = "ActionName"},
}
};

Swapping the default logger with Serilog is a three-step process. The first is to clear the existing provider, the second is to add Serilog into the WebApplicationBuilder, and the third is to finish configuring Serilog. Add a new method named ConfigureSerilog(), which is an extension method for the WebApplicationBuilder. The first line clears out the default loggers, and the last line adds the fully configured Serilog framework into the WebApplicationBuilder‘s logging framework.

public static void ConfigureSerilog(this WebApplicationBuilder builder)
{
builder.Logging.ClearProviders(); var config = builder.Configuration;
var settings = config.GetSection(nameof(AppLoggingSettings)).Get(); var connectionStringName = settings.MSSqlServer.ConnectionStringName;
var connectionString = config.GetConnectionString(connectionStringName); var tableName = settings.MSSqlServer.TableName;
var schema = settings.MSSqlServer.Schema;
string restrictedToMinimumLevel = settings.General.RestrictedToMinimumLevel; if (!Enum.TryParse(restrictedToMinimumLevel, out var logLevel))
{
logLevel = LogEventLevel.Debug;
}
var sqlOptions = new MSSqlServerSinkOptions
{
AutoCreateSqlTable = false,

SchemaName = schema, TableName = tableName,
};
if (builder.Environment.IsDevelopment())
{
sqlOptions.BatchPeriod = new TimeSpan(0, 0, 0, 1);
sqlOptions.BatchPostingLimit = 1;
}

var log = new LoggerConfiguration()
.MinimumLevel.Is(logLevel)
.Enrich.FromLogContext()
.Enrich.With(new PropertyEnricher("ApplicationName", config.GetValue("Applicati onName")))
.Enrich.WithMachineName()
.WriteTo.File(
path: builder.Environment.IsDevelopment()? settings.File.FileName : settings.File. FullLogPathAndFileName,
rollingInterval: RollingInterval.Day, restrictedToMinimumLevel: logLevel, outputTemplate: OutputTemplate)
.WriteTo.Console(restrictedToMinimumLevel: logLevel)
.WriteTo.MSSqlServer( connectionString: connectionString, sqlOptions, restrictedToMinimumLevel: logLevel, columnOptions: ColumnOptions);
builder.Logging.AddSerilog(log.CreateLogger(),false);
}

With everything in place, it’s time to create the logging framework that will use Serilog.

The AutoLot Logging Framework
The AutoLot logging framework leverages the built-in logging capabilities of ASP.NET Core to simplify using Serilog. It starts with the IAppLogging interface.

The IAppLogging Interface
The IApplogging interface holds the logging methods for the custom logging system. Add new directory named Interfaces in the Logging directory in the AutoLot.Service project. In this directory, add a new interface named IAppLogging. Update the code in this interface to match the following:
namespace AutoLot.Services.Logging.Interfaces; public interface IAppLogging
{
void LogAppError(Exception exception, string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);

void LogAppError(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);

void LogAppCritical(Exception exception, string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);

void LogAppCritical(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);

void LogAppDebug(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);

void LogAppTrace(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);

void LogAppInformation(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);

void LogAppWarning(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0);
}

The attributes CallerMemberName, CallerFilePath, and CallerLineNumber inspect the call stack to get the values they are named for from the calling code. For example, if the line that calls LogAppWarning() is in the DoWork() function, in a file named MyClassFile.cs, and resides on line number 36, then the call:

_appLogger.LogAppError(ex, "ERROR!");

is converted into the equivalent of this:

_appLogger.LogAppError(ex,"ERROR","DoWork ","c:/myfilepath/MyClassFile.cs",36);

If values are passed into the method call for any of the attributed parameters, the values passed in are used instead of the values from the attributes.
Add the following global using statement to the GlobalUsings.cs file in the AutoLot.Services project:

global using AutoLot.Services.Logging.Interfaces;

The AppLogging Class
The AppLogging class implements the IAppLogging interface. Add a new class named AppLogging to the Logging directory. Make the class public and implement IAppLogging and add a constructor that takes an instance of ILogger and stores it in a class level variable.

namespace AutoLot.Services.Logging;

public class AppLogging : IAppLogging
{
private readonly ILogger _logger;

public AppLogging(ILogger logger)
{
_logger = logger;
}
}

Serilog enables adding additional properties into the standard logging process by pushing them onto the LogContext. Add an internal method to log an event with an exception and push the MemberName, FilePath, and LineNumber properties. The PushProperty() method returns an IDisposable, so the method disposes everything before leaving the method.

internal static void LogWithException(string memberName,
string sourceFilePath, int sourceLineNumber, Exception ex, string message, Action<Exception, string, object[]> logAction)
{
var list = new List
{
LogContext.PushProperty("MemberName", memberName), LogContext.PushProperty("FilePath", sourceFilePath), LogContext.PushProperty("LineNumber", sourceLineNumber),
};
logAction(ex,message,null); foreach (var item in list)
{
item.Dispose();
}
}

Repeat the process for log events that don’t include an exception:

internal static void LogWithoutException(string memberName, string sourceFilePath, int sourceLineNumber, string message, Action<string, object[]> logAction)
{
var list = new List
{
LogContext.PushProperty("MemberName", memberName), LogContext.PushProperty("FilePath", sourceFilePath), LogContext.PushProperty("LineNumber", sourceLineNumber),
};

logAction(message, null); foreach (var item in list)
{
item.Dispose();
}
}

For each type of logging event, call the appropriate help method to write to the logs:

public void LogAppError(Exception exception, string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithException(memberName, sourceFilePath, sourceLineNumber, exception, message, _ logger.LogError);
}

public void LogAppError(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithoutException(memberName, sourceFilePath, sourceLineNumber, message, _logger. LogError);
}

public void LogAppCritical(Exception exception, string message, [CallerMemberName] string memberName = "",
[CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithException(memberName, sourceFilePath, sourceLineNumber, exception, message, _ logger.LogCritical);
}

public void LogAppCritical(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithoutException(memberName, sourceFilePath, sourceLineNumber, message, _logger. LogCritical);
}

public void LogAppDebug(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithoutException(memberName, sourceFilePath, sourceLineNumber, message, _logger.LogDebug);
}

public void LogAppTrace(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithoutException(memberName, sourceFilePath, sourceLineNumber, message, _logger. LogTrace);
}

public void LogAppInformation(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithoutException(memberName, sourceFilePath, sourceLineNumber, message, _logger. LogInformation);
}

public void LogAppWarning(string message, [CallerMemberName] string memberName = "", [CallerFilePath] string sourceFilePath = "", [CallerLineNumber] int sourceLineNumber = 0)
{
LogWithoutException(memberName, sourceFilePath, sourceLineNumber, message, _logger. LogWarning);
}

Final Configuration
The final configuration is to add the IAppLogging<> interface into the DI container and call the extension method to add SeriLog into the WebApplicationBuilder. Start by creating a new extension method in the LoggingConfiguration class:

public static IServiceCollection RegisterLoggingInterfaces(this IServiceCollection services)
{
services.AddScoped(typeof(IAppLogging<>), typeof(AppLogging<>)); return services;
}

Next, add the following global using statement to the GlobalUsings.cs file in each web project:

global using AutoLot.Services.Logging.Configuration; global using AutoLot.Services.Logging.Interfaces;

Next, add both of the extension methods to the top level statements in the Program.cs file. Note that the ConfigureSerilog() method extends off of the WebAppBuilder (the builder variable) and the RegisterLoggingInterfaces() method extends off of the IServiceCollection:

//Configure logging builder.ConfigureSerilog(); builder.Services.RegisterLoggingInterfaces();

Add Logging to the Data Services
With Serilog and the AutoLot logging system in place, it’s time to update the data services to add logging capabilities.

Update the Base Classes
Starting with the ApiDataServiceBase and DalDataServiceBase classes, update the generic definition to also accept a class that implements IDataServiceBase. This is to allow for strongly typing the IAppLogging interface to each of the derived class. Here are the updated classes definitions:

//ApiDataServiceBase.cs
public abstract class ApiDataServiceBase<TEntity, TDataService> : IDataServiceBase where TEntity : BaseEntity, new()
where TDataService : IDataServiceBase
{
//omitted for brevity
}

//DalDataServiceBase.cs
public abstract class DalDataServiceBase<TEntity, TDataService> : IDataServiceBase where TEntity : BaseEntity, new()
where TDataService : IDataServiceBase
{
//omitted for brevity
}

Next, update each of the constructors to take an instance of IAppLogging and assign it to a protected class field:

//CarApiDataService.cs
protected readonly IApiServiceWrapperBase ServiceWrapper;
protected readonly IAppLogging AppLoggingInstance;

protected ApiDataServiceBase(IAppLogging appLogging,
IApiServiceWrapperBase serviceWrapperBase)
{
ServiceWrapper = serviceWrapperBase;
AppLoggingInstance = appLogging;
}

//MakeApiDataService.cs
protected readonly IBaseRepo MainRepo;
protected readonly IAppLogging AppLoggingInstance;

protected DalDataServiceBase(IAppLogging appLogging, IBaseRepo mainRepo)
{
MainRepo = mainRepo;
AppLoggingInstance = appLogging;
}

Update the Entity Specific Data Services Classes
Each of the entity specific classes need to change their inheritance signature to use the new generic parameter and also take an instance of IAppLogging in the constructor and pass it to the base class. Here is the code for the updated classes:

//CarApiDataService.cs
public class CarApiDataService : ApiDataServiceBase<Car,CarApiDataService>, ICarDataService
{
public CarApiDataService( IAppLogging appLogging, ICarApiServiceWrapper serviceWrapper)
: base(appLogging, serviceWrapper) { }
//omitted for brevity
}

//MakeApiDataService.cs
public class MakeApiDataService
: ApiDataServiceBase<Make,MakeApiDataService>, IMakeDataService
{
public MakeApiDataService( IAppLogging appLogging, IMakeApiServiceWrapper serviceWrapper)
: base(appLogging,serviceWrapper) { }
}

//CarDalDataService.cs
public class CarDalDataService : DalDataServiceBase<Car,CarDalDataService>,ICarDataService
{
private readonly ICarRepo _repo;
public CarDalDataService(IAppLogging appLogging, ICarRepo repo) : base(appLogging, repo)
{
_repo = repo;
}
//omitted for brevity
}

//MakeApiDataService.cs
public class MakeDalDataService : DalDataServiceBase<Make,MakeDalDataService>,IMakeD ataService
{
public MakeDalDataService(IAppLogging appLogging,IMakeRepo repo)
: base(appLogging, repo) { }
}

Next, update the constructors to take the instance of IAppLogging and assign it to a protected class field:

Test-Drive the Logging Framework
To close out the chapter, let’s test the logging framework. The first step is to update the HomeController in the AutoLot.Mvc project to use the new logging framework. Replace the ILogger parameter with IAppLogging and update the type of the field, like this:

public class HomeController : Controller
{
private readonly IAppLogging _logger; public HomeController(IAppLogging logger)
{
_logger = logger;
}
//omitted for brevity
}

With this in place, log a test error in the Index() method:

public IActionResult Index([FromServices]IOptionsMonitor dealerMoitor)
{
_logger.LogAppError("Test error"); var vm = dealerMonitor.CurrentValue; return View(vm);
}

Run the AutoLot.Mvc project. When the app starts, a record will be logged in the SeriLogs table as well as written to a file named log_AutoLotYYYYMMDD.txt.
When you open the log file, you might be surprised to see that there are a lot of additional entries that didn’t come from the one call to the logger. That is because EF Core and ASP.NET Core emit very verbose logging when the log level is set to Information. To eliminate the noise, update the appsettings. Development.json files in the AutoLot.Api, AutoLot,Mvc, and AutoLot.Web projects so that the log level is Warning, like this:

"RestrictedToMinimumLevel": "Warning"

String Utilities
Recall that one of the conventions in ASP.NET Core removes the Controller suffix from controllers and the Async suffix from action methods when routing controllers and actions. When manually building up routes, it’s common to have to remove the suffix through code. While the code is simple to write, it can be repetitive. To cut down on repeating the string manipulation code, the next step will create two string extension methods.
Add a new directory named Utilities in the AutoLot.Services project, and in that directory, create a new public static class named StringExtensions. In that class, add the following two extension methods:
namespace AutoLot.Services.Utilities public static class StringExtensions
{
public static string RemoveControllerSuffix(this string original)
=> original.Replace("Controller", "", StringComparison.OrdinalIgnoreCase);

public static string RemoveAsyncSuffix(this string original)
=> original.Replace("Async", "", StringComparison.OrdinalIgnoreCase); public static string RemovePageModelSuffix(this string original)
=> original.Replace("PageModel", "", StringComparison.OrdinalIgnoreCase);
}

Next, add the following global using statement to the GlobalUsings.cs file in the AutoLot.Services project and all three web applications:

global using AutoLot.Services.Utilities;

Summary
This chapter dove into the new features introduced in ASP.NET Core and began the process of updating the three ASP.NET Core applications. In the next chapter, you will finish the AutoLot.Api application.

PART IX

ASP.NET Core

CHAPTER 30

Introducing ASP.NET Core

The final section of this book covers ASP.NET Core, C# and the .NET web development framework. The chapter begins with an introduction of ASP.NET MVC and the basics of the MVC pattern as implemented in ASP.NET Core. Next, you will create the solution and the three ASP.NET Core projects that will be developed over the course of the rest of the book. The first application, AutoLot.Api is an ASP.NET Core RESTful service, the second is an ASP.NET Core web application using the Model-View-Controller pattern and the final application is an ASP.NET Core web application using Razor pages. The RESTFul services serves as
an optional back end to the MVC and Razor Page applications, and the AutoLot.Dal and AutoLot.Models projects that you built earlier in this book will serve as the data access layer for all of the applications.
After building the projects and solution, the next section demonstrates the many ways to run and debug ASP.NET Core projects using Visual Studio or Visual Studio Code. The rest of this chapter explores the many features from ASP.NET that were carried forward into ASP.NET Core. This includes controllers and actions, routing, model binding and validation, and finally filters.

A Quick Look Back at ASP.NET MVC
The ASP.NET MVC framework is based on the Model-View-Controller pattern and provided an answer to developers who were frustrated by WebForms, which was essentially a leaky abstraction over
HTTP. WebForms was created to help client-server developers move to the Web, and it was pretty successful in that respect. However, as developers became more accustomed to web development, many wanted more control over the rendered output, elimination of view state, and adherence to a proven web application design pattern. With those goals in mind, ASP.NET MVC was created.

Introducing the MVC Pattern
The Model-View-Controller (MVC) pattern has been around since the 1970s, originally created as a pattern for use in Smalltalk. The pattern has made a resurgence recently, with implementations in many different and varied languages, including Java (Spring Framework), Ruby (Ruby on Rails), and .NET(ASP.NET MVC).

The Model
The model is the data of your application. The data is typically represented by plain old CLR objects (POCOs). View models are composed of one or more models and shaped specifically for the consumer of the data. One way to think about models and view models is to relate them to database tables and database views.
Academically, models should be extremely clean and not contain validation or any other business rules. Pragmatically, whether or not models contain validation logic or other business rules depends

© Andrew Troelsen, Phil Japikse 2022
A. Troelsen and P. Japikse, Pro C# 10 with .NET 6, https://doi.org/10.1007/978-1-4842-7869-7_30

1313

entirely on the language and frameworks used, as well as specific application needs. For example, EF Core contains many data annotations that double as a mechanism for shaping the database tables and a means for validation in ASP.NET Core web applications. In this book (and in my professional work), the examples focus on reducing duplication of code, which places data annotations and validations where they make the most sense.

The View
The view is the user interface of the application. Views accept commands and render the results of those commands to the user. The view should be as lightweight as possible and not actually process any of the work, but hand off all work to the controller. Views are typically strongly typed to a model, although that is not required.

The Controller
The controller is the brains of the application. Controllers take commands/requests from the user (via the view) or client (through API calls) through action methods, and handle them appropriately. The results of the operation are then returned to the user or client. Controllers should be lightweight and leverage other components or services to handle the details of the requests. This promotes separation of concerns and increases testability and maintainability.

ASP.NET Core and the MVC Pattern
ASP.NET Core is capable of creating many types of web applications and services. Two of the options are web applications using the MVC pattern and RESTful services. If you have worked with ASP.NET “classic,” these are analogous to ASP.NET MVC and ASP.NET Web API, respectively. The MVC web application and API application types share the “model” and the “controller” portion of the pattern, while MVC web applications also implement the “view” to complete the MVC pattern.

ASP.NET Core and .NET Core
Just as Entity Framework Core is a complete rewrite of Entity Framework 6, ASP.NET Core is a rewrite of the popular ASP.NET Framework. Rewriting ASP.NET was no small task, but it was necessary in order to remove the dependency on System.Web. Removing this dependency enabled ASP.NET applications to run on operating systems other than Windows and other web servers besides Internet Information Services (IIS), including self-hosted. This opened the door for ASP.NET Core applications to use a cross-platform, lightweight, fast, and open source web server called Kestrel. Kestrel presents a uniform development experience across all platforms.

■Note Kestrel was originally based on LibUV, but since ASP.NET Core 2.1, it is now based on managed sockets.

Like EF Core, ASP.NET Core is being developed on GitHub as a completely open source project (https://github.com/aspnet). It is also designed as a modular system of NuGet packages. Developers only install the features that are needed for a particular application, minimizing the application footprint,
reducing the overhead, and decreasing security risks. Additional improvements include a simplified startup, built-in dependency injection, a cleaner configuration system, and pluggable middleware.

One Framework, Many Uses
There are lots of changes and improvements in ASP.NET Core, as you will see throughout the rest of the chapters in this section. Besides the cross-platform capabilities, another significant change is the unification of the web application frameworks. ASP.NET Core encompasses ASP.NET MVC, ASP.NET Web API, and Razor Pages into a single development framework. Developing web applications and services with the ASP. NET (not ASP.NET Core) Framework presented several choices, including WebForms, MVC, Web API, Windows Communication Foundation (WCF), and WebMatrix. They all had their positives and negatives; some were closely related, and others were quite different. All of the choices available meant developers had to know each of them in order to select the proper one for the task at hand or just select one and hope for the best.
With ASP.NET Core, you can build applications that use Razor Pages, the Model-View-Controller pattern, RESTful services, and SPA applications using Blazor WebAssembly or JavaScript frameworks like Angular and React. While the UI rendering varies with choices between MVC, Razor Pages, and the
JavaScript frameworks, the underlying server side development framework is the same across all choices. Blazor WebAssembly is a client side development framework, and doesn’t have a server side component like the other ASP.NET Core application types. Two prior choices that have not been carried forward into ASP. NET Core are WebForms and WCF.

■Note With all of the separate frameworks brought under the same roof, the former names of ASP.NET MVC and ASP.NET Web API have been officially retired. In this book, I still refer to ASP.NET Core web applications using the Model-View-Controller pattern as MVC or MVC based applications and refer to ASP.NET rESTful services as API or rESTful services for simplicity.

Create and Configure the Solution and Projects
Before diving into the some of the major concepts in ASP.NET Core, let’s build the solution and projects that will be used through the rest of the chapters. The ASP.NET Core projects can be created using either Visual Studio or the command line. Both options will be covered in the next two sections.

Using Visual Studio 2022
Visual Studio has the advantage of a GUI to step you through the process of creating a solution and projects, adding NuGet packages, and creating references between projects.

Create the Solution and Projects
Start by creating a new project in Visual Studio. Select the C# template ASP.NET Core Web API from the “Create a new project” dialog. In the “Configure your new project” dialog, enter AutoLot.Api for the project name and AutoLot for the solution name, as shown in Figure 30-1.

Figure 30-1. Creating the AutoLot.Api project and AutoLot solution

On the Additional information screen, select .NET 6.0 (Long-term support) for the Framework and leave the “Configure for HTTPS” and “Enable OpenAPI” check boxes checked, as shown in Figure 30-2. Then click Create.

■Note Minimal APIs are a new feature in .NET 6 for creation without the traditional Controllers and action methods. These will not be covered in this text.

Figure 30-2. Selecting the ASP.NET Core Web API template

■Note hot reload is a new feature in .NET 6 that reloads your app while it is running when non-destructive changes are made, reducing the need to restart your application while developing to see changes. This has replaced razor runtime compilation, which was used in .NET 5 to accomplish the same goal.

Now add another ASP.NET Core web application to the solution. Select the “ASP.NET Core Web App (Model-View-Controller)” template. Name the project AutoLot.Mvc, then make sure that .NET Core 6.0 is selected, and the “Configure for HTTPS” option is checked as shown in Figure 30-3.

Figure 30-3. Configuring the ASP.NET Core MVC based Web Application template

Next, add the last ASP.NET Core web application to the solution. Select the “ASP.NET Core Web App” template. Name the project AutoLot.Web, then make sure that .NET Core 6.0 (Long-term support) is selected, and the “Configure for HTTPS” option is checked as shown in Figure 30-4.

Figure 30-4. Configuring the ASP.NET Core Razor page MVC Web Application template

Finally, add a C# Class Library to the project and name it AutoLot.Services.

Add in AutoLot.Models and AutoLot.Dal
The solution requires the completed data access layer which was completed in Chapter 23. You can also use the versions from Chapter 24, but that chapter was all about testing the finished data access layer and didn’t make any changes to the data access layer projects. You can either copy the files into the current solution directory or leave them in the place where you built them. Either way, you need to right-click your solution name in Solution Explorer, select Add ➤ Existing Project, and navigate to the AutoLot.Models.csproj file and select it. Repeat for the AutoLot.Dal project by selecting the AutoLot.Dal.csproj file.

Add the Project References
Add the following project references by right-clicking the project name in Solution Explorer and selecting Add ➤ Project Reference for each project.
AutoLot.Api, AutoLot.Web, and AutoLot.Mvc reference the following:
•AutoLot.Models
•AutoLot.Dal
•AutoLot.Services
AutoLot.Services references the following:
•AutoLot.Models
•AutoLot.Dal

Add the NuGet Packages
Additional NuGet packages are needed to complete the applications.
To the AutoLot.Api project, add the following packages:
•AutoMapper
•Microsoft.AspNetCore.Mvc.Versioning
•Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
•Microsoft.EntityFrameworkCore.Design
•Microsoft.EntityFrameworkCore.SqlServer
•Microsoft.VisualStudio.Web.CodeGeneration.Design
•Microsoft.VisualStudio.Threading.Analyzers
•System.Text.Json
•Swashbuckle.AspNetCore
•Swashbuckle.AspNetCore.Annotations
•Swashbuckle.AspNetCore.Swagger
•Swashbuckle.AspNetCore.SwaggerGen
•Swashbuckle.AspNetCore.SwaggerUI

■Note With the ASP.NET Core 6.0 API templates, Swashbuckle.AspNetCore is already referenced. The additional Swashbuckle packages add capabilities beyond the basic implementation.

To the AutoLot.Mvc project, add the following packages:
•AutoMapper
•System.Text.Json
•LigerShark.WebOptimizer.Core
•Microsoft.Web.LibraryManager.Build
•Microsoft.VisualStudio.Web.CodeGeneration.Design
•Microsoft.EntityFrameworkCore.Design
•Microsoft.EntityFrameworkCore.SqlServer
•Microsoft.VisualStudio.Threading.Analyzers
To the AutoLot.Web project, add the following packages:
•AutoMapper
•System.Text.Json
•LigerShark.WebOptimizer.Core
•Microsoft.Web.LibraryManager.Build

•Microsoft.VisualStudio.Web.CodeGeneration.Design
•Microsoft.EntityFrameworkCore.Design
•Microsoft.EntityFrameworkCore.SqlServer
•Microsoft.VisualStudio.Threading.Analyzers
To the AutoLot.Services project, add the following packages:
•Microsoft.Extensions.Hosting.Abstractions
•Microsoft.Extensions.Options
•Serilog.AspNetCore
•Serilog.Enrichers.Environment
•Serilog.Settings.Configuration
•Serlog.Sinks.Console
•Serilog.Sinks.File
•Serilog.Sinks.MSSqlServer
•System.Text.Json
•Microsoft.VisualStudio.Threading.Analyzers

Using the Command Line
As shown earlier in this book, .NET Core projects and solutions can be created using the command line. Open a prompt and navigate to the directory where you want the solution located.

■Note The commands listed use the Windows directory separator. If you are using a non-Windows operating system, adjust the separator characters as needed. They also use a specific directory path when adding the AutoLot. dal and AutoLot.Models projects to the solution, which will need to be updated based on the location of your projects.

The following commands create the AutoLot solution and add the existing AutoLot.Models and AutoLot.
Dal projects into the solution using the same options that were shown when using Visual Studio 2022:

rem create the solution dotnet new sln -n AutoLot
rem add autolot dal to solution update the path references as needed dotnet sln AutoLot.sln add ..\Chapter_23\AutoLot.Models
dotnet sln AutoLot.sln add ..\Chapter_23\AutoLot.Dal

Create the AutoLot.Service project, add it to the solution, add the NuGet packages and the project references.

rem create the class library for the application services and add it to the solution dotnet new classlib -lang c# -n AutoLot.Services -o .\AutoLot.Services -f net6.0 dotnet sln AutoLot.sln add AutoLot.Services

dotnet add AutoLot.Services package Microsoft.Extensions.Hosting.Abstractions dotnet add AutoLot.Services package Microsoft.Extensions.Options
dotnet add AutoLot.Services package Serilog.AspNetCore
dotnet add AutoLot.Services package Serilog.Enrichers.Environment dotnet add AutoLot.Services package Serilog.Settings.Configuration dotnet add AutoLot.Services package Serilog.Sinks.Console
dotnet add AutoLot.Services package Serilog.Sinks.File
dotnet add AutoLot.Services package Serilog.Sinks.MSSqlServer dotnet add AutoLot.Services package System.Text.Json
dotnet add AutoLot.Services package Microsoft.VisualStudio.Threading.Analyzers
rem update the path references as needed
dotnet add AutoLot.Services reference ..\Chapter_23\AutoLot.Models dotnet add AutoLot.Services reference ..\Chapter_23\AutoLot.Dal

Create the AutoLot.Api project, add it to the solution, add the NuGet packages and the project references.

dotnet new webapi -lang c# -n AutoLot.Api -au none -o .\AutoLot.Api -f net6.0 dotnet sln AutoLot.sln add AutoLot.Api
dotnet add AutoLot.Api package AutoMapper
dotnet add AutoLot.Api package Swashbuckle.AspNetCore
dotnet add AutoLot.Api package Swashbuckle.AspNetCore.Annotations dotnet add AutoLot.Api package Swashbuckle.AspNetCore.Swagger dotnet add AutoLot.Api package Swashbuckle.AspNetCore.SwaggerGen dotnet add AutoLot.Api package Swashbuckle.AspNetCore.SwaggerUI
dotnet add AutoLot.Api package Microsoft.VisualStudio.Web.CodeGeneration.Design dotnet add AutoLot.Api package Microsoft.EntityFrameworkCore.Design
dotnet add AutoLot.Api package Microsoft.EntityFrameworkCore.SqlServer dotnet add AutoLot.Api package Microsoft.VisualStudio.Threading.Analyzers dotnet add AutoLot.Api package System.Text.Json
dotnet add AutoLot.Api package Microsoft.AspNetCore.Mvc.Versioning
dotnet add AutoLot.Api package Microsoft.AspNetCore.Mvc.Versioning.ApiExplorer
rem add project references
rem update the path references as needed
dotnet add AutoLot.Api reference ..\Chapter_23\AutoLot.Dal dotnet add AutoLot.Api reference ..\Chapter_23\AutoLot.Models dotnet add AutoLot.Api reference AutoLot.Services

Create the AutoLot.Mvc project, add it to the solution, add the NuGet packages and the project references.

dotnet new mvc -lang c# -n AutoLot.Mvc -au none -o .\AutoLot.Mvc -f net6.0 dotnet sln AutoLot.sln add AutoLot.Mvc
rem add packages
dotnet add AutoLot.Mvc package AutoMapper dotnet add AutoLot.Mvc package System.Text.Json
dotnet add AutoLot.Mvc package LigerShark.WebOptimizer.Core dotnet add AutoLot.Mvc package Microsoft.Web.LibraryManager.Build
dotnet add AutoLot.Mvc package Microsoft.EntityFrameworkCore.Design

dotnet add AutoLot.Mvc package Microsoft.EntityFrameworkCore.SqlServer dotnet add AutoLot.Mvc package Microsoft.VisualStudio.Threading.Analyzers
dotnet add AutoLot.Mvc package Microsoft.VisualStudio.Web.CodeGeneration.Design
rem add project references
rem update the path references as needed
dotnet add AutoLot.Mvc reference ..\Chapter_23\AutoLot.Models dotnet add AutoLot.Mvc reference ..\Chapter_23\AutoLot.Dal dotnet add AutoLot.Mvc reference AutoLot.Services

Finally, create the AutoLot.Web project, add it to the solution, add the NuGet packages, and add the project references.

dotnet new webapp -lang c# -n AutoLot.Web -au none -o .\AutoLot.Web -f net6.0 dotnet sln AutoLot.sln add AutoLot.Web
rem add packages
dotnet add AutoLot.Web package AutoMapper dotnet add AutoLot.Web package System.Text.Json
dotnet add AutoLot.Web package LigerShark.WebOptimizer.Core dotnet add AutoLot.Web package Microsoft.Web.LibraryManager.Build
dotnet add AutoLot.Web package Microsoft.EntityFrameworkCore.SqlServer
dotnet add AutoLot.Web package Microsoft.EntityFrameworkCore.SqlServer.Design dotnet add AutoLot.Web package Microsoft.VisualStudio.Web.CodeGeneration.Design dotnet add AutoLot.Web package Microsoft.VisualStudio.Threading.Analyzers
rem add project references
rem update the path references as needed
dotnet add AutoLot.Web reference ..\Chapter_23\AutoLot.Models dotnet add AutoLot.Web reference ..\Chapter_23\AutoLot.Dal dotnet add AutoLot.Web reference AutoLot.Services

That completes the setup using the command line. As you can probably see, it is much more efficient provided you don’t need the Visual Studio GUI to help you.

■Note At the time of this writing, Visual Studio created projects with files that use nested namespaces, while the CLI tooling creates files that use file scoped namespaces.

Update the Entity Framework Core Package Reference
Recall from the EF Core chapters that to clear out temporal tables, the Microsoft.EntityFrameworkCore. Design package reference must be modified. Update the reference in the project files for the AutoLot.Api, AutoLot.Mvc, and AutoLot.Web projects to the following:

<PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="6.0.0>

all

Disable Nullable Reference Types For All Projects
At this time, disable nullable reference types by updating each of the project files’ PropertyGroup to the following:

net6.0
disable
enable

Create a GlobalUsing.cs Class in Each Project
The final setup step is to add a file named GlobalUsings.cs to the root folder of each project and clear out any scaffolded code. These will be used to hold the using statements for each project.

Running ASP.NET Core Applications
Previous versions of ASP.NET web applications always ran using IIS (or IIS Express). With ASP.NET Core, applications typically run using the Kestrel web server with an option to use IIS, Apache, Nginx, etc., by way of a reverse proxy between Kestrel and the other web server. This shift from requiring IIS to allowing other web servers not only changes the deployment model, but also changes the development possibilities. During development, you can now run your applications in these ways:
•From Visual Studio, using Kestrel or IIS Express
•From a command prompt with the .NET CLI, using Kestrel
•From Visual Studio Code, using Kestrel, from the Run menu
•From Visual Studio Code’s Terminal window using the .NET CLI and Kestrel
When using any of these options, the application’s ports and environment are configured with a file named launchsettings.json located under the Properties folder. The launchsettings.json file for the AutoLot.Mvc project is listed here for reference (your ports for both the IIS Express and AutoLot.Mvc profiles will be different):

{
"iisSettings": { "windowsAuthentication": false, "anonymousAuthentication": true, "iisExpress": {
"applicationUrl": "http://localhost:42788", "sslPort": 44375
}
},
"profiles": {
"AutoLot.Mvc": { "commandName": "Project", "dotnetRunMessages": true, "launchBrowser": true,
"applicationUrl": "https://localhost:5001;http://localhost:5000", "environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",

}
},
"IIS Express": { "commandName": "IISExpress", "launchBrowser": true, "environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development",
}
}
}
}

Using Visual Studio
The first profile defines the settings when using Kestrel as the web server. The Kestrel profile is always named after the project (e.g., AutoLot.Mvc) when it is created, but can be changed to any other name. The iisSettings section and the IIS Express profile together define the settings when running the application using IIS Express as the web server. The most important settings to note are the applicationUrl, which also defines the port, and the environmentVariables block, which defines the environment variables to
use when debugging. Any environment variables defined in this section supersede any user or machine environment settings with the same name.
The Run command in Visual Studio allows for choosing either the Kestrel or IIS Express profile, as shown in Figure 30-5. Once a profile is selected, you can run the project by pressing F5 (debug mode), pressing Ctrl+F5 (the same as “Start Without Debugging” in the Debug menu), or clicking the green run arrow (the same as “Start Debugging” in the Debug menu). New in .NET 6 and Visual Studio 2022, the Kestrel profile is set as the default.

Figure 30-5. The available Visual Studio debugging profiles

■Note There is also an option to create additional profiles, such as running using the WSL (Windows Subsystem for Linux). This feature isn’t covered in this book, but if you are curious to learn more, there is a book on the topic titled Pro Windows Subsystem for Linux (https://link.springer.com/ book/10.1007/978-1-4842-6873-5z)

Using Visual Studio Code
To run the projects from Visual Studio Code, open the folder where the solution is located. When you press F5 (or click Run), VS Code will prompt you to select the runtime to use (select .NET 6+ and .NET Core) and which project to run (AutoLot.Api, AutoLot.Web, or AutoLot.Mvc). It will then create a run configuration and place it in a file named launch.json. The launch settings only have to be configured the first time. Once the files exists, you can freely run/debug your application without having to make the selections again. Visual Studio Code uses the Kestrel profile when running your application.

Using the Command Line or Terminal Window
Running from the command line for ASP.NET Core apps is the same as any other .NET application that you have seen in this book. Simply navigate to the directory where the csproj file for your application is located and enter the following command:

dotnet run

This starts your application using the Kestrel profile. To end the process, press Ctrl+C.

Changing Code While Debugging
When running from the command line using dotnet run, the code in your application’s projects can be changed, but the changes won’t be reflected in the running app. To have the changes reflected in the running app, enter the following command:

dotnet watch

This command runs with Hot Reload enabled. Hot Reload is a new feature in .NET 6 that attempts to reload your app in real time when changes are made. This is a vast improvement over the .NET 5 dotnet watch run command, which restarted your entire app when a file watcher noticed changes.
Not all changes can be reloaded in real time, as some do require a restart of your app. If this is needed, you will be prompted to restart your application. If the prompt doesn’t appear, you can force a reload by using Ctrl+R in the terminal window. To cancel the application, hit Ctrl+C.
Hot Reload is also available when debugging with Visual Studio 2022 or Visual Studio Code.

Debugging ASP.NET Core Applications
When running your application from Visual Studio or Visual Studio Code, debugging works as expected. When running from the command line, you have to attach to the running process before you can debug your application.

Attaching with Visual Studio
After launching your app (with dotnet run or dotnet watch run), select Debug ➤ Attach to Process in Visual Studio. When the Attach to Process dialog appears, filter the process by your application name, as shown in Figure 30-6.

Figure 30-6. Attaching to the running applications for debugging in Visual Studio

Once attached to the running process, you can set breakpoints in Visual Studio, and debugging works as expected. Hot reload is enabled when you attach to the running process, so the edit and continue experience is getting better, although not yet to the level it was in prior versions of the .NET framework.

Attaching with Visual Studio Code
After launching your app (with dotnet run or dotnet watch run), select .NET Core Attach instead of .NET Core Launch (web) by clicking the green run arrow in VS Code, as shown in Figure 30-7.

Figure 30-7. Attaching to the running applications for debugging in Visual Studio Code

When you click the Run button, you will be prompted to select which process to attach. Select your application. You can now set breakpoints as expected.

Update the AutoLot.Api and AutoLot.Web Kestrel Ports
You might have noticed that AutoLot.Api, AutoLot.Web, and AutoLot.Mvc have different ports specified for the IIS Express and Kestrel profiles. Instead of remembering each of the randomly assigned ports, update all of the projects settings as follows:

//AutoLot.Mvc launchSettins.json "AutoLot.Mvc": {
"commandName": "Project", "launchBrowser": true, "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development"
},
"applicationUrl": "https://localhost:5001;http://localhost:5000",
"dotnetRunMessages": true
},
//AutoLot.Api launchSettins.json "AutoLot.API": {
"commandName": "Project", "dotnetRunMessages": true, "launchBrowser": true, "launchUrl": "swagger",
"applicationUrl": "https://localhost:5011;http://localhost:5010",
"environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development"
}
},
//AutoLot.Web launchSettins.json "AutoLot.Web": {
"commandName": "Project", "dotnetRunMessages": true, "launchBrowser": true,
"applicationUrl": "https://localhost:5021;http://localhost:5020",
"environmentVariables": {

"ASPNETCORE_ENVIRONMENT": "Development"
}
},

ASP.NET Core Concepts from MVC/Web API
Many of the design goals and features that brought developers to use ASP.NET MVC and ASP.NET Web API are still supported (and improved) in ASP.NET Core. Some of these (but not all) are listed here:
•Convention over configuration
•Controllers and actions
•Cleaner directory structure
•Model binding
•Model validation
•Routing
•Filters
•Layouts and Razor Views
These items are all covered in the next sections, except for layouts and Razor views, which are covered in a later chapter.

■Note razor page based applications are new in ASP.NET Core, however many of the concepts covered in this section also apply to this new application type. razor page based applications will be formally introduced in the next chapter.

Convention over Configuration
ASP.NET MVC and ASP.NET Web API reduced the amount of configuration necessary by introducing certain conventions. When followed, these conventions reduce the amount of manual (or templated) configuration, but also require the developers to know the conventions in order to take advantage of them. Two of the main conventions include naming conventions and directory structure.

Naming Conventions
There are multiple naming conventions in ASP.NET Core, for MVC style and RESTful service applications as well as Razor page based applications. For example, controllers are typically named with the Controller suffix (e.g., HomeController) in addition to deriving from Controller (or ControllerBase). When accessed through routing, the Controller suffix is dropped. When routing to async action methods named with the suffix Async, the Async suffix is dropped. Razor pages’ code behind files are named with the Model suffix
(ErrorModel), which is dropped just like the Controller and Async suffixes. This convention of dropping the suffix is repeated throughout ASP.NET Core.
Another naming convention is used in locating the views for a controller’s action methods. When looking for a controller’s views, the controller name minus the suffix is the starting search location. By default, an action method will render the view of the same name as the method.
There will be many examples of ASP.NET Core conventions covered in the following chapters.

Controllers and Actions (MVC Based Web Apps and RESTful Services)
Just like ASP.NET MVC and ASP.NET Web API, controllers and action methods are the workhorses of an ASP. NET Core MVC style web application or RESTful service application.

■Note razor pages derive from the PageModel class, which will be covered in the next chapter.

The Controller Class
As mentioned already, ASP.NET Core unified ASP.NET MVC5 and ASP.NET Web API. This unification also combines the Controller, ApiController, and AsyncController base classes from MVC5 and Web API
2.1into one new class, Controller, which has a base class of its own named ControllerBase. ASP.NET Core web application controllers inherit from the Controller class, while ASP.NET Core service controllers inherit from the ControllerBase class (covered next).
The Controller class provides a host of helper methods for MVC style web applications. Table 30-1 lists the most commonly used methods.

Table 30-1. Some of the Helper Methods Provided by the Controller Class

Helper Method Meaning in Life
ViewDataTempDataViewBag Provide data to the view through the ViewDataDictionary, TempDataDictionary, and dynamic ViewBag transport.
View Returns a ViewResult (derived from ActionResult) as the HTTP response. Defaults to a view of the same name as the action method, with the option of specifying a specific view. All options allow specifying a view model that is strongly typed and sent to the View.
PartialView Returns a PartialViewResult to the response pipeline.
ViewComponent Returns a ViewComponentResult to the response pipeline.
Json Returns a JsonResult containing an object serialized as JSON as the response.
OnActionExecuting Executes before an action method executes.
OnActionExecutionAsync Async version of OnActionExecuting.
OnActionExecuted Executes after an action method executes.

The ControllerBase Class
The ControllerBase class provides the core functionality for both ASP.NET Core MVC style web applications and RESTful services, in addition to helper methods for returning HTTP status codes. Table 30-2 lists some of the core functionality in ControllerBase.

Table 30-2. Some of the Helper Methods Provided by the ControllerBase Class

Helper Method Meaning in Life
HttpContext Returns the HttpContext for the currently executing action.
Request Returns the HttpRequest for the currently executing action.
Response Returns the HttpResponse for the currently executing action.
RouteData Returns the RouteData for the currently executing action (routing is covered later in this chapter).
ModelState Returns the state of the model in regard to model binding and validation (both covered later in this chapter).
Url Returns an instance of the IUrlHelper, providing access to building URLs for ASP.NET Core MVC applications and services.
User Returns the ClaimsPrincipal user.
Content Returns a ContentResult to the response. Overloads allow for adding a content type and encoding definition.
File Returns a FileContentResult to the response.
Redirect A series of methods that redirect the user to another URL by returning a
RedirectResult.
LocalRedirect A series of methods that redirect the user to another URL only if the URL is local. More secure than the generic Redirect methods.
RedirectToActionRedirect ToPageRedirectToRoute A series of methods that redirect to another action method, Razor Page, or named route. Routing is covered later in this chapter.
TryUpdateModelAsync Used for explicit model binding (covered later in this chapter).
TryValidateModel Used for explicit model validation (covered later in this chapter).

And Table 30-3 covers some of the helper methods for returning HTTP status codes.

Table 30-3. Some of the HTTP Status Code Helper Methods Provided by the ControllerBase Class

Helper Method HTTP Status Code Action Result Status Code
NoContent NoContentResult 204
Ok OkResult 200
NotFound NotFoundResult 404
BadRequest BadRequestResult 400
CreatedCreatedAt ActionCreatedAtRoute CreatedResultCreatedAtAction ResultCreateAtRouteResult 201
AcceptedAcceptedAt ActionAcceptedAtRoute AcceptedResultAccepted AtActionResultAcceptedAtRouteResult 202

Actions
Actions are methods on a controller that return an IActionResult (or Task for async operations) or a class that implements IActionResult, such as ActionResult or ViewResult.
This example returns a ViewResult in an MVC based application:

public async Task Index()
=> View(await _serviceWrapper.GetCarsAsync());

This example returns an HTTP status code of 200 with a list of Car records as JSON:

[Produces("application/json")]
public ActionResult<IEnumerable> GetCarsByMake(int? id)
{
return Ok(MainRepo.GetAll());
}

Actions and their return values will be covered more in the following chapters.

Antiforgery Tokens
ASP.NET Core uses antiforgery middleware to help combat against cross-site request forgery attacks. ASP. NET Core uses the Synchronizer Token Pattern (STP) which creates a server side token that is unique and unpredictable. That token is sent to the browser with the response. Any request that comes back to the server must include the correct token, or the request is refused.

Opting In (MVC Style Web Apps)
Receiving the token and validating it is handled in the action methods for MVC style web applications(MVC). To validate the token, simply add the ValidateAntiForgeryToken attribute to every HTTP Post method in your application, like this:

[HttpPost]
[ValidateAntiForgeryToken]
public async Task Create (Car entity)
{
//do important stuff
}

To opt out of the check, simply leave the ValidateAntiForgeryToken attribute off of the method.

■Note Adding the antiforgery token to the response will be covered along with tag helpers and views.

Opting Out (Razor Page Web Apps)
Razor page base applications automatically participate in the antiforgery pattern. To opt out of participating, add the IgnoreAntiforgeryToken to the PageModel class:

[IgnoreAntiforgeryToken]
public class ErrorModel : PageModel
{
//Omitted for brevity
}

Directory Structure Conventions
There are several folder conventions that you must understand to successfully build ASP.NET Core web applications and services. Many of the directories from Web API/MVC are the same (Controllers, Views, Areas) while there are some new ones (e.g., Pages, wwwroot). You will find the directory structure improved from MVC/WebAPI.

The Controllers Folder
By convention, the Controllers folder is where the ASP.NET Core MVC and API implementations (and the routing engine) expect that the controllers for your application are placed.

The Views Folder
The Views folder is where the views for an MVC style application are stored. Each controller gets its own folder under the main Views folder named after the controller name (minus the Controller suffix). The action methods will render views in their controller’s folder by default. For example, the Views/Home folder holds all the views for the HomeController controller class.

The Shared Folder
A special folder under Views is named Shared. This folder is accessible to all controllers and their action methods. After searching the folder named for the controller, if the view can’t be found, then the Shared folder is searched for the view.

The Pages Folder
The Pages folder is where the pages for the application are stored when building web applications using Razor pages. The directory structure under the Pages folder sets the base route for each page (more on routing later).

The Shared Folder
A special folder under Pages is named Shared. This folder is accessible to all pages in a Razor page based web application.

The Areas Folder
Areas are a feature that is used to organize related functionality into a group as a separate namespace for routing and folder structure for views and Razor pages. Each area gets its own set of controllers (API
applications), controllers and views (MVC style applications), and pages (Razor page based applications). An application can have zero to many areas, and each area goes under the parent Areas folder.

The wwwroot Folder
An improvement in ASP.NET Core web applications over the previous framework versions is the creation of a special folder named wwwroot. In ASP.NET MVC, the JavaScript files, images, CSS, and other client-side content were intermingled with all the other folders. In ASP.NET Core, the client side files are all contained under the wwwroot folder. This separation of compiled files from client-side files significantly cleans up the project structure when working with ASP.NET Core.
There is an exception to this conventions that relates to view and page specific CSS files. Those are stored alongside the views/pages they target. They will be covered in later chapters.

Routing
Routing is how ASP.NET Core matches HTTP requests to the proper code (the executable endpoints) to handle those requests as well as create URLs from the executable end points. This is accomplished with routing middleware registered in the Startup class (pre-C# 10) or the top level statements in the Program.cs file (C# 10 and later).
A route in an MVC based web application consists of an (optional) area, a controller, an action method, an HTTP verb (POST or GET), and (optional) additional values (called route values). Routes in ASP.NET Core RESTful services consists of an (optional) area, a controller, an (optional) action method, an HTTP Verb (POST, PUT, GET, DELETE, etc.), and (optional) additional route values. When defining routes for ASP.NET RESTful services, an action method is not usually specified. Instead, once the controller is located, the action method to execute is based on the HTTP verb of the request. In MVC style web applications and RESTful services, routes can be configured along in the middleware or through route attributes on controllers and action methods.
A route in a Razor page based application is the directory structure of the application, an HTTP Verb, the page itself, and (optional) additional route values. In addition to the default constructs, all ASP.NET style applications can create a route that ignores the standard templates. In Razor page based applications, routes are based on the directory structure of the application, with additional tokens available as part of the @page directive. All of this is covered in more detail shortly.

URL Patterns and Route Tokens
Route definitions are composed of URL patterns that contain variable placeholders (called tokens) and (optional) literals placed into an ordered collection known as the route table. Each entry in the route table must define a different URL pattern to match. Table 30-4 lists the reserved token names and their definitions.

Table 30-4. Reserved Route Tokens for MVC Styled and RESTful Service Applications

Token Meaning in Life
Area Defines the area for the route
Controller Defines the controller (minus the controller suffix)
Action Defines the action method name

• or Catch-all parameter. When used as a prefix to a route parameter, it binds the rest of the URI. For example, car/{slug} matches any URI that starts with /car and has any value following it. The following value is assigned to the slug route value. Using a double * in the path preserves path separator characters while a single does not.

Handling Duplicate C# Method Signatures
The action token by default matches the C# method name on a controller. The ActionName attribute can be used to change in relation to routing. For example, the following code specifies the HTTP Get and HTTP Post action methods with the name and same signature. C# doesn’t allow two methods with the same signature with the same name, so a compiler error occurs:

[HttpGet]
public async Task Create()
{
//do something
}

[HttpPost] [ValidateAntiForgeryToken]
//Compiler error
public async Task Create()
{
//Do something else
}

The solution is to rename one of the methods and add the ActionName attribute to change the name used by the routing engine:

[HttpPost] [ActionName("Create")] [ValidateAntiForgeryToken]
public async Task CreateCar()
{
//Do something else
}

Custom Route Tokens
In addition to the reserved tokens, routes can contain custom tokens that are mapped (model bound) to a controller action method’s or Razor page handler method’s parameters. When defining routes using
tokens, there must be a literal value separating the tokens. While {controller}/{action}/{id?} is valid,
{controller}{action}{id?} is not.

Route Token Constraints
Route tokens can also be constrained to disambiguate similar routes. Table 30-5 shows the available route token constraints. Note that the constraints are not meant to be used for validation. If a route value is invalid based on a constraint (e.g., too big for the int constraint), the routing engine will not find a match and returns a 404 (Not Found). However, business logic would probably require that a 400 (Bad Request) be returned instead.

Table 30-5. Route Tokens Constraints for MVC Styled and RESTful Service Applications

Constraint Example Meaning in Life
Int {id:int} Matches any integer.
Bool {active:bool} Matches true or false. Case insensitive.
datetime {dob:datetime} Matches a valid DateTime value in the invariant culture.
decimal {price:decimal} Matches a valid decimal value in the invariant culture.
double {weight:double} Matches a valid double value in the invariant culture.
Float {weight:float} Matches a valid float value in the invariant culture.
Guid {id:guid} Matches a valid GUID value.
Long {ticks:long} Matches a valid long value in the invariant culture.
minlength(value) {name:minlength(4)} String must be at least value characters long.
maxlength(value) {name:maxlength(12)} String must be at most value characters long.
length(value) {name:length(12)} String must be exactly value characters long.
min(value) {age:min(18)} Integer must be at least value
max(value) {age:max(65)} Integer must be at most value
range(min,max) {age:range(12,65)} Integer must be between min and max
alpha {name:alpha} String must only contain letters a-z, case insensitive.
regex(expression) {ssn:regex(^\d{{3}}-
\d{{2}}-\d{{4}}$)} String must match regular expression.
required {name:required} Value is required.

Conventional Routing (MVC Style Web Apps)
Conventional routing builds the route table in the Startup class (pre-.NET6) or in the Program.cs file’s top level statements (.NET6+). The MapControllerRoute() method adds an endpoint into the route table. The method specifies a name, URL pattern, and any default values for the variables in the URL pattern. In the following code sample, the predefined {controller} and {action} placeholders refer to a controller (minus the Controller suffix) and an action method contained in that controller. The placeholder {id} is custom and is translated into a parameter (named id) for the action method. Adding a question mark to a
route token indicates that it is an optional route value and is represented in the action method as a nullable parameter.

app.UseRouting(); app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}"
);

When a URL is requested, it is checked against the route table. If there is a match, the HTTP Verb (Post, Get, etc.) of the request is also checked to make sure the code located at that application endpoint accepts the request’s verb. For example, an HTTP Post with the URL (minus the scheme and domain) Car/Delete/5 comes into the application. From the following two actions, the second delete action method would be targeted (since it is marked with the [HttpPost] attribute), passing in 5 as the value for the id parameter:

public class CarController : ControllerBase
{
[HttpGet]
public async Task Delete(int? id)
{
//return a view
}

[HttpPost] [ValidateAntiForgeryToken]
public async Task Delete(int id, Car car)
{
//delete the record
}
}

The defaults specify how to fill in the blanks for URLs that don’t contain all of the defined components. In the previous code, if no additional route values were specified in the URL (such as http:// localhost:5001), then the routing engine would call the Index() action method of the HomeController class, without an id parameter. The defaults are progressive, meaning that they can be excluded from right
to left. However, route parts can’t be skipped. Entering a URL like http://localhost:5001/Delete/5 will fail the {controller}/{action}/{id} pattern.
Conventional routing is order dependent. The routing engine starts at the top of the route table and will attempt to find the first matching route based on the (optional) area, controller, action, custom tokens, and HTTP verb. If the routing engine finds more than one end point that matches the route plus HTTP Verb it will throw an AmbiguousMatchException. If the routing engine can’t find a matching route, it will return a 404.
Notice that the route template doesn’t contain a protocol or hostname. The routing engine automatically prepends the correct information when creating routes and uses the HTTP verb, path, and parameters to determine the correct application endpoint. For example, if your site is running on https:// www.skimedic.com, the protocol (HTTPS) and hostname (www.skimedic.com) is automatically prepended
to the route when created (e.g., https://www.skimedic.com/Car/Delete/5). For an incoming request, the routing engine uses the Car/Delete/5 portion of the URL.

Area Routes
If your application contains an area, there is an additional route pattern that needs to be mapped. Instead of using MapControllerRoute(), call MapAreaControllerRoute(), like this:

app.UseRouting(); app.MapAreaControllerRoute(
name:"areaRoute", areaName:"Admin",
pattern:"Admin/{controller}/{action}/{id?}");

Since area routes are more specific than the non-area routes, they are typically added to the route table first, like this:

app.UseRouting(); app.MapAreaControllerRoute(
name:"areaRoute", areaName:"Admin",
pattern:"Admin/{controller}/{action}/{id?}"); app.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");

Named Routes
Route names can be used as a shorthand to generate URLs from within the application. In the preceding conventional route, the endpoint is assigned the name default.

Attribute Routing (MVC Style Web Apps and RESTful Services)
Attribute routing works the same way as conventional routing when matching routes with application endpoints and HTTP verbs. The difference is how the routes are configured. In attribute routing, routes are defined using C# attributes on controllers and their action methods. This can lead to more precise routing, but can also increase the amount of configuration, since every controller and action needs to have routing information specified. Before we look at examples of attribute routing, it must be enabled in the Startup class (pre .NET 6) or the Program.cs file’s top level statements (.NET6+) by calling MapControllers():

app.MapControllers();

For an example of attribute routing, take the following code snippet. The four Route attributes on the Index() action method equate to the same default route defined earlier. The Index() action method is the application endpoint for
•mysite.com ([Route("/")]),
•mysite.com/Home ([Route("/Home")]),
•mysite.com/Home/Index ([Route("/Home/Index")]), or
•mysite.com/Home/Index/5 ([Route("/Home/Index/{id?}")]).

public class HomeController : Controller
{
[Route("/")]
[Route("/Home")] [Route("/Home/Index")] [Route("/Home/Index/{id?}")]
public IActionResult Index(int? id)
{
...
}
}

In the previous example, the only route token used was for the optional id parameter. The same set of routes can be created using the controller and action route tokens, like this:

public class HomeController : Controller
{
[Route("/")]
[Route("/[controller]")]
[Route("/[controller]/[action]")]
[Route("/[controller]/[action]/{id?}")]
public IActionResult Index(int? id)
{
...
}
}

The major difference between conventional routing and attribute routing is that conventional routing covers the application, while attribute routing covers just the controller and its action methods with the Route attribute. If conventional routing is not used, every controller will need to have their route defined with attribute routing or they will not be able to be accessed. For example, if there wasn’t a default route defined in the route table (using conventional routing), the following code is not discoverable since the controller doesn’t have any routing configured:

public class CarController : Controller
{
public IActionResult Delete(int id)
{
...
}
}

■Note Conventional and attribute routing can be used together. If the default controller route was set as in the conventional routing example, the preceding controller would be located by the route table.

When routes are added at the controller level, the action methods derive from that base route. For example, the following controller route covers the Delete() (and any other) action method:

[Route("[controller]/[action]/{id?}")]
public class CarController : Controller
{
public IActionResult Delete(int id)
{
...
}
}

■Note The built-in tokens are distinguished with square brackets ([]) in attribute routing instead of the curly braces ({}) used in conventional routing. Custom tokens still use curly braces.

If an action method needs to restart the route pattern, prefix the route with a forward slash (/). For example, if the delete method should follow the URL pattern mysite.com/Delete/Car/5, configure the action as follows:

[Route("[controller]/[action]/{id?}")] public class CarController : Controller
{
[Route("/[action]/[controller]/{id}")]
public IActionResult Delete(int id)
{
...
}
}

As shown with the default attribute route example, route definitions can use literal route values instead of using token replacement. The following code will produce the same result for the Delete() action method as the previous code sample:

[Route("[controller]/[action]/{id?}")] public class CarController : Controller
{
[Route("/Delete/Car/{id}")]
public IActionResult Delete(int id)
{
...
}
}

Razor Page Routing
As mentioned already, Razor page routing is based on the folder structure of the application. To enable routing, call MapRazorPages() in the Startup class (pre .NET 6) or the Program.cs file’s top level statements (.NET6+):

app.UseRouting(); app.MapRazorPages();

For Razor page based web applications, the Index page is the default page for a directory. This means that if an Index.cshtml page is located at Pages/Cars/Index.cshtml, then both the routes that map to that page include /Cars and /Cars/Index.
Additional route tokens can be added after the @page directive to refine the route. Suppose you have a Car folder under the Pages folder, and in the Cars folder, there is a page named Delete.cshtml. The default route for this page is /Cars/Delete. To add an optional id token to accept a URI like /Cars/Delete/5, update the @page directive to the following:

@page "{id?}"

Just like routing for MVC style applications, the route can be reset using a forward slash (/). Once reset, you can add literals and tokens to completely change the route. For example, the route for the Delete. cshtml page can be updated to /Delete/Vehicle/5 by using the following:

@page "/Delete/Vehicle/{id?}

Routing and HTTP Verbs
As we have already discussed, none of the route templates define an HTTP verb. In MVC based applications and RESTful services, the action methods are decorated with attributes to indicate which HTTP verb it should handle. For Razor page based applications, the different HTTP verbs are handled with specific page handler methods.

HTTP Verbs in MVC Styled Web Application Attribute Routing
As discussed earlier, a common pattern in web applications using the MVC pattern, there will be two application endpoints that match a particular route template. The discriminator in these instances is the HTTP verb, as we saw with the CarController‘s two Delete() action methods.
Routes can also be modified using the HTTP verb attributes. For example, the following shows the optional id route token added to the route template for both Delete() methods:

[Route("[controller]/[action]")]
public class CarController : Controller
{
[HttpGet("{id?}")]
public IActionResult Delete(int? id)
{
...
}
[HttpPost("{id}")] [ValidateAntiForgeryToken]
public IActionResult Delete(int id, Car recordToDelete)
{
...
}
}

■Note Browsers only support get and post requests, so while you can decorate your MVC web application’s methods with additional hTTP Verb attributes (like HttpPut and HttpDelete), browsers will not be able to make the appropriate requests to leverage those endpoints.

Routes can also be restarted using the HTTP verbs; just preface the route templated with a forward slash (/), as the following example demonstrates:

[HttpGet("/[controller]/[action]/{makeId}/{makeName}")] public IActionResult ByMake(int makeId, string makeName)
{
ViewBag.MakeName = makeName;
return View(_repo.GetAllBy(makeId));
}

If an action method isn’t decorated with an HTTP verb attribute, it defaults to accepting HTTP get requests. However, in MVC styled web applications, unmarked action methods can also respond to HTTP post requests, which might cause unexpected results. For this reason, it’s considered a best practice to mark all action methods explicitly with the correct verb attribute.

HTTP Verbs in RESTful Service Routing
Route definitions used for RESTful services typically do not specify action methods. When action methods are not part of the route template, the action methods are selected based on the HTTP verb of the request (and optionally the content type). The following code shows an API controller with four methods that all match the same route template. Notice that the HTTP verb attributes are different for each of the action methods:

[Route("api/[controller]")] [ApiController]
public class CarController : ControllerBase
{
[HttpGet("{id}")]
public IActionResult GetCarsById(int id)
{
...
}
[HttpPost("{id}")]
public IActionResult CreateANewCar(int id, Car entity)
{
...
}
[HttpPut("{id}")]
public IActionResult UpdateAnExistingCar(int id, Car entity)
{
...
}

[HttpDelete("{id}")]
public IActionResult DeleteACar(int id, Car entity)
{
...
}
}

If an action method doesn’t have an HTTP verb attribute, it is treated as the application endpoint for HTTP get requests. Just as with MVC style applications, if the route requested is matched but there isn’t an action method with the correct verb attribute, the server will return a 404 (not found).

■Note ASP.NET Web API allowed you to omit the hTTP verb for a method if the name started with Get, Put, Delete, or Post. This convention has been removed in ASP.NET Core. If an action method does not have an hTTP verb specified, it will be called using an hTTP get.

The final endpoint selector for API controllers is the optional Consumes attribute, which specifies the content type that is accepted by the endpoint. The request must use the matching content-type header, or a 415 Unsupported Media Type error will be returned. The following two example endpoints, both in the same controller, differentiate between JSON and XML:

[HttpPost] [Consumes("application/json")]
public IActionResult PostJson(IEnumerable values)
=> Ok(new { Consumes = "application/json", Values = values });
[HttpPost]
[Consumes("application/x-www-form-urlencoded")]
public IActionResult PostForm([FromForm] IEnumerable values)
=> Ok(new { Consumes = "application/x-www-form-urlencoded", Values = values });

■Note There is one additional (and optional) route selector for API controllers, and that involves versioning. Versioning API applications is covered in Chapter 32.

HTTP Verbs in Razor Page Routing
Once a Razor page is discovered as the endpoint for a route, the HTTP verb is used to determine the correct page handler method to execute. The following code sample for the Delete.cshtml page will execute the OnGet() method on get requests and the OnPost() method on post requests.

public class DeleteModel : PageModel
{
public IActionResult OnGet(int? id)
{
//handle the get request here
}

public IActionResult OnPost(int? id)
{
//handle the post request here
}
}

This will be covered in more depth in the next chapter.

Redirecting Using Routing
Another advantage of routing is that you no longer have to hard-code URLs for other pages in your site. The routing entries are used to match incoming requests as well as build URLs. When building URLs, the scheme, host, and port are added based on the values of the current request.
When redirecting in server side code (e.g., in a controller’s action method or in a Razor page), there are several redirect methods that can be used to redirect the execution path to another end point. Table 30-6 shows three of the redirect methods and their most commonly used overloads.

Table 30-6. Methods for Server-Side Redirecting of Requests

Method Meaning in Life
RedirectToAction() Redirects to an action. Overloaded parameter options include: actionName, controllerName, routeValues
If any of the parameters are not supplied, the values will be supplied by the current HTTP request.
RedirectToRoute() Redirects to a named route. Optional route values can be supplied.
RedirectToPage() Redirects to a Razor Page. Optional route values can be supplied.

For an example, the following code redirects the request from the Delete method to the Index method in the same controller (since a controller name wasn’t provided):

[HttpPost("{id}")]
public async Task Delete(int id, Car car)
{
//interesting code here
return RedirectToAction(nameof(Index));
}

Model Binding
Model binding is the process where ASP.NET Core uses the name-value pairs submitted in an HTTP Post call to assign values to models. The values are submitted using form fields, request body (for API style controllers), route data, query string parameters, or uploaded files. To bind to a reference type, the name- value pairs come from the form values or the request body, the reference types must have a public default constructor, and the properties to be bound must be public and writable.
When assigning values, implicit type conversions (such as setting a string property value using an int) are used where applicable. If type conversion doesn’t succeed, that property is flagged in error. Before discussing binding in greater detail, it’s important to understand the ModelState dictionary and its role in the binding (and validation) process.

The ModelState Dictionary
The ModelState dictionary contains an entry for every property being bound and an entry for the model itself. If an error occurs during model binding, the binding engine adds the errors to the dictionary entry for the property and sets ModelState.IsValid = false. If all matched properties are successfully assigned, the binding engine sets ModelState.IsValid = true.

■Note Model validation, which also sets the ModelState dictionary entries, happens after model binding. Both implicit and explicit model binding automatically call validation for the model. Validation is covered shortly.

How you handle the binding and/or validation errors varies based on the needs of your application. The following code sample from an API endpoint shows how to get all of the errors from the ModelState, create an anonymous object, and then return a BadRequestObject (HTTP status code 400) with the resulting object sent back in the body of the response as JSON:

[HttpPost] [ValidateAntiForgeryToken]
public async Task Update(Car entity)
{
if (!ModelState.IsValid)
{
IEnumerable errorList = ModelState.Values.SelectMany(v => v.Errors).Select(e=>e. ErrorMessage);
var responseContent =
new { Message = "One or more field validation errors occurred", Errors = errorList }; apiLogEntry.ResponseContentBody = JsonSerializer.Serialize(responseContent);
return new BadRequestObjectResult(responseContent);
}
//binding and validation was successful, execute the rest of the method
}

Adding Custom Errors to the ModelState Dictionary
In addition to the properties and errors added by the binding and validation engines, custom errors can be added to the ModelState dictionary. Errors can be added at the property level or for the entire model.
To add a specific error for a property (e.g., the PetName property of the Car entity), use the following:

ModelState.AddModelError("PetName","Name is required");

To add an error for the entire model, use string.Empty for the property name, like this:

ModelState.AddModelError(string.Empty, $"Unable to create record: {ex.Message}");

Clearing the ModelState Dictionary
There are times where you might need to clear the ModelState of all values and errors. To reset the ModelState, simply call the Clear() method, like this:

ModelState.Clear();

This is commonly used with explicit validation or when required properties are intentionally left out because of over posting concerns.

Implicit Model Binding
Implicit model binding occurs when the model to be bound is a parameter for an action method (MVC/API applications) or a handler method (Razor page applications). It uses reflection (and recursion for complex types) to match the model’s writable property names with the names contained in the name-value pairs posted to the action method. If there is a name match, the binder uses the value from the name-value pair to attempt to set the property value. If multiple names from the name-value pairs match, the first matching name’s value is used. If a property isn’t found in the name-value pairs, the property is set to its default value. The order the name-value pairs are searched is as follows:
•Form values from an HTTP Post method (including JavaScript AJAX posts)
•Request body (for API controllers)
•Route values provided through ASP.NET Core routing (for simple types)
•Query string values (for simple types)
•Uploaded files (for IFormFile types)
For example, the following method will attempt to set all of the properties on the Car type implicitly. If the binding process completes without error, the ModelState.IsValid property returns true.

[HttpPost] [ValidateAntiForgeryToken]
public ActionResult Create(Car entity)
{
if (ModelState.IsValid)
{
//Save the data;
}
}

Here an example OnPostAsync() method in a Razor page PageModel class that takes in an optional integer (from the route or query string) and an implicitly bound Car entity:

public async Task OnPostAsync(int? id, Car entity)
{
if (ModelState.IsValid)
{
//Save the data;
}
}

Explicit Model Binding
Explicit model binding is executed with a call to TryUpdateModelAsync(), passing in an instance of the type being bound and the list of properties to bind. The method then uses reflection to find matches between the property names and the names in the name-value pairs in the request. If the model binding fails, the method returns false and sets the ModelState errors in the same manner as implicit model binding.

When using explicit model binding, the type being bound isn’t a parameter of the action method (MVC/ API) or handler method (Razor pages). For example, you could write the previous Create() method this way and use explicit model binding:

[HttpPost] [ValidateAntiForgeryToken]
public async Task Create()
{
var newCar = new Car();
if (await TryUpdateModelAsync(newCar ,"", c=>c.Color,c=>c.PetName,c=>c.MakeId))
{
//do something important
}
}

Explicit model binding also works in Razor page handler methods:

public async Task OnPostAsync()
{
var newCar = new Car();
if (await TryUpdateModelAsync(newCar ,"", c=>c.Color,c=>c.PetName,c=>c.MakeId))
{
//do something important
}
}

■Note The second parameter (set to an empty string in these examples) will be covered shortly in the handling Property Name Prefixes section.

With implicit model binding, an instance is getting created for you. However, with explicit model binding, you must first create the instance then call TryUpdateModelAsync(), which attempts to update the values of that instance from the name value pairs sent in the request. Like explicit model binding, the binding engine ignores any properties without a matching name in the name-value pairs in the request.
Since you have to create the instance first with explicit model binding, you can set properties on your instance before calling TryUpdateModelAsync(), like this:

var newCar = new Car
{
Color = "Purple", MakeId = 1, PetName = "Prince"
};
if (await TryUpdateModelAsync(newCar,"", c=>c.Color,c=>c.PetName,c=>c.MakeId))
{
//do something important
}

In the previous example, any of the values set with the initial object initialization will retain their values if the property does not have a matching name in the name-value pairs in the request.

Property Model Binding
A property on a MVC style controller or a Razor page PageModel can be marked as the binding target for HTTP Post requests. This is accomplished by adding the public property to the class and marking it with the BindProperty attribute. When using property binding, the controller’s action methods or PageModel handler methods do not take the property as a parameter. Here are two examples that uses property binding on a Car property for an MVC style application and a Razor page PageModel:

//CarsController - MVC
public class CarsController : Controller
{
[BindProperty] public Car Entity { get; set; }

[HttpPost("{id}")] [ValidateAntiForgeryToken] [ActionName("Edit")]
public async Task Edit(int id)
{
//Handle the post request
} //omitted for brevity
}

//EditPage -- Razor
public class EditModel : PageModel
{
[BindProperty] public Car Entity { get; set; }

public async Task OnGet(int? id)
{
//Handle the HTTP Get request
}
public async Task OnPost(int id)
{
//Handle the HTTP Get request
}
}

By default, property binding only works with HTTP Post requests. If you need HTTP Get requests to also bind to the property, update the BindProperty attribute as follows:

[BindProperty(Name="car",SupportsGet = true)] public Car Entity { get; set; }

Handling Property Name Prefixes
Sometimes the data will come into your action method from a table, a parent-child construct, or a complex object that adds a prefix to the names in the name-value pairs. Recall that both implicit and explicit model binding uses reflection to match property names with names in the name-value pairs of the request, and prefixes to the names will prevent the matches from being made.

With implicit model binding, the Bind attribute is used to specify a prefix for the property names. The following example sets a prefix for the names:

[HttpPost] [ValidateAntiForgeryToken]
public ActionResult Create([Bind(Prefix="CarList")]Car car)
{
if (ModelState.IsValid)
{
//Save the data;
}
//handle the binding errors
}

With explicit model binding, the prefix is set in the TryUpdateModelAsync() method using the second parameter (which was just an empty string in the previous examples):

[HttpPost] [ValidateAntiForgeryToken]
public async Task Create()
{
var newCar = new Car();
if (await TryUpdateModelAsync(newCar,"CarList", c=>c.Color,c=>c.PetName,c=>c.MakeId))
{
//Save the data
}
//handle the binding errors
}

Preventing Over Posting
Over posting is when the request submits more values than you are expecting (or wanting). This can be accidental (the developer left too many fields in the form), or malicious (someone used browser dev tools to modify the form before submitting it). For example, presume you want the application to allow changing colors, names, or makes, but not the prices on Car records.
The Bind attribute in HTTP Post methods allows you to limit the properties that participate in implicit model binding. If a Bind attribute is placed on a reference parameter, the fields listed in the Include list are the only fields that will be assigned through model binding. If the Bind attribute is not used, all fields are bindable.
The following example uses the Bind attribute to only allow updating the PetName and Color fields in the Update() method:

[HttpPost] [ValidateAntiForgeryToken]
public ActionResult Update([Bind(nameof(Car.PetName),nameof(Car.Color))]Car car)
{
//body omitted for brevity
}

Here is the same example in a Razor page:

public async Task OnPostAsync(int? id, [Bind(nameof(Car.PetName),nameof(Car. Color))]Car car)
{
//body omitted for brevity
}

To prevent over posting when using explicit model binding, you remove the properties in the body of the TryUpdateModel() method’s body that shouldn’t be accepted. The following example only allows updating the PetName and Color fields in the Update() method:

[HttpPost] [ValidateAntiForgeryToken]
public async Task Update()
{
var newCar = new Car();
if (await TryUpdateModelAsync(newCar,"", c=>c.Color,c=>c.PetName))
{
//save the data
}
//Handle the binding errors
}

When using this method of implicit method of model binding, the Bind attribute can be used to prevent over posting:

public async Task OnPostAsync(int? id, [Bind(nameof(Car.PetName),nameof(Car. Color))]Car car)
{
//body omitted for brevity
}

You can also specify the binding source in Razor pages. The following instructs the binding engine to get the data from the request’s Form data:

public async Task OnPostAsync(int? id, [FromForm]Car car)
{
//body omitted for brevity
}

Controlling Model Binding Sources in ASP.NET Core
Binding sources can be controlled through a set of attributes on the action parameters. Custom model binders can also be created; however, that is beyond the scope of this book. Table 30-7 lists the attributes that can be used to control model binding.

Table 30-7. Controlling Model Binding Sources

Attribute Meaning in Life
BindingRequired A model state error will be added if binding cannot occur instead of just setting the property to its default value.
BindNever Tells the model binder to never bind to this parameter.
FromHeaderFromQuery FromRouteFromForm Used to specify the exact binding source to apply (header, query string, route parameters, or form values).
FromServices Binds the type using dependency injection (covered later in this chapter).
FromBody Binds data from the request body. The formatter is selected based on the content of the request (e.g., JSON, XML, etc.). There can be at most one parameter decorated with the FromBody attribute.
ModelBinder Used to override the default model binder (for custom model binding).

Here are two examples that show using the FromForm attribute. The first is in a RESTful service controller, and the second is from a Razor page handler method:

//API ActionMethod [HttpPost]
public ActionResult Create([FromForm] Car entity)
{
//body omitted for brevity
}

//Razor page
public async Task OnPostAsync(int? id, [FromForm]Car car)
{
//body omitted for brevity
}

Model Validation
Model validation occurs immediately after model binding (both explicit and implicit). While model binding adds errors to the ModelState data dictionary due to conversion issues, validation failures add errors to the ModelState data dictionary due to broken validation rules. Examples of validation rules include required fields, strings that have a maximum allowed length, properly formatted phone numbers, or dates being within a certain allowed range.
Validation rules are set through validation attributes, either built-in or custom. Table 30-8 lists some of the built-in validation attributes. Note that several also double as data annotations for shaping the EF Core entities.

Table 30-8. Some of the Built-in Validation Attributes

Attribute Meaning in Life
CreditCard Performs a Luhn-10 check on the credit card number
Compare Validates the two properties in a model match
EmailAddress Validates the property has a valid email format
Phone Validates the property has a valid phone number format
Range Validates the property falls within a specified range
RegularExpression Validates the property matches a specified regular expression
Required Validates the property has a value
StringLength Validates the property doesn’t exceed a maximum length
Url Validates the property has a valid URL format
Remote Validates input on the client by calling an action method on the server

Custom validation attributes can also be developed and are covered later in this book.

Explicit Model Validation
Explicit model validation is executed with a call to TryValidateModel(), passing in an instance of the type being validated. The result of this call is a populated ModelState instance with any invalid properties. Valid properties do not get written to the ModelState object like they do with the binding/validation combination.
Take the following code as an example. This method uses explicit binding, leaving out the Color property. Since the color property is required, the ModelState reports as invalid. The Color is updated, explicit validation is called, and the ModelState is still invalid:

[HttpPost] [ValidateAntiForgeryToken]
public async Task CreateCar()
{
var newCar = new Car();
if (await TryUpdateModelAsync(newCar, "",c => c.PetName, c => c.MakeId))
{
//car is bound and valid - save it
}

var isValid = ModelState.IsValid; //false newCar.Color = "Purple"; TryValidateModel(newCar);
isValid = ModelState.IsValid; //still false
//rest of the method
}
}

In order for an object that has been through a validation pass to be revalidated, the ModelState must be cleared, as in the following update to the method:

[HttpPost] [ValidateAntiForgeryToken]
public async Task CreateCar()
{
var newCar = new Car();
if (await TryUpdateModelAsync(newCar, "",c => c.PetName, c => c.MakeId))
{
//car is bound and valid - save it
}

var isValid = ModelState.IsValid; //false newCar.Color = "Purple"; TryValidateModel(newCar);
isValid = ModelState.IsValid; //still false ModelState.Clear(); TryValidateModel(newCar);
isValid = ModelState.IsValid; //true
//rest of the method
}
}

Do know that calling Clear() clears out all ModelState data, including the binding information.

Filters
Filters in ASP.NET Core run code before or after specific stages of the request processing pipeline. There are built-in filters for authorization and caching, as well as options for assigning customer filters. Table 30-9 lists the types of filters that can be added into the pipeline, listed in their order of execution.

Table 30-9. Filters Available in ASP.NET Core

Filter Meaning in Life
Authorization filters Run first and determine if the user is authorized for the current request.
Resource filters Run immediately after the authorization filter and can run after the rest of the pipeline has completed. Run before model binding.
Action filters Run immediately before an action is executed and/or immediately after an action is executed. Can alter values passed into an action and the result returned from an action. Applies to MVC style web applications and RESTful services.
Page Filters Can be built to run code after a handler method has been selected but before model binding, after the handler method executes after model binding is complete or immediately after the handler executed. Similar to Action filters but apply to Razor Pages.
Exception filters Used to apply global policies to unhandled exceptions that occur before writing to the response body.
Result filters Run code immediately after the successful execution of action results. Useful for logic that surrounds view or formatter execution.

Authorization Filters
Authorization filters work with the ASP.NET Core Identity system to prevent access to controllers or actions that the user doesn’t have permission to use. It’s not recommended to build custom authorization filters since the built-in AuthorizeAttribute and AllowAnonymousAttribute usually provide enough coverage when using ASP.NET Core Identity.

Resource Filters
Resource filters have two methods. The OnResourceExecuting() method executes after authorization filters and prior to any other filters, and the OnResourceExecuted() method executes after all other filters. This enables resource filters to short-circuit the entire response pipeline. A common use for resource filters is for caching. If the response is in the cache, the filter can skip the rest of the pipeline.

Action Filters
The OnActionExecuting() method executes immediately before the execution of the action method, and the OnActionExecuted() method executes immediately after the execution of the action method. Action filters can short-circuit the action method and any filters that are wrapped by the action filter (order of execution and wrapping are covered shortly).

Page Filters
The OnHandlerSelected() method executes after a handler method has been selected but before model binding occurs. The OnPageHandlerExecuting() method executes after model binding is complete and the OnPageHandlerExecuted() method executes after the handler method executes.

Exception Filters
Exception filters enable implementation of consistent error handling in an application. The OnException() method executes when unhandled exceptions are thrown in controller creation, model binding, action filters, or action methods, page filters, or page handler methods.

Result Filters
Result filters wrap the execution of the IActionResult for an action method. A common scenario is to add header information into the HTTP response message using a result filter. The OnResultExecuting() method executes before the response and OnResultExecuted() executes after the response has started.

Summary
This chapter introduced ASP.NET Core and is the first of a set of chapters covering ASP.NET Core. This chapter began with a brief look back at the history of ASP.NET and then looked at the features from classic ASP.NET MVC and ASP.NET Web API that also exist in ASP.NET Core.
The next section created the solution and the projects, updated the ports, and examined running and debugging ASP.NET Core web applications and services.
In the next chapter, you will dive into many of the new features added in ASP.NET Core.

CHAPTER 29

WPF Notifications, Validations, Commands, and MVVM

This chapter will conclude your investigation of the WPF programming model by covering the capabilities that support the Model-View-ViewModel (MVVM) pattern. The first section covers the Model-View- ViewModel pattern. Next, you learn about the WPF notification system and its implementation of the Observable pattern through observable models and observable collections. Having the data in the UI accurately portray the current state of the data automatically improves the user experience significantly and reduces the manual coding required in older technologies (such as WinForms) to achieve the same result.
Building on the Observable pattern, you will examine the mechanisms to add validation into your application. Validation is a vital part of any application—not only letting the user know that something is wrong but also letting them know what is wrong. To inform the user what the error is, you will also learn how to incorporate validation into the view markup.
Next, you will take a deeper dive into the WPF command system and create custom commands to encapsulate program logic, much as you did in Chapter 25 with the built-in commands. There are several advantages to creating custom commands, including (but not limited to) enabling code reuse, logic encapsulation, and separation of concerns.
Finally, you will bring all of this together in a sample MVVM application.

Introducing Model-View-ViewModel
Before you dive into notifications, validations, and commands in WPF, it would be good to understand the end goal of this chapter, which is the Model-View-ViewModel pattern (MVVM). Derived from Martin
Fowler’s Presentation Model pattern, MVVM leverages XAML-specific capabilities, discussed in this chapter, to make your WPF development faster and cleaner. The name itself describes the main components of the pattern: model, view, view model.

The Model
The model is the object representation of your data. In MVVM, models are conceptually the same as the models from your data access layer (DAL). Sometimes they are the same physical class, but there is no requirement for this. As you read this chapter, you will learn how to decide whether you can use your DAL models or whether you need to create new ones.
Models typically take advantage of the built-in (or custom) validations through data annotations and the INotifyDataErrorInfo interface and are configured as observable to tie into the WPF notification system. You will see all of this later in this chapter.

© Andrew Troelsen, Phil Japikse 2022
A. Troelsen and P. Japikse, Pro C# 10 with .NET 6, https://doi.org/10.1007/978-1-4842-7869-7_29

1273

The View
The view is the UI of the application, and it is designed to be very lightweight. Think of the menu board at a drive-thru restaurant. The board displays menu items and prices, and it has a mechanism so the user can communicate with the back-end systems. However, there isn’t any intelligence built into the board, unless it is specifically user interface logic, such as turning on the lights if it gets dark.
MVVM views should be developed with the same goals in mind. Any intelligence should be built into the application elsewhere. The only code in the code-behind file (e.g., MainWindow.xaml.cs) should be directly related to manipulating the UI. It should not be based on business rules or anything that needs to be persisted for future use. While not a main goal of MVVM, well-developed MVVM applications typically have very little code in the code-behind.

The View Model
In WPF and other XAML technologies, the view model serves two purposes.
•The view model provides a single stop for all the data needed by the view. This doesn’t mean the view model is responsible for getting the actual data; instead, it is merely a transport mechanism to move the data from the data store to the view. Usually, there is a one-to-one correlation between views and view models, but architectural differences exist, and your mileage may vary.
•The second job is to act as the controller for the view. Just like the menu board, the view model takes direction from the user and relays that call to the relevant code to make sure the proper actions are taken. Quite often this code is in the form of custom commands.

Anemic Models or Anemic View Models
In the early days of WPF, when developers were still working out how best to implement the MVVM pattern, there were significant (and sometimes heated) discussions about where to implement items like validation and the Observable pattern. One camp (the anemic model camp) argued that it all should be in the view model since adding those capabilities to the model broke separation of concerns. The other camp (the anemic view model camp) argued it should all be in the models since that reduced duplication of code.
The real answer is, of course, it depends. When INotifyPropertyChanged, IDataErrorInfo, and INotifyDataErrorInfo are implemented on the model classes, this ensures that the relevant code is close to the target of the code (as you will see in this chapter) and is implemented only once for each model.
That being said, there are times when your view model classes will need to be developed as observables themselves. At the end of the day, you need to determine what makes the most sense for your application, without over-complicating your code or sacrificing the benefits of MVVM.

■Note There are multiple MVVM frameworks available for WPF, such as MVVMLite, Caliburn.Micro, and Prism (although Prism is much more than just an MVVM framework). This chapter discusses the MVVM pattern and the features in WPF that support implementing the pattern. I leave it to you, the reader, to examine the different frameworks and select the one that best matches your app’s needs.

The WPF Binding Notification System
A significant shortcoming in the binding system for WinForms is a lack of notifications. If the data represented in the view is updated programmatically, the UI must also be refreshed programmatically to keep them in sync. This leads to a lot of calls to Refresh() on controls, typically more than are absolutely necessary in order to be safe. While usually not a significant performance issue to include too many calls to Refresh(), if you don’t include enough, the experience for the user could be affected negatively.
The binding system built into XAML-based applications corrects this problem by enabling you to hook your data objects and collections into a notification system by developing them as observables. Whenever a property’s value changes on an observable model or the collection changes (e.g., items are added, removed, or reordered) on an observable collection, an event is raised (either NotifyPropertyChanged
or NotifyCollectionChanged). The binding framework automatically listens for those events to occur
and updates the bound controls when they fire. Even better, as a developer, you have control over which properties raise the notifications. Sounds perfect, right? Well, it’s not quite perfect. There can be a fair amount of code involved in setting this up for observable models if you are doing it all by hand. Fortunately, there is an open source framework that makes it much simpler, as you shall soon see.

Observable Models and Collections
In this section, you will create an application that uses observable models and collections. To get started, create a new WPF application named WpfNotifications. The application will be a master-detail form, allowing the user to select a specific car using a ComboBox, and then the details for that car will be displayed in the following TextBox controls. Update MainWindow.xaml by replacing the default Grid with the following markup:

Your window will resemble Figure 29-1.

Figure 29-1. Master-detail window displaying Car details

The IsSharedSizeScope tag on the Grid control sets up child grids to share dimensions. The ColumnDefinitions marked SharedSizeGroup will automatically be sized to the same width without any programming needed. In this example, if the Pet Name label was changed to something much longer, the Vehicle column (which is in a different Grid control) would be sized to match it, keeping the window’s appearance nice and tidy.
Next, right-click the project name in Solution Explorer, select Add ➤ New Folder, and name the folder
Models. In this new folder, create a class named Car. The initial class is listed here:

public class Car
{
public int Id { get; set; } public string Make { get; set; } public string Color { get; set; }
public string PetName { get; set; }
}

Adding Bindings and Data
The next step is to add the binding statements for the controls. Remember that data-binding statements revolve around a data context, and this can be set on the control itself or on a parent control. Here, you are going to set the context on the DetailsGrid, so each control contained will inherit that data context. Set the DataContext to the SelectedItem property of the ComboBox. Update the Grid that holds the detail controls to the following:

<Grid Grid.Row="1" Name="DetailsGrid"
DataContext="{Binding ElementName=cboCars, Path=SelectedItem}">

The text boxes in the DetailsGrid will show the individual properties of the select car. Add the appropriate text attributes and related bindings to the TextBox controls, like so:

Finally, add data to the ComboBox. In MainWindow.xaml.cs, create a new list of Car records, and set the ItemsSource for the ComboBox to the list. Also, add the using statement for the Notifications.Models namespace.

using WpfNotifications.Models;
//omitted for brevity
public partial class MainWindow : Window
{
readonly IList _cars = new List(); public MainWindow()
{
InitializeComponent();
_cars.Add(new Car {Id = 1, Color = "Blue", Make = "Chevy", PetName = "Kit"});
_cars.Add(new Car {Id = 2, Color = "Red", Make = "Ford", PetName = "Red Rider"}); cboCars.ItemsSource = _cars;
}
}

Run the app. You’ll see that the vehicle selector has two cars to choose from. Choose one of them, and the text boxes will be automatically populated with the vehicle detail. Change the color of one of the vehicles, select the other vehicle, and then go back to the vehicle you edited. You will see the new color is indeed still attached to the vehicle. This isn’t anything remarkable; you’ve seen the power of XAML data binding in previous examples.

Programmatically Changing the Vehicle Data
While the previous example works as expected, if the data is changed programmatically, the UI will not reflect the changes unless you program the app to refresh the data. To demonstrate this, add an event handler for the btnChangeColor Button, like so:

In the BtnChangeColor_Click() event handler, use the SelectedItem property of the ComboBox to locate the selected record from the cars list, and change the color to Pink. The code is listed here:

private void BtnChangeColor_OnClick(object sender, RoutedEventArgs e)
{
_cars.First(x => x.Id == ((Car)cboCars.SelectedItem)?.Id).Color = "Pink";
}

Run the app, select a vehicle, and click the Change Color button. Nothing changes visibly. Select the other vehicle and go back to your originally selected vehicle. Now you will see the updated value. This is not a good experience for the user!
Now add an event handler to the btnAddCar button, like this:

In the BtnAddCar_Click event handler, add a new record to the Car list.

private void BtnAddCar_Click(object sender, RoutedEventArgs e)
{
var maxCount = _cars?.Max(x => x.Id) ?? 0;
_cars?.Add(new Car { Id=++maxCount,Color="Yellow",Make="VW",PetName="Birdie"});
}

Run the app, click the Add Car button, and examine the contents of the ComboBox. Even though you know there are three cars in the list, only two are displayed! To correct both of these problems, you will convert the Car class to an observable model and use an observable collection to hold all the Car instances.

Observable Models
The problem of data changing on a property of your model and not being displayed in the UI is resolved by implementing the INotifyPropertyChanged interface on your Car model class. The INotifyPropertyChanged interface contains a single event: PropertyChangedEvent. The XAML binding engine listens for this event for each bound property on classes that implement the INotifyPropertyChanged interface. The interface is shown here:

public interface INotifyPropertyChanged
{
event PropertyChangedEventHandler PropertyChanged;
}

Add the following using statements to the Car.cs class:

using System.ComponentModel;
using System.Runtime.CompilerServices;

Next, implement the INotifyPropertyChanged interface on the class, as follows:

public class Car : INotifyPropertyChanged
{
//Omitted for brevity
public event PropertyChangedEventHandler PropertyChanged;
}

The PropertyChanged event takes an object reference and a new instance of the
PropertyChangedEventArgs class, like in this example:

PropertyChanged?.Invoke(this,
new PropertyChangedEventArgs("Model"));

The first parameter is the object instance that is raising the event. The PropertyChangedEventArgs constructor takes a string that indicates the property that was changed and needs to be updated. When the event is raised, the binding engine looks for any controls bound to the named property on that instance. If you pass String.Empty into the PropertyChangedEventArgs, all of the bound properties of the instance are updated.
You control which properties are enlisted in the automatic updates. Only those properties that raise the PropertyChanged event in the setter will be automatically updated. This is usually all the properties on your model classes, but you have the option of omitting certain properties based on your application’s requirements. Instead of raising the event directly in the setter for each of the enlisted properties, a common pattern is to create a helper method (typically named OnPropertyChanged()) that raises the event on behalf of the properties, usually in a base class for your models. Add the following method and code into the Car.cs class:

protected void OnPropertyChanged([CallerMemberName] string propertyName = "")
{
PropertyChanged?.Invoke(this,
new PropertyChangedEventArgs(propertyName));
}

Next, update each of the automatic properties in the Car class to have a full getter and setter with a backing field. When the value is changed, call the OnPropertyChanged() helper method. Here is the Id property updated:

private int _id; public int Id
{
get => _id; set
{
if (value == _id) return;
_id = value;
OnPropertyChanged();
}
}

Make sure you do the same for all the properties in the class and then run the app again. Select a vehicle and click the Change Color button. You will immediately see the change show up in the UI. First problem solved!

Using nameof
A feature added in C# 6 is the nameof operator, which provides the string name of the item passed into the
nameof method. You can use this in the calls to OnPropertyChanged() in your setters, like this:

public string Color
{
get { return _color; } set
{
if (value == _color) return;
_color = value; OnPropertyChanged(nameof(Color));
}
}

Note that you don’t have to remove the CallerMemberName attribute from OnPropertyChanged() when you use the nameof method (although it becomes unnecessary). In the end, whether you use the nameof method or the CallerMemberName attribute comes down to a matter of personal choice.

Observable Collections
The next problem to resolve is updating the UI when the contents of a collection changes. This is done by implementing the INotifyCollectionChanged interface. Like the INotifyPropertyChanged interface, this interface exposes one event, the CollectionChanged event. Unlike the INotifyPropertyChanged event, implementing this interface by hand is more than just calling a method in the setter. You need to create a full List implementation and raise the CollectionChanged event any time your list changes.

Using the ObservableCollections Class
Fortunately, there is a much easier way than creating your own collection class. The ObservableCollection class implements INotifyCollectionChanged, INotifyPropertyChanged, and Collection, and it is part of the .NET Core Framework. No extra work! To see this, add a using statement for System.Collections.ObjectModel and then update the private field for _cars to the following:

private readonly IList _cars = new ObservableCollection();

Run the app again and click the Add Car button. You will see the new records appear appropriately.

Implementing a Dirty Flag
Another advantage of observable models is the ability to track state changes. Dirty tracking (tracking when one or more of an object’s values have changed) with WPF is fairly trivial. Add a bool property named IsChanged to the Car class. Make sure to call OnPropertyChanged() just like the other properties in the Car class.

private bool _isChanged; public bool IsChanged {
get => _isChanged; set
{
if (value == _isChanged) return;
_isChanged = value;
OnPropertyChanged();
}
}

You need to set the IsChanged property to true in the OnPropertyChanged() method. You also need to make sure you aren’t setting IsChanged to true when IsChanged is updated, or you will hit a stack overflow exception! Update the OnPropertyChanged() method to the following (which uses the nameof method discussed earlier):

protected virtual void OnPropertyChanged( [CallerMemberName] string propertyName = "")
{
if (propertyName != nameof(IsChanged))
{
IsChanged = true;
}
PropertyChanged?.Invoke(this,
new PropertyChangedEventArgs(propertyName));
}

Open MainWindow.xaml and add an additional RowDefinition to the DetailsGrid. Add the following to the end of the Grid, which contains a Label and a CheckBox, bound to the IsChanged property, as follows:

If you were to run the app now, you would see that every single record shows up as changed, even though you haven’t changed anything! This is because object creation sets property values, and setting any values calls OnPropertyChanged(). This sets the object’s IsChanged property. To correct this, set the
IsChanged property to false as the last property in the object initialization code. Open MainWindow.xaml.cs
and change the code that creates the list to the following:

_cars.Add(
new Car {Id = 1, Color = "Blue", Make = "Chevy", PetName = "Kit", IsChanged = false});
_cars.Add(
new Car {Id = 2, Color = "Red", Make = "Ford", PetName = "Red Rider", IsChanged = false});

Run the app again, select a vehicle, and click the Change Color button. You will see the check box get selected along with the updated color.

Updating the Source Through UI Interaction
You might notice that if you type text into the UI, the Is Changed check box doesn’t actually get selected until you tab out of the control being edited. This is because of the UpdateSourceTrigger property on the TextBox bindings. The UpdateSourceTrigger determines what event (such as changing the value, tabbing out, etc.) causes the UI to update the underlying data. There are four options, as shown in Table 29-1.

Table 29-1. UpdateSourceTrigger Values

Member Meaning in Life
Default Sets to the default for the control (e.g., LostFocus for TextBox controls).
Explicit Updates the source object only when the UpdateSource method is called.
LostFocus Updates when the control loses focus. This is the default for TextBox controls.
PropertyChanged Updates as soon as the property changes. This is the default for CheckBox controls.

The default source trigger for a TextBox is the LostFocus event. Change this to PropertyChanged by updating the binding for the Color TextBox to the following XAML:

Now, when you run the app and start typing into the Color text box, the check box is immediately selected. You might ask why the default is set to LostFocus for TextBox controls. Any validation (covered in a moment) for a model fires in conjunction with the UpdateSourceTrigger. For a TextBox, this would then potentially cause errors continually flashing until the user entered the correct values. For example, if the validation rules don’t allow less than five characters in a TextBox, the error would show on each keystroke until the user got five or more entered. In those cases, it’s best to wait for the user to tab out of the TextBox (after completing the change to the text) to update the source.

Wrapping Up Notifications and Observables
Using INotifyPropertyChanged on your models and ObservableCollections classes for your lists improves the user experience by keeping the data and the UI in sync. While neither interface is complicated, they
do require updates to your code. Fortunately, Microsoft has included the ObservableCollection class to handle all of the plumbing to create observable collections. Just as fortunate is the update to the Fody project to add INotifyPropertyChanged functionality automatically. With these two tools in hand, there isn’t any reason to not implement observables in your WPF applications.

WPF Validations
Now that you’ve implemented INotifyPropertyChanged and are using an ObservableCollection, it’s time to add validations to your application. Applications need to validate user input and provide feedback to the user when the data entered is incorrect. This section covers the most common validation mechanisms for modern WPF applications, but these are still just a portion of the capabilities built into WPF.

Validation occurs when a data binding attempts to update the data source. In addition to built-in validations, such as exceptions in a property’s setter, you can create custom validation rules. If any validation rule (built-in or custom) fails, the Validation class, discussed shortly, comes into play.

■Note For each of the sections in this chapter, you can continue working in the same project from the previous section, or you can create a copy of the project for each new section. In the repo for this chapter, each section is a different project.

Updating the Sample for the Validation Examples
In the repo for this chapter, the new project (copied from the previous example) is called WpfValidations. If you are using the same project from the previous section, you just need to make note of the namespace changes when copying code into your project from the examples listed in this section.

The Validation Class
Before adding validations to your project, it’s important to understand the Validation class. This class is part of the validation framework, and it provides methods and attached properties that can be used to
display validation results. There are three main properties of the Validation class commonly used when handling validation errors (shown in Table 29-2). You will use each of these through the rest of this section.

Table 29-2. Key Members of the Validation Class

Member Meaning in Life
HasError Attached property indicating that a validation rule failed somewhere in the process
Errors Collection of all active ValidationError objects
ErrorTemplate Control template that becomes visible and adorns the bound element when HasError is set to true

Validation Options
As mentioned, XAML technologies have several mechanisms for incorporating validation logic into your application. You will examine three of the most commonly used validation choices in the next sections.

Notify on Exceptions
While exceptions should not be used to enforce business logic, exceptions can and do happen, and they should be handled appropriately. In case they aren’t handled in code, the user should receive visual feedback of the problem. An important change from WinForms is that WPF binding exceptions are not, by default, propagated to the user as exceptions. They are, however, visually indicated, using an adorner (visual layer that resides on top of your controls).

To test this, run the app, select a record from the ComboBox, and clear out the Id value. Since the Id property is defined as an int (not a nullable int), a numeric value is required. When you tab out of the Id field, an empty string is sent to the Id property by the binding framework, and since an empty string can’t be converted to an int, an exception is thrown in the setter. Normally, an unhandled exception would generate a message box to the user, but in this case, nothing like that happened. If you look in the Debug portion of the Output window, you will see the following:

System.Windows.Data Error: 7 : ConvertBack cannot convert value '' (type 'String'). BindingExpression:Path=Id; DataItem='Car' (HashCode=52579650); target element is 'TextBox' (Name=''); target property is 'Text' (type 'String') FormatException:'System. FormatException: Input string was not in a correct format.

Visual display of the exception is a thin red box around the control, as shown in Figure 29-2.

Figure 29-2. The default error template

The red box is the ErrorTemplate property of the Validation object and acts as an adorner for the bound control. While the default error adorner shows that there is indeed an error, there isn’t any indication as to what is wrong. The good news is that the ErrorTemplate is completely customizable, as you will see later in this chapter.

IDataErrorInfo
The IDataErrorInfo interface provides a mechanism for you to add custom validations to your model classes. This interface is added directly to your model (or view model) classes, and the validation code is placed inside your model classes (preferably in partial classes). This centralizes validation code in your project, in direct contrast to WinForms projects, where validation was typically done in the UI itself.

The IDataErrorInfo interface, shown here, contains two properties: an indexer and a string property named Error. Note that the WPF binding engine doesn’t use the Error property.

public interface IDataErrorInfo
{
string this[string columnName] { get; } string Error { get; }
}

You will be adding the Car partial class shortly, but first you need to update the Car.cs class and mark it as partial. Next, add another file to the Models directory named CarPartial.cs. Rename this class Car, make sure the class is marked as partial, and add the IDataErrorInfo interface. Finally, implement the API for the interface. The initial code is listed here:

public partial class Car : IDataErrorInfo
{
public string this[string columnName] => string.Empty; public string Error { get;}
}

For a bound control to opt in to the IDataErrorInfo interface, it must add ValidatesOnDataErrors to the binding expression. Update the binding expression for the Make text box to the following (and update the rest of the binding statements in the same way):

Once this update is made to the binding statements, the indexer on the model gets called each time the
PropertyChanged event is raised. The property name from the event is used as the columnName parameter in the indexer. If the indexer returns string.Empty, the framework assumes that all validations passed, and no error condition exists. If the indexer returns anything but string.Empty, an error is presumed to exist on the property for that object instance, and each control that is bound to the property being validated on this specific instance of the class is considered to have an error, the HasError property of the Validation object is set to true, and the ErrorTemplate adorner is activated for the controls effected.
Next, you will add some simple validation logic to the indexer in CarPartial.cs. The validation rules are simple.
•If Make equals ModelT, set the error equal to "Too Old".
•If Make equals Chevy and Color equals Pink, set the error equal to $"{Make}'s don't come in {Color}".
Start by adding a switch statement for each of the properties. To avoid using magic strings in the case statements, you will again use the nameof method. If the code falls through the switch statement, return string.Empty. Next, add the validation rules. In the proper case statements, add a check of the property value based on the rules listed earlier. In the case statement for the Make property, first check to make sure the value isn’t ModelT. If it is, return the error. If that passes, the next line will call into a helper method that returns an error if the second rule is violated, or it will return string.Empty if it is not. In the case statement for the Color property, also call the helper method. The code is as follows:

public string this[string columnName]
{
get
{
switch (columnName)
{
case nameof(Id):
break;
case nameof(Make):
return Make == "ModelT"
? “Too Old”
: CheckMakeAndColor(); case nameof(Color):
return CheckMakeAndColor(); case nameof(PetName):
break;
}
return string.Empty;
}
}

internal string CheckMakeAndColor()
{
if (Make == "Chevy" && Color == "Pink")
{
return $"{Make}'s don't come in {Color}";
}
return string.Empty;
}

Run the app, select the Red Rider vehicle (the Ford), and change the Make to ModelT. Once you tab out of the field, the red error decorator appears. Now select Kit (which is a Chevy) from the drop-down and
click the Change Color button to change the color to Pink. Immediately the red error adorner appears on the Color field but doesn’t appear on the Make text box. Now, change Make to Ford, tab out of the text box, and note that the red adorner does not disappear!
This is because the indexer runs only when the PropertyChanged event is fired for a property. As discussed in earlier, the PropertyChanged event fires when the source object’s property changes, and this happens either through code (such as clicking the Change Color button) or through user interaction (the timing of this is controlled through the UpdateSourceTrigger). When you changed the color, the Make property did not change, so the event did not fire for the Make property. Since the event didn’t fire, the indexer did not get called, so the validation for the Make property didn’t run.
There are two ways to fix this. The first is to change PropertyChangedEventArgs to update every bound property by passing in string.Empty instead of a field name. As discussed, this causes the binding engine to update every property on that instance. Update the OnPropertyChanged() method in the Car.cs class like this:

protected virtual void OnPropertyChanged([CallerMemberName] string propertyName = "")
{
if (propertyName != nameof(IsChanged))
{
IsChanged = true;
}

//PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName)); PropertyChanged?.Invoke(this,
new PropertyChangedEventArgs(string.Empty));
}

Now, when you run the same test, you see that both the Make and Color text boxes are adorned with the error template when one of them is updated. So, why not always raise the event in this manner? It’s largely a matter of performance. It’s possible that refreshing every property on an object could hamper performance. Of course, there’s no way to know without testing, and your mileage may (and probably will) vary.
The other solution is to raise the PropertyChanged event for the other dependent field(s) when one changes. The downside to using this mechanism is that you (or other developers who support your app) must know that the Make and Color properties are related through the validation code.

INotifyDataErrorInfo
The INotifyDataErrorInfo interface introduced in .NET 4.5 builds on the IDataErrorInfo interface and adds additional capabilities for validation. Of course, with additional power comes additional work! In a drastic shift from prior validation techniques that you had to specifically opt into, the ValidatesOnNotifyDataErrors binding property defaults to true, so adding the property to your binding statements is optional.
The INotifyDataErrorInfo interface is extremely small but does take a fair amount of plumbing code to make it effective, as you will see shortly. The interface is shown here:

public interface INotifyDataErrorInfo
{
bool HasErrors { get; }
event EventHandler ErrorsChanged;
IEnumerable GetErrors(string propertyName);
}

The HasErrors property is used by the binding engine to determine whether there are any errors on any of the instance’s properties. If the GetErrors() method is called with a null or empty string for the propertyName parameter, it returns all errors that exist in the instance. If a propertyName is passed into the method, only
the errors for that particular property are returned. The ErrorsChanged event (like the PropertyChanged and
CollectionChanged events) notifies the binding engine to update the UI for the current list of errors.

Implement the Supporting Code
When implementing INotifyDataErrorInfo, most of the code is usually pushed into a base model class, so it needs be written only once. Start by replacing IDataErrorInfo with INotifyDataErrorInfo in the CarPartial.cs class and add the interface members (you can leave the code from IDataErrorInfo in the class; you will be updating this later).

public partial class Car: INotifyDataErrorInfo, IDataErrorInfo
{
...
public IEnumerable GetErrors(string propertyName)
{
throw new NotImplementedException();
}

public bool HasErrors { get; } public event
EventHandler ErrorsChanged;
}

Next, add a Dictionary<string,List> that will hold any errors grouped by property name, as shown here:

private readonly Dictionary<string,List> _errors
= new Dictionary<string, List>();

The HasErrors property should return true if there are any errors in the dictionary. This is easily accomplished like this:

public bool HasErrors => _errors.Any();

Next, create a helper method to raise the ErrorsChanged event (just like raising the PropertyChanged
event) like this:

private void OnErrorsChanged(string propertyName)
{
ErrorsChanged?.Invoke(this,
new DataErrorsChangedEventArgs(propertyName));
}

As mentioned earlier, the GetErrors() method should return any and all errors in the dictionary if the parameter is empty or null. If a propertyName value is passed in, it will return any errors found for that property. If the parameter doesn’t match (or there aren’t any errors for a property), then the method will return null.

public IEnumerable GetErrors(string propertyName)
{
if (string.IsNullOrEmpty(propertyName))
{
return _errors.Values;
}
return _errors.ContainsKey(propertyName)
? _errors[propertyName]
: null;
}

The final set of helpers will add one or more errors for a property or clear all of the errors for a property (or all properties). Any time the dictionary changes, remember to call the OnErrorsChanged() helper method.

private void AddError(string propertyName, string error)
{
AddErrors(propertyName, new List { error });
}
private void AddErrors(
string propertyName, IList errors)

{
if (errors == null || !errors.Any())
{
return;
}
var changed = false;
if (!_errors.ContainsKey(propertyName))
{
_errors.Add(propertyName, new List()); changed = true;
}
foreach (var err in errors)
{
if (_errors[propertyName].Contains(err)) continue;
_errors[propertyName].Add(err); changed = true;
}
if (changed)
{
OnErrorsChanged(propertyName);
}
}
protected void ClearErrors(string propertyName = "")
{
if (string.IsNullOrEmpty(propertyName))
{
_errors.Clear();
}
else
{
_errors.Remove(propertyName);
}
OnErrorsChanged(propertyName);
}

Now the question is “how is this code activated?” The binding engine listens for the ErrorsChanged
event and will update the UI if there is a change in the errors collection for a binding statement. But the validation code still needs a trigger to execute. There are two mechanisms for this, and they will be discussed next.

Use INotifyDataErrorInfo for Validations
One place to check for errors is in the property setters, like the following example, simplified to just check for the ModelT validation:

public string Make
{
get { return _make; } set
{
if (value == _make) return;

_make = value;
if (Make == "ModelT")
{
AddError(nameof(Make), "Too Old");
}
else
{
ClearErrors(nameof(Make));
}
OnPropertyChanged(nameof(Make)); OnPropertyChanged(nameof(Color));
}
}

The main issue with this approach is you have to combine validation logic with property setters, making the code harder to read and support.

Combine IDataErrorInfo with INotifyDataErrorInfo for Validations
You saw in the previous section that IDataErrorInfo can be added to a partial class, which means you don’t have to update your setters. You also saw that the indexer automatically gets called when PropertyChanged is raised on a property. Combining IDataErrorInfo and INotifyDataErrorInfo provides you with the additional features for validations from INotifyDataErrorInfo and with the separation from the setters provided by IDataErrorInfo.
The purpose of using IDataErrorInfo is not to run validations but to make sure your validation code that leverages INotifyDataErrorInfo gets called every time PropertyChanged is raised on your object. Since you aren’t using IDataErrorInfo for validation, always return string.Empty from the indexer. Update the indexer and the CheckMakeAndColor() helper method to the following code:

public string this[string columnName]
{
get
{
ClearErrors(columnName); switch (columnName)
{
case nameof(Id): break;
case nameof(Make): CheckMakeAndColor(); if (Make == "ModelT")
{
AddError(nameof(Make), "Too Old"); hasError = true;
}
break;
case nameof(Color): CheckMakeAndColor(); break;
case nameof(PetName):

break;
}
return string.Empty;
}
}
internal bool CheckMakeAndColor()
{
if (Make == "Chevy" && Color == "Pink")
{
AddError(nameof(Make), $"{Make}'s don't come in {Color}"); AddError(nameof(Color),
$"{Make}'s don't come in {Color}"); return true;
}
return false;
}

Run the app, select Chevy, and change the color to Pink. In addition to the red adorners around the Make and Model text boxes, you will also see a red box adorner around the entire grid that holds the Car details fields (shown in Figure 29-3).

Figure 29-3. The updated error adorner

This is another advantage of using INotifyDataErrorInfo. In addition to the controls in error, the control defining the data context also gets adorned with the error template.

Show All Errors
The Errors property on the Validation class returns all the validation errors on a particular object in the form of ValidationError objects. Each ValidationError object has an ErrorContent property that contains the list of error messages for the property. This means the error messages you want to display are in this list within a list. To display them properly, you need to create a ListBox that holds a ListBox to display the data. It sounds a bit recursive, but it will make sense once you see it.
Start by adding another row to the DetailsGrid and make sure the Height of the Window is at least 300. Add a ListBox in the last row, and bind the ItemsSource to the DetailsGrid, using Validation.Errors for the path, as follows:

Add a DataTemplate to the ListBox, and in the DataTemplate, add a ListBox that is bound to the ErrorContent property. The data context for each ListBoxItem in this case is a ValidationError object, so you don’t need to set the data context, just the path. Set the binding path to ErrorContent, like this:

Run the app, select Chevy, and set the color to Pink. You will see the errors displayed in Figure 29-4.

Figure 29-4. Showing the errors collection

This just scratches the surface of what you can do with validations and with displaying the errors generated, but it should have you well on your way to developing informative UIs that improve the user experience.

Move the Support Code to a Base Class
As you probably noticed, there is a lot of code now in the CarPartial.cs class. Since this example has only one model class, this isn’t terrible. But, as you add models to a real application, you don’t want to have to add all of that plumbing into each partial class for your models. The best thing to do is to push all of that supporting code down to a base class. You will do that now.
Add a new class file to the Models folder named BaseEntity.cs. Add using statements for System. Collections and System.ComponentModel. Make the class public, and add the INotifyDataErrorInfo interface, like this:

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

namespace Validations.Models
{
public class BaseEntity : INotifyDataErrorInfo
}

Move all of the code from CarPartial.cs that relates to INofityDataErrorInfo into the new base class.
Any private methods and variables need to be made protected. Next, remove the INotifyDataErrorInfo
interface from the CarPartial.cs class, and add BaseEntity as a base class, as follows:

public partial class Car : BaseEntity, IDataErrorInfo
{
//removed for brevity
}

Now, any additional model classes you create will inherit all of the INotifyDataErrorInfo plumbing code.

Leverage Data Annotations with WPF
WPF can leverage data annotations as well for UI validation. Let’s add some data annotations to the Car model.

Add Data Annotations to the Model
Open Car.cs and add a using statement for System.ComponentModel.DataAnnotations. Add the [Required] and [StringLength(50)] attributes to Make, Color, and PetName. The Required attribute adds a validation rule that the property must not be null (admittedly, this is redundant for the Id property since it
is not a nullable int). The StringLength(50) attribute adds a validation rule that the value of the property cannot be longer than 50 characters.

Check for Data Annotation–Based Validation Errors
In WPF you have to programmatically check for data annotation–based validation errors. Two key classes for annotation-based validations are the ValidationContext and Validator classes. The ValidationContext class provides a context for checking a class for validation errors. The Validator class allows you to check an object for attribute-based errors within a ValidationContext.
Open BaseEntity.cs, and add the following using statements:

using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

Next, create a new method named GetErrorsFromAnnotations(). This method is generic, takes a string property name and a value of type T as the parameters, and returns a string array. Make sure the method is marked as protected. The signature is listed here:

protected string[] GetErrorsFromAnnotations( string propertyName, T value)
{}

In the method, create a List variable that will hold the results of validation checks and create a ValidationContext scoped to the property name passed into the method. When you have those two items in place, call Validate.TryValidateProperty, which returns a bool. If everything passes (in regard to data annotation validations), it returns true. If not, it returns false and populates the List with the errors. The complete code is shown here:

protected string[] GetErrorsFromAnnotations(

string propertyName, T value)
{
var results = new List();
var vc = new ValidationContext(this, null, null)
{ MemberName = propertyName };
var isValid = Validator.TryValidateProperty( value, vc, results);
return (isValid)
? null
: Array.ConvertAll(
results.ToArray(), o => o.ErrorMessage);
}

Now you can update the indexer method in CarPartial.cs to check for any errors based on data annotations. If any errors are found, add them to the errors collection supporting INotifyDataErrorInfo. This enables us to clean up the error handling. In the start of the indexer method, clear the errors for the column.
Then process the validations and finally the custom logic for the entity. The updated indexer code is shown here:

public string this[string columnName]
{
get
{
ClearErrors(columnName); var errorsFromAnnotations =
GetErrorsFromAnnotations(columnName, typeof(Car)
.GetProperty(columnName)?.GetValue(this,null)); if (errorsFromAnnotations != null)
{
AddErrors(columnName, errorsFromAnnotations);
}
switch (columnName)
{
case nameof(Id): break;
case nameof(Make): CheckMakeAndColor(); if (Make == "ModelT")
{
AddError(nameof(Make), "Too Old");
}
break;
case nameof(Color): CheckMakeAndColor(); break;
case nameof(PetName): break;
}
return string.Empty;
}
}

Run the app, select one of the vehicles, and add text for the color that is longer than 50 characters. When you cross the 50-character threshold, the StringLength data annotation creates a validation error, and it is reported to the user, as shown in Figure 29-5.

Figure 29-5. Validating the required data annotation

Customizing the ErrorTemplate
The final topic is to create a style that will be applied when a control is in error and also update the ErrorTemplate to display more meaningful error information. As you learned in Chapter 27, controls are customizable through styles and control templates.
Start by adding a new style in the Windows.Resources section of MainWindow.xaml with a target type of TextBox. Next, add a trigger on the style that sets properties when the Validation.HasError property is set to true. The properties and the values to set are Background (Pink), Foreground (Black), and Tooltip to the ErrorContent. The Background and Foreground setters are nothing new, but the syntax for setting the ToolTip needs some explanation. The binding points back to the control that this style is applied to, in this case, the TextBox. The path is the first ErrorContent value of the Validation.Errors collection. The markup is as follows:

Run the app and create an error condition. The result will be similar to Figure 29-6, complete with a tooltip showing the error message.

Figure 29-6. Showing a custom ErrorTemplate

The previous style changed the appearance of any TextBox that has an error condition. Next, you will create a custom control template to update the ErrorTemplate of the Validation class to show a red exclamation mark and set the tooltips for the exclamation mark. The ErrorTemplate is an adorner, which
sits on top of the control. While the style just created updates the control itself, the ErrorTemplate will sit on top of the control.
Place a setter immediately after the Style.Triggers closing tag within the style you just created. You will be creating a control template that consists of a TextBlock (to show the exclamation mark) and a BorderBrush to surround the TextBox that contains the error(s). There is a special tag in XAML for the control that is being adorned with the ErrorTemplate named AdornedElementPlaceholder. By adding a
name to this control, you can access the errors that are associated with the control. In this example, you want to access the Validation.Errors property so you can get the ErrorContent (just like you did in the Style. Trigger). Here is the full markup for the setter:

Run the app and create an error condition. The result will be similar to Figure 29-7.

Figure 29-7. Showing a custom ErrorTemplate

Wrapping Up Validations
This completes your look at validation methods within WPF. Of course, there is much more that you can do. For more information, consult the WPF documentation.

Creating Custom Commands
As with the validations sections, you can continue working in the same project or create a new one and copy all of the code to it. I will create a new project named WpfCommands. If you are using the same project, be sure to pay attention to the namespaces in the code samples in this section and adjust them as needed.
As you learned in Chapter 25, commands are an integral part of WPF. Commands can be hooked up to WPF controls (such as Button and MenuItem controls) to handle user events, such as the Click() event. Instead of creating an event handler directly and adding the code directly into the code-behind file, the Execute() method of the command is executed when the click event fires. The CanExecute() method is
used to enable or disable the control based on custom code. In addition to the built-in commands you used in Chapter 25, you can create your own custom commands by implementing the ICommand interface. By using commands instead of event handlers, you gain the benefit of encapsulating application code, as well as automatically enabling and disabling controls based on business logic.

Implementing the ICommand Interface
As a quick review from Chapter 25, the ICommand interface is listed here:

public interface ICommand
{
event EventHandler CanExecuteChanged; bool CanExecute(object parameter); void Execute(object parameter);
}

Adding the ChangeColorCommand
The event handlers for your Button controls will be replaced with commands, starting with the Change Color button. Start by adding a new folder (named Cmds) in your project. Add a new class named ChangeColorCommand.cs. Make the class public, and implement the ICommand interface. Add the following using statements (the first one might vary depending on whether you created a new project for this sample):

using WpfCommands.Models; using System.Windows.Input;

Your class should look like this:

public class ChangeColorCommand : ICommand
{
public bool CanExecute(object parameter)
{
throw new NotImplementedException();
}
public void Execute(object parameter)
{
throw new NotImplementedException();
}
public event EventHandler CanExecuteChanged;
}

If the CanExecute() method returns true, any bound controls will be enabled, and if it returns false, they will be disabled. If a control is enabled (because CanExecute() returns true) and clicked, the Execute() method will fire. The parameter passed into both of these methods comes from the UI based on the CommandParameter property set on binding statements. The CanExecuteChanged event ties into the binding and notification system to inform the UI that the result of the CanExecute() method has changed (much like the PropertyChanged event).
In this example, the Change Color button should work only if the parameter is not null and of type Car.
Update the CanExecute() method to the following:

public bool CanExecute(object parameter)
=> (parameter as Car) != null;

The value for the Execute() method parameter is the same as for the CanExecute() method. Since the Execute() method can execute only if the object is of type Car, the argument must be cast to an Car type and have the color updated, as follows:

public void Execute(object parameter)
{
((Car)parameter).Color="Pink";
}

Attaching the Command to the CommandManager
The final update for the command class is to type the command into the command manager. The CanExecute() method fires when the Window first loads and then when the command manager instructs it to reexecute. Each command class has to opt in to the command manager. This is done by updating the code regarding the CanExecuteChanged event, as follows:

public event EventHandler CanExecuteChanged
{
add => CommandManager.RequerySuggested += value; remove => CommandManager.RequerySuggested -= value;
}

Updating MainWindow.xaml.cs
The next change is to create an instance of this class that the Button can access. For now, you will place this in the code-behind file for the MainWindow (later in this chapter, you will move this into a view model). Open MainWindow.xaml.cs and delete the Click event handler for the Change Color button. Add the following using statements to the top of the file (again, the namespace may vary based on whether you are still using the same project or you started a new one):

using WpfCommands.Cmds; using System.Windows.Input;

Next, add a public property named ChangeColorCmd of type ICommand with a backing field. In the expression body for the property, return the backing property (make sure to instantiate a new instance of the ChangeColorCommand if the backing field is null).

private ICommand _changeColorCommand = null; public ICommand ChangeColorCmd
=> _changeColorCommand ??= new ChangeColorCommand());

Updating MainWindow.xaml
As you saw in Chapter 25, clickable controls in WPF (like Button controls) have a Command property that allows you to assign a command object to the control. Start by connecting your command instantiated in the code-behind to the btnChangeColor button. Since the property for the command is on the MainWindow class, you use the RelativeSourceMode binding syntax to get to the Window that contains the Button, as follows:

Command="{Binding Path=ChangeColorCmd,
RelativeSource={RelativeSource Mode=FindAncestor, AncestorType={x:Type Window}}}"

The Button still needs to send in a Car object as the parameter for the CanExecute() and Execute() methods. This is assigned through the CommandParameter property. You set this to the SelectedItem of the cboCars ComboBox, as follows:

CommandParameter="{Binding ElementName=cboCars, Path=SelectedItem}"

The complete markup for the button is shown here:

Testing the Application
Run the application. You will see that the Change Color command is not enabled, as shown in Figure 29-8, since there isn’t a vehicle selected.

Figure 29-8. A window with nothing selected

Now, select a vehicle; the button will become enabled, and clicking it will change the color, as expected!

Creating the CommandBase Class
If you continued with this pattern for AddCarCommand.cs, there would be code that would be repeated between the classes. This is a good sign that a base class can help. Create a new class in the Cmds folder named CommandBase.cs and add a using for the System.Windows.Input namespace. Set the class to public and implement the ICommand interface. Change the class and the Execute() and CanExecute() methods to abstract. Finally, add in the updated CanExecuteChanged event from the ChangeColorCommand class. The full implementation is listed here:

using System;
using System.Windows.Input;

namespace WpfCommands.Cmds
{
public abstract class CommandBase : ICommand
{
public abstract bool CanExecute(object parameter); public abstract void Execute(object parameter); public event EventHandler CanExecuteChanged
{
add => CommandManager.RequerySuggested += value; remove => CommandManager.RequerySuggested -= value;
}
}
}

Adding the AddCarCommand Class
Add a new class named AddCarCommand.cs to the Cmds folder. Make the class public and add CommandBase as the base class. Add the following using statements to the top of the file:

using System.Collections.ObjectModel; using System.Linq;
using WpfCommands.Models;

The parameter is expected to be an ObservableCollection, so check to make sure of this in the CanExecute() method. If it is, then the Execute() method should add an additional car, just like the Click event handler.

public class AddCarCommand :CommandBase
{
public override bool CanExecute(object parameter)
=> parameter is ObservableCollection; public override void Execute(object parameter)
{
if (parameter is not ObservableCollection cars)
{
return;
}
var maxCount = cars.Max(x => x.Id); cars.Add(new Car
{
Id = ++maxCount, Color = "Yellow", Make = "VW", PetName = "Birdie"
});
}
}

Updating MainWindow.xaml.cs
Add a public property named AddCarCmd of type ICommand with a backing field. In the expression body for the property, return the backing property (make sure to instantiate a new instance of the AddCarCommand if the backing field is null).

private ICommand _addCarCommand = null; public ICommand AddCarCmd
=> _addCarCommand ??= new AddCarCommand());

Updating MainWindow.xaml
Update the XAML to remove the Click attribute and add the Command and CommandParameter attributes. The AddCarCommand will receive the list of cars from the cboCars combo box. The entire button’s XAML is as follows:

With this in place, you can now add cars and update the color of cars using reusable code contained in stand-alone classes.

Updating ChangeColorCommand
The final step is to update the ChangeColorCommand to inherit from CommandBase. Change ICommand to CommandBase, add the override keyword to both methods, and delete the CanExecuteChanged code. It’s really that simple! The new code is listed here:

public class ChangeColorCommand : CommandBase
{
public override bool CanExecute(object parameter)
=> parameter is Car;
public override void Execute(object parameter)
{
((Car)parameter).Color = "Pink";
}
}

RelayCommands
Another implementation of the command pattern in WPF is the RelayCommand. Instead of creating a new class for each command, this pattern uses delegates to implement the ICommand interface. It is a lightweight implementation, in that each command doesn’t have its own class. RelayCommands are usually used when there isn’t any reuse needed for the implementation of the command.

Creating the Base RelayCommand
RelayCommands are typically implemented in two classes. The base RelayCommand class is used when there aren’t any parameters needed for the CanExecute() and Execute() methods, and RelayCommand is used when a parameter is required. You will start with the base RelayCommand class, which leverages the CommandBase class. Add a new class named RelayCommand.cs to the Cmds folder. Make the class public and add CommandBase as the base class. Add two class-level variables to hold the Execute() and CanExecute() delegates.

private readonly Action _execute; private readonly Func _canExecute;

Create three constructors. The first is the default constructor (needed by the RelayCommand-derived class), the second is a constructor that takes an Action parameter, and the third is a constructor that takes an Action parameter and a Func parameter, as follows:

public RelayCommand(){}
public RelayCommand(Action execute) : this(execute, null) { } public RelayCommand(Action execute, Func canExecute)
{
_execute = execute
?? throw new ArgumentNullException(nameof(execute));
_canExecute = canExecute;
}

Finally, implement the CanExecute() and Execute() overrides. CanExecute() returns true if the Func is null; or if it is not null, it executes and returns true. Execute() executes the Action parameter.

public override bool CanExecute(object parameter)
=> _canExecute == null || _canExecute();
public override void Execute(object parameter) { _execute(); }

Creating RelayCommand
Add a new class named RelayCommandT.cs to the Cmds folder. This class is almost a carbon copy of the base class, except that the delegates all take a parameter. Make the class public and generic, and add RelayCommand as the base class, as follows:

public class RelayCommand : RelayCommand

Add two class-level variables to hold the Execute() and CanExecute() delegates:

private readonly Action _execute; private readonly Func _canExecute;

Create two constructors. The first takes an Action parameter, and the second takes an Action
parameter and a Func parameter, as follows:

public RelayCommand(Action execute):this(execute, null) {} public RelayCommand(
Action execute, Func canExecute)
{
_execute = execute
?? throw new ArgumentNullException(nameof(execute));
_canExecute = canExecute;
}

Finally, implement the CanExecute() and Execute() overrides. CanExecute() returns true if the Func is null; or, if it is not null, it executes and returns true. Execute() executes the Action parameter.

public override bool CanExecute(object parameter)
=> _canExecute == null || _canExecute((T)parameter); public override void Execute(object parameter)
{ _execute((T)parameter); }

Updating MainWindow.xaml.cs
When you use RelayCommands, all of the methods for the delegates need to be specified when a new command is constructed. This doesn’t mean that the code needs to live in the code-behind (as is shown here); it just has to be accessible from the code-behind. It could live in another class (or even another assembly), providing the code encapsulation benefits of creating a custom command class.
Add a new private variable of type RelayCommand and a public property named DeleteCarCmd, as shown here:

private RelayCommand _deleteCarCommand = null; public RelayCommand DeleteCarCmd
=> _deleteCarCommand ??=
new RelayCommand(DeleteCar,CanDeleteCar));

The DeleteCar() and CanDeleteCar() methods must be created as well, as follows:

private bool CanDeleteCar(Car car) => car != null; private void DeleteCar(Car car)
{
_cars.Remove(car);
}

Notice the strong typing in the methods—this is one of the benefits of using RelayCommand.

Adding and Implementing the Delete Car Button
The final step to tie it all together is to add the button and assign the Command and CommandParameter
bindings. Add the following markup:

Now when you run the application, you can test that the Delete Car button is enabled only if a car is selected in the drop-down and that clicking the button does indeed delete the car from the Car list.

Wrapping Up Commands
This concludes your brief journey into WPF commands. By moving the event handling out of the code- behind file and into individual command classes, you gain the benefit of code encapsulating, reuse, and improved maintainability. If you don’t need that much separation of concerns, you can use the lighter- weight RelayCommand implementation. The goal is to improve maintainability and code quality, so choose the method that works best for you.

Migrate Code and Data to a View Model
As in the “WPF Validations” section, you can continue working in the same project, or you can create a new one and copy all of the code over. I will create a new project named WpfViewModel. If you are using the same project, be sure to pay attention to the namespaces in the code samples in this section and adjust as needed.
Create a new folder named ViewModels in your project, and add a new class named
MainWindowViewModel.cs into that folder. Add the following namespaces and make the class public:

using System.Collections.Generic; using System.Collections.ObjectModel; using System.Windows.Input;
using WpfViewModel.Cmds; using WpfViewModel.Models;

■Note a popular convention is to name the view models after the window they support. I typically follow that convention and will do so in this chapter. however, like any pattern or convention, this isn’t a rule, and you will find a wide range of opinions on this.

Moving the MainWindow.xaml.cs Code
Almost all the code from the code-behind file will be moved to the view model. At the end, there will only be a few lines, including the call to InitializeComponent() and the code for setting the data context for the window to the view model.
Create a public property of type IList named Cars, like this:

public IList Cars { get; } = new ObservableCollection();

Create a default constructor and move all the Car creation code from the MainWindow.xaml.cs file, updating the list variable name. You can also delete the _cars variable from MainWindow.xaml.cs. Here is the view model constructor:

public MainWindowViewModel()
{
Cars.Add(
new Car { Id = 1, Color = "Blue", Make = "Chevy", PetName = "Kit", IsChanged = false }); Cars.Add(
new Car { Id = 2, Color = "Red", Make = "Ford", PetName = "Red Rider", IsChanged = false });
}

Next, move all the command-related code from the window code-behind file to the view model, updating the _cars variable reference to Cars. Here is just the changed code:

//rest omitted for brevity private void DeleteCar(Car car)
{
Cars.Remove(car);
}

Updating the MainWindow Code and Markup
Most of the code has been removed from the MainWindow.xaml.cs file. Remove the line that assigns the
ItemsSource for the combo box, leaving only the call to InitializeComponent. It should now look like this:

public MainWindow()
{
InitializeComponent();
}

Add the following using statement to the top of the file:

using WpfViewModel.ViewModels;

Next, create a strongly typed property to hold the instance of the view model.

public MainWindowViewModel ViewModel { get; set; }
= new MainWindowViewModel();

Finally, add a DataContext property to the window’s declaration in XAML.

DataContext="{Binding ViewModel, RelativeSource={RelativeSource Self}}"

Updating the Control Markup
Now that the DataContext for the Window is set to the view model, the XAML bindings for the controls need to be updated. Starting with the combo box, update the markup by adding an ItemsSource.

This works because the data context for the Window is the MainWindowViewModel, and Cars is a public property on the view model. Recall that binding calls walk up the element tree until a data context is located. Next, you need to update the bindings for the Button controls. This is straightforward; since the bindings are already set to the window level, you just need to update the binding statement to start with the DataContext property, as follows:

Wrapping Up View Models
Believe it or not, you have just completed your first MVVM WPF application. You might be thinking, “This isn’t a real application. What about data? The data in this example is hard-coded.” And you would be correct. It’s not a real app; it’s demoware. However, that is the beauty of the MVVM pattern. The view doesn’t know anything about where the data is coming from; it’s just binding to a property on the view model. You can swap out view model implementations, perhaps using a version with hard-coded data for testing and one that hits the database for production.
There are a lot of additional points that could be discussed, including various open source frameworks, the View Model Locator pattern, and a host of differing opinions on how to best implement the pattern.
That’s the beauty of software design patterns—there are usually many correct ways to implement it, and then you just need to find the best manner based on your business and technical requirements.

Updating AutoLot.Dal for MVVM
If you want to update AutoLot.Dal for MVVM, you will have to apply the changes that we did for the Car
class to all of the entities in the AutoLot.Dal.Models project, including the BaseEntity.

Summary
This chapter examined the WPF topics that support the Model-View-ViewModel pattern. You started off learning how to tie model classes and collections into the notification system in the binding manager. You implemented INotifyPropertyChanged and used ObservableCollections classes to keep the UI in sync with the bound data.
Next, you added validation code to the model using IDataErrorInfo and INotifyDataErrorInfo and checked for data annotation errors. You then displayed any validation errors in the UI so the user would know what the problem is and how to fix it, and you created a style and custom control template to render errors in a meaningful way.
Finally, you put it all together by adding a view model, and you cleaned up the UI markup and code- behind file to increase separation of concerns.

CHAPTER 28

WPF Resources, Animations, Styles, and Templates

This chapter introduces you to three important (and interrelated) topics that will deepen your understanding of the Windows Presentation Foundation (WPF) API. The first order of business is to learn the role of logical resources. As you will see, the logical resource (also known as an object resource) system is a way to name and refer to commonly used objects within a WPF application. While logical resources are often authored in XAML, they can also be defined in procedural code.
Next, you will learn how to define, execute, and control an animation sequence. Despite what you might think, WPF animations are not limited to video game or multimedia applications. Under the WPF API, animations can be as subtle as making a button appear to glow when it receives focus or expanding the size of a selected row in a DataGrid. Understanding animations is a key aspect of building custom control templates (as you will see later in this chapter).
You will then explore the role of WPF styles and templates. Much like a web page that uses CSS or the ASP.NET theme engine, a WPF application can define a common look and feel for a set of controls. You can define these styles in markup and store them as object resources for later use, and you can also apply them dynamically at runtime. The final example will teach you how to build custom control templates.

Understanding the WPF Resource System
Your first task is to examine the topic of embedding and accessing application resources. WPF supports two flavors of resources. The first is a binary resource, and this category typically includes items most programmers consider to be resources in the traditional sense (embedded image files or sound clips, icons used by the application, etc.).
The second flavor, termed object resources or logical resources, represents a named .NET object that can be packaged and reused throughout the application. While any .NET object can be packaged as an object resource, logical resources are particularly helpful when working with graphical data of any sort, given that you can define commonly used graphic primitives (brushes, pens, animations, etc.) and refer to them when required.

© Andrew Troelsen, Phil Japikse 2022
A. Troelsen and P. Japikse, Pro C# 10 with .NET 6, https://doi.org/10.1007/978-1-4842-7869-7_28

1233

Working with Binary Resources
Before getting to the topic of object resources, let’s quickly examine how to package up binary resources such as icons or image files (e.g., company logos or images for an animation) into your applications. If you would like to follow along, create a new WPF application named BinaryResourcesApp. Update the markup for your initial window to handle the Window Loaded event and to use a DockPanel as the layout root, like so:

<Window x:Class="BinaryResourcesApp.MainWindow"

Title="Fun with Binary Resources" Height="500" Width="649" Loaded="MainWindow_OnLoaded">

Now, let’s say your application needs to display one of three image files inside part of the window, based on user input. The WPF Image control can be used to display not only a typical image file (.bmp,
.gif, .ico, .jpg, .png, .wdp, or *.tiff) but also data in a DrawingImage (as you saw in Chapter 27). You might build a UI for your window that supports a DockPanel containing a simple toolbar with Next and Previous buttons. Below this toolbar you can place an Image control, which currently does not have a value set to the Source property, like so:

Next, add the following empty event handlers:

private void MainWindow_OnLoaded( object sender, RoutedEventArgs e)
{
}
private void btnPreviousImage_Click( object sender, RoutedEventArgs e)
{
}
private void btnNextImage_Click( object sender, RoutedEventArgs e)
{
}

When the window loads, images will be added to a collection that the Next and Previous buttons will cycle through. Now that the application framework is in place, let’s examine the different options for implementing this.

Including Loose Resource Files in a Project
One option is to ship your image files as a set of loose files in a subdirectory of the application install path. Start by adding a new folder (named Images) to your project. Into this folder add some images by right- clicking and selecting Add ➤ Existing Item. Make sure to change the file filter in the Add Existing Item dialog to . so the image files show. You can add your own image files or use the three image files named Deer. jpg, Dogs.jpg, and Welcome.jpg from the downloadable code.

Configuring the Loose Resources
To copy the content of your \Images folder to the \bin\Debug folder when the project builds, begin by selecting all the images in Solution Explorer. Now, with these images still selected, right-click and select Properties to open the Properties window. Set the Build Action property to Content, and set the Copy to Output Directory property to “Copy always” (see Figure 28-1).

Figure 28-1. Configuring the image data to be copied to your output directory

■Note you could also select Copy if newer, which will save you time if you’re building large projects with a lot of content. For this example, “Copy always” works.

If you build your project, you can now click the Show All Files button of Solution Explorer and view the copied Image folder under your \bin\Debug directory (you might need to click the Refresh button).

Programmatically Loading an Image
WPF provides a class named BitmapImage, which is part of the System.Windows.Media.Imaging namespace.
This class allows you to load data from an image file whose location is represented by a System.Uri object. Add a List to hold the images, as well as an int to store the index of the currently displayed image.

// A List of BitmapImage files.
List _images=new List();
// Current position in the list.
private int _currImage=0;

In the Loaded event of your window, fill the list of images and then set the Image control source to the first image in the list.

private void MainWindow_OnLoaded( object sender, RoutedEventArgs e)
{
try
{
string path=Environment.CurrentDirectory;
// Load these images from disk when the window loads.
_images.Add(new BitmapImage(new Uri($@"{path}\Images\Deer.jpg")));
_images.Add(new BitmapImage(new Uri($@"{path}\Images\Dogs.jpg")));
_images.Add(new BitmapImage(new Uri($@"{path}\Images\Welcome.jpg")));
// Show first image in the List.
imageHolder.Source=_images[_currImage];
}
catch (Exception ex)
{
MessageBox.Show(ex.Message);
}
}

Next, implement the previous and next handlers to loop through the images. If the user gets to the end of the list, start them back at the beginning and vice versa.

private void btnPreviousImage_Click( object sender, RoutedEventArgs e)
{
if (--_currImage < 0)
{
_currImage=_images.Count - 1;
}
imageHolder.Source=_images[_currImage];
}
private void btnNextImage_Click( object sender, RoutedEventArgs e)
{
if (++_currImage >=_images.Count)
{
_currImage=0;
}
imageHolder.Source=_images[_currImage];
}

At this point, you can run your program and flip through each picture.

Embedding Application Resources
If you would rather configure your image files to be compiled directly into your .NET assembly as binary resources, select the image files in Solution Explorer (in the \Images folder, not in the \bin\Debug\Images folder). Change the Build Action property to Resource and set the Copy to Output Directory property to “Do not copy” (see Figure 28-2).

Figure 28-2. Configuring the images to be embedded resources

Now, using Visual Studio’s Build menu, select the Clean Solution option to wipe out the current contents of \bin\Debug\Images and then rebuild your project. Refresh Solution Explorer and observe the absence of data in your \bin\Debug\Images directory. With the current build options, your graphical data is no longer copied to the output folder and is now embedded within the assembly itself. This ensures that the resources exist but also increases the size of your compiled assembly.
You need to modify your code to load these images into your list by extracting them from the compiled assembly.

// Extract from the assembly and then load images
_images.Add(new BitmapImage(new Uri(@"/Images/Deer.jpg", UriKind.Relative)));
_images.Add(new BitmapImage(new Uri(@"/Images/Dogs.jpg", UriKind.Relative)));
_images.Add(new BitmapImage(new Uri(@"/Images/Welcome.jpg", UriKind.Relative)));

In this case, you no longer need to determine the installation path and can simply list the resources by name, which considers the name of the original subdirectory. Also notice, when you create your Uri objects, you specify a UriKind value of Relative. At this point, your executable is a stand-alone entity that can be run from any location on the machine because all the compiled data is within the binary.

Working with Object (Logical) Resources
When you are building a WPF application, it is common to define a blurb of XAML to use in multiple locations within a window or perhaps across multiple windows or projects. For example, say you have created the perfect linear gradient brush, which consists of ten lines of markup. Now, you want to use that brush as the background color for every Button control in the project (which consists of eight windows) for a total of 16 Button controls.

The worst thing you could do is to copy and paste the XAML to every control. Clearly, this would be a nightmare to maintain, as you would need to make numerous changes any time you wanted to tweak the look and feel of the brush.
Thankfully, object resources allow you to define a blob of XAML, give it a name, and store it in a fitting dictionary for later use. Like a binary resource, object resources are often compiled into the assembly that requires them. However, you do not need to tinker with the Build Action property to do so. If you place your XAML into the correct location, the compiler will take care of the rest.
Working with object resources is a big part of WPF development. As you will see, object resources can be far more complex than a custom brush. You can define a XAML-based animation, a 3D rendering, a custom control style, a data template, a control template, and more, and package each one as a reusable resource.

The Role of the Resources Property
As mentioned, object resources must be placed in a fitting dictionary object to be used across an application. As it stands, every descendant of FrameworkElement supports a Resources property. This property encapsulates a ResourceDictionary object that contains the defined object resources. The ResourceDictionary can hold any type of item because it operates on System.Object types and may be manipulated via XAML or procedural code.
In WPF, all controls, Windows, Pages (used when building navigation applications), and UserControls extend FrameworkElement, so just about all widgets provide access to a ResourceDictionary. Furthermore, the Application class, while not extending FrameworkElement, supports an identically named Resources property for the same purpose.

Defining Window-wide Resources
To begin exploring the role of object resources, create a new WPF application named ObjectResourcesApp and change the initial Grid to a horizontally aligned StackPanel layout manager. Into this StackPanel, define two Button controls like so (you really do not need much to illustrate the role of object resources, so this will do):

Now, click the OK button and set the Background color property to a custom brush type using the integrated Brushes editor (discussed in Chapter 27). After you have done so, notice how the brush is embedded within the scope of the

and tags, as shown here:

To allow the Cancel button to use this brush as well, you should promote the scope of your

to a parent element’s resource dictionary. For example, if you move it to the
, both buttons can use the same brush because they are child elements of the layout manager. Even better, you could package the brush into the resource dictionary of the Window itself so the window’s content can use it.
When you need to define a resource, you use the property-element syntax to set the Resources property of the owner. You also give the resource item an x:Key value, which will be used by other parts of the window when they want to refer to the object resource. Be aware that x:Key and x:Name are not the same! The x:Name attribute allows you to gain access to the object as a member variable in your code file, while the x:Key attribute allows you to refer to an item in a resource dictionary.
Visual Studio allows you to promote a resource to a higher scope using its respective Properties window.
To do so, first identify the property that has the complex object you want to package as a resource (the Background property, in this example). To the right of the property is a small square that, when clicked, will open a pop-up menu. From it, select the Convert to New Resource option (see Figure 28-3).

Figure 28-3. Moving a complex object into a resource container

You are asked to name your resource (myBrush) and specify where to place it. For this example, leave the default selection of the current document (see Figure 28-4).

Figure 28-4. Naming the object resource

When you are done, you will see the brush has been moved inside the Window.Resources tag.

And the Button control’s Background has been updated to use a new resource.

The Create Resource Wizard creates the new resource as a DynamicResource. You will learn about
DynamicResources later in the text, but for now, change it to a StaticResource, like this:

To see the benefit, update the Cancel Button’s Background property to the same StaticResource, and you can see the reuse in action.

The {StaticResource} Markup Extension
The {StaticResource} markup extension applies the resource only once (on initialization) and stays “connected” to the original object during the life of the application. Some properties (such as gradient stops) will update, but if you create a new Brush, for example, the control will not be updated. To see this in action, add a Name and Click event handler to each Button control, as follows:

Next, add the following code to the Ok_OnClick() event handler:

private void Ok_OnClick(object sender, RoutedEventArgs e)
{
// Get the brush and make a change.
var b=(RadialGradientBrush)Resources["myBrush"]; b.GradientStops[1]=new GradientStop(Colors.Black, 0.0);
}

■Note you are using the Resources indexer to locate a resource by name here. Be aware, however, that this will throw a runtime exception if the resource cannot be found. you could also use the
TryFindResource() method, which will not throw a runtime error; it will simply return null if the specified resource cannot be located.

When you run the program and click the OK Button, you see the gradients change appropriately. Now add the following code to the Cancel_OnClick() event handler:

private void Cancel_OnClick(object sender, RoutedEventArgs e)
{
// Put a totally new brush into the myBrush slot. Resources["myBrush"]=new SolidColorBrush(Colors.Red);
}

Run the program again, click the Cancel Button, and nothing happens!

The {DynamicResource} Markup Extension
It is also possible for a property to use the DynamicResource markup extension. To see the difference, change the markup for the Cancel Button to the following:

This time, when you click the Cancel Button, the background for the Cancel Button changes, but the background for the OK Button remains the same. This is because the {DynamicResource} markup extension can detect whether the underlying keyed object has been replaced with a new object. As you might guess,

this requires some extra runtime infrastructure, so you should typically stick to using {StaticResource} unless you know you have an object resource that will be swapped with a different object at runtime and you want all items using that resource to be informed.

Application-Level Resources
When you have object resources in a window’s resource dictionary, all items in the window are free to make use of it, but other windows in the application cannot. The solution to share resources across your application is to define the object resource at the application level, rather than at the window level. There is no way to automate this within Visual Studio, so simply cut the current brush object out of the scope and place it in the scope in your App.xaml file.
Now any additional window or control in your application is free to use this same brush. If you want to set the Background property for a control, the application-level resources are available for selection, as shown in Figure 28-5.

Figure 28-5. Applying application-level resources

■Note placing the resources at the application level and assigning it to a control’s property will freeze the resource, preventing changing values at runtime. the resource can be cloned, and the clone can be updated.

Defining Merged Resource Dictionaries
Application-level resources are a quite often good enough, but they do not help reuse across projects. In this case, you want to define what is known as a merged resource dictionary. Think of it as a class library for WPF resources; it is nothing more than a XAML file that contains a collection of resources. A single project can have as many of these files as required (one for brushes, one for animations, etc.), each of which can be inserted using the Add New Item dialog box activated via the Project menu (see Figure 28-6).

Figure 28-6. Inserting a new merged resource dictionary

In the new MyBrushes.xaml file, cut the current resources in the Application.Resources scope and move them into your dictionary, like so:

Even though this resource dictionary is part of your project, all resource dictionaries must be merged (typically at the application level) into an existing resource dictionary to be used. To do this, use the following format in the App.xaml file (note that multiple resource dictionaries can be merged by adding multiple elements within the scope):

The problem with this approach is that each resource file must be added to each project that needs the resources. A better approach for sharing resources is to define a .NET class library to share between projects, which you will do next.

Defining a Resource-Only Assembly
The easiest way to build a resource-only assembly is to begin with a WPF User Control Library project. Add such a project (named MyBrushesLibrary) to your current solution via the Add ➤ New Project menu option of Visual and add a project reference to it from the ObjectResourcesApp project.
Now, delete the UserControl1.xaml file from the project. Next, drag and drop the MyBrushes.xaml file into your MyBrushesLibrary project and delete it from the ObjectResourcesApp project. Finally, open MyBrushes.xaml in the MyBrushesLibrary project and change the x:local namespace in the file to clr- namespace:MyBrushesLibrary. Your MyBrushes.xaml file should look like this:

Compile your User Control Library project. Now, merge these binary resources into the application- level resource dictionary of the ObjectResourcesApp project. Doing so, however, requires some rather funky syntax, shown here:

First, be aware that this string is space sensitive. If you have extra whitespace around your semicolon or forward slashes, you will generate errors. The first part of the string is the friendly name of the external library (no file extension). After the semicolon, type in the word Component followed by the name of the compiled binary resource, which will be identical to the original XAML resource dictionary.
That wraps up the examination of WPF’s resource management system. You will make good use of these techniques for most (if not all) of your applications. Next up, let’s investigate the integrated animation API of Windows Presentation Foundation.

Understanding WPF’s Animation Services
In addition to the graphical rendering services you examined in Chapter 27, WPF supplies a programming interface to support animation services. The term animation may bring to mind visions of spinning company logos, a sequence of rotating image resources (to provide the illusion of movement), text bouncing across the screen, or specific types of programs such as video games or multimedia applications.
While WPF’s animation APIs could certainly be used for such purposes, animation can be used any time you want to give an application additional flair. For example, you could build an animation for a button on
a screen that magnifies slightly when the mouse cursor hovers within its boundaries (and shrinks back once the mouse cursor moves beyond the boundaries). Or you could animate a window so that it closes using a particular visual appearance, such as slowly fading into transparency. A more business application–centric use is to fade in error messages on an application screen to improve the user experience. In fact, WPF’s animation support can be used within any sort of application (a business application, multimedia programs, video games, etc.) whenever you want to provide a more engaging user experience.
As with many other aspects of WPF, the notion of building animations is nothing new. What is new is that, unlike other APIs you might have used in the past (including Windows Forms), developers are not required to author the necessary infrastructure by hand. Under WPF, there is no need to create the
background threads or timers used to advance the animation sequence, define custom types to represent the animation, erase and redraw images, or bother with tedious mathematical calculations. Like other aspects
of WPF, you can build an animation entirely using XAML, entirely using C# code, or using a combination of the two.

■Note Visual studio has no support for authoring animations using Gui animation tools. if you author an animation with Visual studio, you will do so by typing in the Xaml directly. however, Blend for Visual studio (the companion product that ships with Visual studio 2019) does indeed have a built-in animation editor that can simplify your life a good deal.

The Role of the Animation Class Types
To understand WPF’s animation support, you must begin by examining the animation classes within the System.Windows.Media.Animation namespace of PresentationCore.dll. Here, you will find more than 100 different class types that are named using the Animation token.
These classes can be placed into one of three broad categories. First, any class that follows the name convention DataTypeAnimation (ByteAnimation, ColorAnimation, DoubleAnimation, Int32Animation, etc.) allows you to work with linear interpolation animations. This enables you to change a value smoothly over time from a start value to a final value.
Next, the classes that follow the naming convention DataTypeAnimationUsingKeyFrames (StringAnimationUsingKeyFrames, DoubleAnimationUsingKeyFrames, PointAnimationUsingKeyFrames, etc.) represent “key frame animations,” which allow you to cycle through a set of defined values over a period of time. For example, you could use key frames to change the caption of a button by cycling through a series of individual characters.
Finally, classes that follow the DataTypeAnimationUsingPath naming convention (DoubleAnimationUsingPath, PointAnimationUsingPath, among others) are path-based animations that allow you to animate objects to move along a path you define. By way of an example, if you were building a GPS application, you could use a path-based animation to move an item along the quickest travel route to the user’s destination.

Now, obviously, these classes are not used to somehow provide an animation sequence directly to a variable of a particular data type (after all, how exactly could you animate the value “9” using an Int32Animation?).
For example, consider the Label type’s Height and Width properties, both of which are dependency properties wrapping a double. If you wanted to define an animation that would increase the height of a label over a time span, you could connect a DoubleAnimation object to the Height property and allow WPF to
take care of the details of performing the actual animation itself. By way of another example, if you wanted to transition the color of a brush type from green to yellow over a period of five seconds, you could do so using the ColorAnimation type.
To be clear, these Animation classes can be connected to any dependency property of a given object that
matches the underlying types. As explained in Chapter 26, dependency properties are a specialized form of property required by many WPF services including animation, data binding, and styles.
By convention, a dependency property is defined as a static, read-only field of the class and is named by suffixing the word Property to the normal property name. For example, the dependency property for the Height property of a Button would be accessed in code using Button.HeightProperty.

The To, From, and By Properties
All Animation classes define the following handful of key properties that control the starting and ending values used to perform the animation:
•To: This property represents the animation’s ending value.
•From: This property represents the animation’s starting value.
•By: This property represents the total amount by which the animation changes its starting value.
Despite that all Animation classes support the To, From, and By properties, they do not receive them via virtual members of a base class. The reason for this is that the underlying types wrapped by these properties vary greatly (integers, colors, Thickness objects, etc.), and representing all possibilities using a single base class would result in complex coding constructs.
On a related note, you might also wonder why .NET generics were not used to define a single generic animation class with a single type parameter (e.g., Animate). Again, given that there are so many underlying data types (colors, vectors, ints, strings, etc.) used to animated dependency properties, it would not be as clean a solution as you might expect (not to mention XAML has only limited support for generic types).

The Role of the Timeline Base Class
Although a single base class was not used to define virtual To, From, and By properties, the Animation classes do share a common base class: System.Windows.Media.Animation.Timeline. This type provides several additional properties that control the pacing of the animation, as described in Table 28-1.

Table 28-1. Key Members of the Timeline Base Class

Properties Meaning in Life
AccelerationRatio, DecelerationRatio, SpeedRatio These properties can be used to control the overall pacing of the animation sequence.
AutoReverse This property gets or sets a value that indicates whether the timeline plays in reverse after it completes a forward iteration (the default value is false).
BeginTime This property gets or sets the time at which this timeline should begin. The default value is 0, which begins the animation immediately.
Duration This property allows you to set a duration of time to play the timeline.
FillBehavior, RepeatBehavior These properties are used to control what should happen once the timeline has completed (repeat the animation, do nothing, etc.).

Authoring an Animation in C# Code
Specifically, you will build a Window that contains a Button, which has the odd behavior of spinning in a circle (based on the upper-left corner) whenever the mouse enters its surface area. Begin by creating a new WPF application named SpinningButtonAnimationApp. Update the initial markup to the following (note you are handling the button’s MouseEnter event):

In the code-behind file, import the System.Windows.Media.Animation namespace and add the following code in the window’s C# code file:
private bool _isSpinning=false; private void btnSpinner_MouseEnter(
object sender, MouseEventArgs e)
{
if (!_isSpinning)
{
_isSpinning=true;
// Make a double animation object, and register
// with the Completed event.
var dblAnim=new DoubleAnimation();
dblAnim.Completed +=(o, s)=> { _isSpinning=false; };
// Set the start value and end value.
dblAnim.From=0; dblAnim.To=360;
// Now, create a RotateTransform object, and set
// it to the RenderTransform property of our
// button.
var rt=new RotateTransform(); btnSpinner.RenderTransform=rt;

// Now, animation the RotateTransform object.
rt.BeginAnimation(RotateTransform.AngleProperty, dblAnim);
}
}
private void btnSpinner_OnClick( object sender, RoutedEventArgs e)
{

}

The first major task of this method is to configure a DoubleAnimation object, which will start at the value 0 and end at the value 360. Notice that you are handling the Completed event on this object as well, to toggle a class-level bool variable that is used to ensure that if an animation is currently being performed, you don’t “reset” it to start again.
Next, you create a RotateTransform object that is connected to the RenderTransform property of your Button control (btnSpinner). Finally, you inform the RenderTransform object to begin animating its Angle property using your DoubleAnimation object. When you are authoring animations in code, you typically do so by calling BeginAnimation() and then pass in the underlying dependency property you would like to
animate (remember, by convention, this is a static field on the class), followed by a related animation object.
Let’s add another animation to the program, which will cause the button to fade into invisibility when clicked. First, add the following code in the Click event handler:

private void btnSpinner_OnClick( object sender, RoutedEventArgs e)
{
var dblAnim=new DoubleAnimation
{
From=1.0, To=0.0
};
btnSpinner.BeginAnimation(Button.OpacityProperty, dblAnim);
}

Here, you are changing the Opacity property value to fade the button out of view. Currently, however, this is hard to do, as the button is spinning very fast! How, then, can you control the pace of an animation? Glad you asked.

Controlling the Pace of an Animation
By default, an animation will take approximately one second to transition between the values assigned to the From and To properties. Therefore, your button has one second to spin around a full 360-degree angle, while the button will fade away to invisibility (when clicked) over the course of one second.
If you want to define a custom amount of time for an animation’s transition, you may do so via the animation object’s Duration property, which can be set to an instance of a Duration object. Typically, the time span is established by passing a TimeSpan object to the Duration’s constructor. Consider the following update that will give the button a full four seconds to rotate:

private void btnSpinner_MouseEnter( object sender, MouseEventArgs e)
{
if (!_isSpinning)
{
_isSpinning=true;

// Make a double animation object, and register
// with the Completed event.
var dblAnim=new DoubleAnimation();
dblAnim.Completed +=(o, s)=> { _isSpinning=false; };

// Button has four seconds to finish the spin!
dblAnim.Duration=new Duration(TimeSpan.FromSeconds(4));

...
}
}

With this adjustment, you should have a fighting chance of clicking the button while it is spinning, at which point it will fade away.

■Note the BeginTime property of an Animation class also takes a TimeSpan object. recall that this property can be set to establish a wait time before starting an animation sequence.

Reversing and Looping an Animation
You can also tell Animation objects to play an animation in reverse at the completion of the animation sequence by setting the AutoReverse property to true. For example, if you want to have the button come back into view after it has faded away, you could author the following:

private void btnSpinner_OnClick(object sender, RoutedEventArgs e)
{
DoubleAnimation dblAnim=new DoubleAnimation
{
From=1.0, To=0.0
};
// Reverse when done.
dblAnim.AutoReverse=true; btnSpinner.BeginAnimation(Button.OpacityProperty, dblAnim);
}

If you would like to have an animation repeat some number of times (or to never stop once activated), you can do so using the RepeatBehavior property, which is common to all Animation classes. If you pass in a simple numerical value to the constructor, you can specify a hard-coded number of times to repeat.

On the other hand, if you pass in a TimeSpan object to the constructor, you can establish an amount of time the animation should repeat. Finally, if you want an animation to loop ad infinitum, you can simply specify RepeatBehavior.Forever. Consider the following ways you could change the repeat behaviors of either of the DoubleAnimation objects used in this example:

// Loop forever.
dblAnim.RepeatBehavior=RepeatBehavior.Forever;

// Loop three times.
dblAnim.RepeatBehavior=new RepeatBehavior(3);

// Loop for 30 seconds.
dblAnim.RepeatBehavior=new RepeatBehavior(TimeSpan.FromSeconds(30));

That wraps up your investigation about how to animate aspects of an object using C# code and the WPF animation API. Next, you will learn how to do the same using XAML.

Authoring Animations in XAML
Authoring animations in markup is like authoring them in code, at least for simple, straightforward animation sequences. When you need to capture more complex animations, which may involve changing the values of numerous properties at once, the amount of markup can grow considerably. Even if you
use a tool to generate XAML-based animations, it is important to know the basics of how an animation is represented in XAML because this will make it easier for you to modify and tweak tool-generated content.

■Note you will find a number of Xaml files in the XamlAnimations folder of the downloadable source code. as you go through the next several pages, copy these markup files into your custom Xaml editor or into the Kaxaml editor to see the results.

For the most part, creating an animation is like what you saw already. You still configure an Animation object and associate it to an object’s property. One big difference, however, is that WPF is not function call friendly. As a result, instead of calling BeginAnimation(), you use a storyboard as a layer of indirection.
Let’s walk through a complete example of an animation defined in terms of XAML, followed by a detailed breakdown. The following XAML definition will display a window that contains a single label. As soon as the Label object loads into memory, it begins an animation sequence in which the font size increases from 12 points to 100 over a period of four seconds. The animation will repeat for as long as the
Window object is loaded in memory. You can find this markup in the GrowLabelFont.xaml file, so copy it into Kaxaml (make sure to press F5 to show the window) and observe the behavior.

Now, let’s break this example down, bit by bit.

The Role of Storyboards
Working from the innermost element outward, you first encounter the element, which makes use of the same properties you set in procedural code (From, To, Duration, and RepeatBehavior).

As mentioned, Animation elements are placed within a element, which is used to map the animation object to a given property on the parent type via the TargetProperty property, which in this case is FontSize. A is always wrapped in a parent element named .

The Role of Event Triggers
After the element has been defined, you need to specify some sort of action that will cause the animation to begin executing. WPF has a few different ways to respond to runtime conditions in markup, one of which is termed a trigger. From a high level, you can consider a trigger a way of responding to an event condition in XAML, without the need for procedural code.
Typically, when you respond to an event in C#, you author custom code that will execute when the event occurs. A trigger, however, is just a way to be notified that some event condition has happened (“I’m loaded into memory!” or “The mouse is over me!” or “I have focus!”).
Once you have been notified that an event condition has occurred, you can start the storyboard. In this example, you are responding to the Label being loaded into memory. Because it is the Label’s Loaded event you are interested in, the is placed in the Label’s trigger collection.

Let’s see another example of defining an animation in XAML, this time using a key frame animation.

Animation Using Discrete Key Frames
Unlike the linear interpolation animation objects, which can only move between a starting point and an ending point, the key frame counterparts allow you to create a collection of specific values for an animation that should take place at specific times.
To illustrate the use of a discrete key frame type, assume you want to build a Button control that animates its content so that over the course of three seconds the value “OK!” appears, one character at a time. You will find the following markup in the AnimateString.xaml file. Copy this markup into your MyXamlPad.exe program (or Kaxaml) and view the results:

First, notice that you have defined an event trigger for your button to ensure that your storyboard executes when the button has loaded into memory. The StringAnimationUsingKeyFrames class oversees changing the content of the button, via the Storyboard.TargetProperty value.
Within the scope of the element, you define four DiscreteStringKeyFrame elements, which change the button’s Content property over the course of two seconds (note that the duration established by StringAnimationUsingKeyFrames is a total of three seconds, so you will see a slight pause between the final ! and looping O).
Now that you have a better feel for how to build animations in C# code and XAML, let’s look at the role of WPF styles, which make heavy use of graphics, object resources, and animations.

Understanding the Role of WPF Styles
When you are building the UI of a WPF application, it is not uncommon for a family of controls to require a shared look and feel. For example, you might want all button types to have the same height, width, background color, and font size for their string content. Although you could handle this by setting each button’s individual properties to identical values, such an approach makes it difficult to implement changes down the road because you would need to reset the same set of properties on multiple objects for every change.
Thankfully, WPF offers a simple way to constrain the look and feel of related controls using styles.
Simply put, a WPF style is an object that maintains a collection of property-value pairs. Programmatically speaking, an individual style is represented using the System.Windows.Style class. This class has a property named Setters, which exposes a strongly typed collection of Setter objects. It is the Setter object that allows you to define the property-value pairs.
In addition to the Setters collection, the Style class also defines a few other important members that allow you to incorporate triggers, restrict where a style can be applied, and even create a new style based on an existing style (think of it as “style inheritance”). Be aware of the following members of the Style class:
•Triggers: Exposes a collection of trigger objects, which allow you to capture various event conditions within a style
•BasedOn: Allows you to build a new style based on an existing style
•TargetType: Allows you to constrain where a style can be applied

Defining and Applying a Style
In almost every case, a Style object will be packaged as an object resource. Like any object resource, you can package it at the window or application level, as well as within a dedicated resource dictionary (this is great because it makes the Style object easily accessible throughout your application). Now recall that the goal is to define a Style object that fills (at minimum) the Setters collection with a set of property-value pairs.
Let’s build a style that captures the basic font characteristics of a control in your application. Start by creating a new WPF application named WpfStyles. Open your App.xaml file and define the following named style:

Notice that your BasicControlStyle adds three Setter objects to the internal collection. Now, let’s apply this style to a few controls in your main window. Because this style is an object resource, the controls that want to use it still need to use the {StaticResource} or {DynamicResource} markup extension to locate the style. When they find the style, they will set the resource item to the identically named Style property. Replace the default Grid control with the following markup:

If you view the Window in the Visual Studio designer (or run the application), you will find that both controls support the same cursor, height, and font size.

Overriding Style Settings
While both of your controls have opted into the style, if a control wants to apply a style and then change some of the defined settings, that is fine. For example, the Button will now use the Help cursor (rather than the Hand cursor defined in the style).

Styles are processed before the individual property settings of the control using the style; therefore, controls can “override” settings on a case-by-case basis.

The Effect of TargetType on Styles
Currently, your style is defined in such a way that any control can adopt it (and must do so explicitly by setting the control’s Style property), given that each property is qualified by the Control class. For a program that defines dozens of settings, this would entail a good amount of repeated code. One way to clean this style up a bit is to use the TargetType attribute. When you add this attribute to a Style’s opening element, you can mark exactly once where it can be applied (in this example, in App.XAML).

■Note When you build a style that uses a base class type, you needn’t be concerned if you assign a value to a dependency property not supported by derived types. if the derived type does not support a given dependency property, it is ignored.

This is somewhat helpful, but you still have a style that can apply to any control. The TargetType attribute is more useful when you want to define a style that can be applied to only a particular type of control. Add the following new style to the application’s resource dictionary:

This style will work only on Button controls (or a subclass of Button). If you apply it to an incompatible element, you will get markup and compiler errors. Add a new Button that uses this new style, as follows:

You will see output like that shown in Figure 28-7.

Figure 28-7. Controls with different styles

Another effect of TargetType is that the style will get applied to all elements of that type within the scope of the style definition if the x:Key property does not exist.
Here is another application-level style that will apply automatically to all TextBox controls in the current application:

You can now define any number of TextBox controls, and they will automatically get the defined look.
If a given TextBox does not want this default look and feel, it can opt out by setting the Style property to {x:Null}. For example, txtTest will get the default unnamed style, while txtTest2 is doing things its own way.

Subclassing Existing Styles
You can also build new styles using an existing style, via the BasedOn property. The style you are extending must have been given a proper x:Key in the dictionary, as the derived style will reference it by name
using the {StaticResource} or {DynamicResource} markup extension. Here is a new style based on
BigGreenButton, which rotates the button element by 20 degrees:

To use this new style, update the markup for the button to this:

This changes the appearance to the image shown in Figure 28-8.

Figure 28-8. Using a derived style

Defining Styles with Triggers
WPF styles can also contain triggers by packaging up Trigger objects within the Triggers collection of the Style object. Using triggers in a style allows you to define certain elements in such a way that they will be applied only if a given trigger condition is true. For example, perhaps you want to increase the size of a font when the mouse is over a button. Or maybe you want to make sure that the text box with the current

focus is highlighted with a given color. Triggers are useful for these sorts of situations, in that they allow you to take specific actions when a property changes, without the need to author explicit C# code in a code- behind file.
Here is an update to the TextBox style that ensures that when a TextBox has the input focus, it will receive a yellow background:

If you test this style, you’ll find that as you tab between various TextBox objects, the currently selected TextBox has a bright yellow background (provided it has not opted out by assigning {x:Null} to the Style property).
Property triggers are also very smart, in that when the trigger’s condition is not true, the property automatically receives the default assigned value. Therefore, as soon as a TextBox loses focus, it also automatically becomes the default color without any work on your part. In contrast, event triggers (examined when you looked at WPF animations) do not automatically revert to a previous condition.

Defining Styles with Multiple Triggers
Triggers can also be designed in such a way that the defined elements will be applied when multiple conditions are true. Let’s say you want to set the background of a TextBox to Yellow only if it has the active focus and the mouse is hovering within its boundaries. To do so, you can make use of the
element to define each condition, like so:

Animated Styles
Styles can also incorporate triggers that kick off an animation sequence. Here is one final style that, when applied to Button controls, will cause the controls to grow and shrink in size when the mouse is inside the button’s surface area:

Here, the Triggers collection is on the lookout for the IsMouseOver property to return true. When this occurs, you define a element to execute a simple storyboard that forces the button to grow to a Height value of 200 (and then return to a Height of 40) over two seconds. If you want to perform other property changes, you could also define a scope to define any custom actions to take when IsMouseOver changes to false.

Assigning Styles Programmatically
Recall that a style can be applied at runtime as well. This can be helpful if you want to let end users choose how their UI looks and feels or if you need to enforce a look and feel based on security settings (e.g., the DisableAllButton style) or what have you.
During this project, you have defined several styles, many of which can apply to Button controls. So,
let’s retool the UI of your main window to allow the user to pick from some of these styles by selecting names in a ListBox. Based on the user’s selection, you will apply the appropriate style. Here is the new (and final) markup for the element:

The ListBox control (named lstStyles) will be filled dynamically within the window’s constructor, like so:

public MainWindow()
{
InitializeComponent();
// Fill the list box with all the Button styles. lstStyles.Items.Add("GrowingButtonStyle"); lstStyles.Items.Add("TiltButton"); lstStyles.Items.Add("BigGreenButton"); lstStyles.Items.Add("BasicControlStyle");}
}

The final task is to handle the SelectionChanged event in the related code file. Notice in the following code how you can extract the current resource by name, using the inherited TryFindResource() method:

private void comboStyles_Changed(object sender, SelectionChangedEventArgs e)
{
// Get the selected style name from the list box.
var currStyle=(Style)TryFindResource(lstStyles.SelectedValue); if (currStyle==null) return;
// Set the style of the button type.
this.btnStyle.Style=currStyle;
}

When you run this application, you can pick from one of these four button styles on the fly. Figure 28-9 shows your completed application.

Figure 28-9. Controls with different styles

Logical Trees, Visual Trees, and Default Templates
Now that you understand styles and resources, there are a few more preparatory topics to investigate before you begin learning how to build custom controls. Specifically, you need to learn the distinction between a logical tree, a visual tree, and a default template. When you are typing XAML into Visual Studio or a tool such as kaxaml.exe, your markup is the logical view of the XAML document. As well, if you author C# code that adds new items to a layout control, you are inserting new items into the logical tree. Essentially, a logical view represents how your content will be positioned within the various layout managers for a main Window (or another root element, such as Page or NavigationWindow).
However, behind every logical tree is a much more verbose representation termed a visual tree, which is used internally by WPF to correctly render elements onto the screen. Within any visual tree, there will be full details of the templates and styles used to render each object, including any necessary drawings, shapes, visuals, and animations.
It is useful to understand the distinction between logical and visual trees because when you are building a custom control template, you are essentially replacing all or part of the default visual tree of a control and inserting your own. Therefore, if you want a Button control to be rendered as a star shape,
you could define a new star template and plug it into the Button’s visual tree. Logically, the Button is still
of type Button, and it supports the properties, methods, and events as expected. But visually, it has taken on a whole new appearance. This fact alone makes WPF an extremely useful API, given that other toolkits would require you to build a new class to make a star-shaped button. With WPF, you simply need to define new markup.

■Note WpF controls are often described as lookless. this refers to the fact that the look and feel of a WpF control is completely independent (and customizable) from its behavior.

Programmatically Inspecting a Logical Tree
While analyzing a window’s logical tree at runtime is not a tremendously common WPF programming activity, it is worth mentioning that the System.Windows namespace defines a class named LogicalTreeHelper, which allows you to inspect the structure of a logical tree at runtime. To illustrate the connection between logical trees, visual trees, and control templates, create a new WPF application named TreesAndTemplatesApp.
Replace the Grid with the following markup that contains two Button controls and a large read-only TextBox with scrollbars enabled. Make sure you use the IDE to handle the Click event of each button. The following XAML will do nicely:

Within your C# code file, define a string member variable named _dataToShow. Now, within the Click handler for the btnShowLogicalTree object, call a helper function that calls itself recursively to populate the string variable with the logical tree of the Window. To do so, you will call the static GetChildren() method of LogicalTreeHelper. Here is the code:

private string _dataToShow=string.Empty;

private void btnShowLogicalTree_Click(object sender, RoutedEventArgs e)
{
_dataToShow=""; BuildLogicalTree(0, this); txtDisplayArea.Text=_dataToShow;
}

void BuildLogicalTree(int depth, object obj)
{
// Add the type name to the dataToShow member variable.
_dataToShow +=new string(' ', depth) + obj.GetType().Name + "\n";
// If an item is not a DependencyObject, skip it. if (!(obj is DependencyObject))
return;
// Make a recursive call for each logical child.
foreach (var child in LogicalTreeHelper.GetChildren((DependencyObject)obj))
{
BuildLogicalTree(depth + 5, child);
}
}
private void btnShowVisualTree_Click( object sender, RoutedEventArgs e)
{
}

If you run your application and click this first button, you will see a tree print in the text area, which is just about an exact replica of the original XAML (see Figure 28-10).

Figure 28-10. Viewing a logical tree at runtime

Programmatically Inspecting a Visual Tree
A Window’s visual tree can also be inspected at runtime using the VisualTreeHelper class of System. Windows.Media. Here is a Click implementation of the second Button control (btnShowVisualTree), which performs similar recursive logic to build a textual representation of the visual tree:

using System.Windows.Media;

private void btnShowVisualTree_Click(object sender, RoutedEventArgs e)
{
_dataToShow=""; BuildVisualTree(0, this); txtDisplayArea.Text=_dataToShow;
}
void BuildVisualTree(int depth, DependencyObject obj)
{
// Add the type name to the dataToShow member variable.
_dataToShow +=new string(' ', depth) + obj.GetType().Name + "\n";
// Make a recursive call for each visual child.
for (int i=0; i < VisualTreeHelper.GetChildrenCount(obj); i++) { BuildVisualTree(depth + 1, VisualTreeHelper.GetChild(obj, i)); } } As you can see in Figure 28-11, the visual tree exposes several lower-level rendering agents such as ContentPresenter, AdornerDecorator, TextBoxLineDrawingVisual, and so forth. Figure 28-11. Viewing a visual tree at runtime Programmatically Inspecting a Control’s Default Template Recall that a visual tree is used by WPF to understand how to render a Window and all contained elements. Every WPF control stores its own set of rendering commands within its default template. Programmatically speaking, any template can be represented as an instance of the ControlTemplate class. As well, you can obtain a control’s default template by using the aptly named Template property, like so: // Get the default template of the Button. Button myBtn=new Button(); ControlTemplate template=myBtn.Template; Likewise, you could create a new ControlTemplate object in code and plug it into a control’s Template property as follows: // Plug in a new template for the button to use. Button myBtn=new Button(); ControlTemplate customTemplate=new ControlTemplate(); // Assume this method adds all the code for a star template. MakeStarTemplate(customTemplate); myBtn.Template=customTemplate; While you could build a new template in code, it is far more common to do so in XAML. However, before you start building your own templates, let’s finish the current example and add the ability to view the default template of a WPF control at runtime. This can be a useful way to look at the overall composition of a template. Update the markup of your window with a new StackPanel of controls docked to the left side of the master DockPanel, defined as so (placed just before the element):

Add an empty event handler function for the btnTemplate_Click() event like this:

private void btnTemplate_Click( object sender, RoutedEventArgs e)
{
}

The upper-left text area allows you to enter in the fully qualified name of a WPF control located in the PresentationFramework.dll assembly. Once the library is loaded, you will dynamically create an instance of the object and display it in the large square in the bottom left. Finally, the control’s default template will be displayed in the right-hand text area. First, add a new member variable to your C# class of type Control, like so:

private Control _ctrlToExamine=null;

Here is the remaining code, which will require you to import the System.Reflection, System.Xml, and
System.Windows.Markup namespaces:

private void btnTemplate_Click( object sender, RoutedEventArgs e)
{
_dataToShow="";
ShowTemplate();
txtDisplayArea.Text=_dataToShow;
}

private void ShowTemplate()
{
// Remove the control that is currently in the preview area. if (_ctrlToExamine !=null)
stackTemplatePanel.Children.Remove(_ctrlToExamine); try
{
// Load PresentationFramework, and create an instance of the
// specified control. Give it a size for display purposes, then add to the
// empty StackPanel.
Assembly asm=Assembly.Load("PresentationFramework, Version=4.0.0.0," + "Culture=neutral, PublicKeyToken=31bf3856ad364e35");
_ctrlToExamine=(Control)asm.CreateInstance(txtFullName.Text);
_ctrlToExamine.Height=200;
_ctrlToExamine.Width=200;
_ctrlToExamine.Margin=new Thickness(5); stackTemplatePanel.Children.Add(_ctrlToExamine);
// Define some XML settings to preserve indentation.
var xmlSettings=new XmlWriterSettings{Indent=true};
// Create a StringBuilder to hold the XAML.
var strBuilder=new StringBuilder();
// Create an XmlWriter based on our settings.
var xWriter=XmlWriter.Create(strBuilder, xmlSettings);
// Now save the XAML into the XmlWriter object based on the ControlTemplate.
XamlWriter.Save(_ctrlToExamine.Template, xWriter);
// Display XAML in the text box.
_dataToShow=strBuilder.ToString();
}
catch (Exception ex)
{
_dataToShow=ex.Message;
}
}

The bulk of the work is just tinkering with the compiled BAML resource to map it into a XAML string. Figure 28-12 shows your final application in action, displaying the default template of the System.Windows. Controls.DatePicker control. The image shows the Calendar, which is accessed by clicking the button on the right side of the control.

Figure 28-12. Investigating a ControlTemplate at runtime

Great! You should have a better idea about how logical trees, visual trees, and control default templates work together. Now you can spend the remainder of this chapter learning how to build custom templates and user controls.

Building a Control Template with the Trigger Framework
When you build a custom template for a control, you could do so with nothing but C# code. Using this approach, you would add data to a ControlTemplate object and then assign it to a control’s Template property. Most of the time, however, you will define the look and feel of a ControlTemplate using XAML and add bits of code (or possibly quite a bit of code) to drive the runtime behavior.
In the remainder of this chapter, you will examine how to build custom templates using Visual Studio. Along the way, you will learn about the WPF trigger framework and the Visual State Manager (VSM), and you will see how to use animations to incorporate visual cues for the end user. Using Visual Studio alone to build complex templates can entail a fair amount of typing and a bit of heavy lifting. To be sure, production- level templates will benefit from the use of Blend for Visual Studio, the (now) free companion application installed with Visual Studio. However, given that this edition of the text does not include coverage of Blend, it is time to roll up your sleeves and pound out some markup.
To begin, create a new WPF application named ButtonTemplate. For this project, you are more interested in the mechanics of creating and using templates, so replace the Grid with the following markup:

In the Click event handler, simply display a message box (via MessageBox.Show()) to show a message confirming the clicking of the control. Remember, when you build custom templates, the behavior of the control is constant, but the look may vary.
Currently, this Button is rendered using the default template, which, as the previous example illustrated, is a BAML resource within a given WPF assembly. When you want to define your own template, you essentially replace this default visual tree with your own creation. To begin, update the definition of the

element to specify a new template using the property-element syntax. This template will give the control a round appearance.

Here, you have defined a template that consists of a named Grid control containing a named Ellipse and a Label. Because your Grid has no defined rows or columns, each child stacks on top of the previous control, which centers the content. If you run your application now, you will notice that the Click event will fire only when the mouse cursor is within the bounds of the Ellipse! This is a great feature of the WPF template architecture: you do not need to recalculate hit-testing, bounds checking, or any other low-level
detail. So, if your template used a Polygon object to render some oddball geometry, you can rest assured that the mouse hit-testing details are relative to the shape of the control, not the larger bounding rectangle.

Templates as Resources
Currently, your template is embedded to a specific Button control, which limits reuse. Ideally, you would place your template into a resource dictionary so you can reuse your round button template between projects or, at minimum, move it into the application resource container for reuse within this project. Let’s move the local Button resource to the application level by cutting the template definition from the Button and pasting it into the Application.Resources tag in the App.xaml file. Add in a Key and a TargetType, as follows:

Update the Button markup to the following:

Now, because this resource is available for the entire application, you can define any number of round buttons just by simply applying the template. Create two additional Button controls that use this template for testing purposes (no need to handle the Click event for these new items).

Incorporating Visual Cues Using Triggers
When you define a custom template, the visual cues of the default template are removed as well. For example, the default button template contains markup that informs the control how to look when certain UI events occur, such as when it receives focus, when it is clicked with the mouse, when it is enabled (or disabled), and so on. Users are quite accustomed to these sorts of visual cues because it gives the control somewhat of a tactile response. However, your RoundButtonTemplate does not define any such markup, so the look of the control is identical regardless of the mouse activity. Ideally, your control should look slightly different when clicked (maybe via a color change or drop shadow) to let the user know the visual state has changed.
This can be done using triggers, as you have already learned. For simple operations, triggers work perfectly well. There are additional ways to do this that are beyond the scope of this book, but there is more information available at https://docs.microsoft.com/en-us/dotnet/desktop-wpf/themes/how-to- create-apply-template.
By way of example, update your RoundButtonTemplate with the following markup, which adds two
triggers. The first will change the color of the control to blue and the foreground color to yellow when the mouse is over the surface. The second shrinks the size of the Grid (and, therefore, all child elements) when the control is pressed via the mouse.

The Role of the {TemplateBinding} Markup Extension
The problem with the control template is that each of the buttons looks and says the same thing. Updating the markup to the following has no effect:

This is because the control’s default properties (such as BackGround and Content) are overridden in the template. To enable them, they must be mapped to the related properties in the template. You can solve these issues by using the {TemplateBinding} markup extension when you build your template. This allows
you to capture property settings defined by the control using your template and use them to set values in the template itself.
Here is a reworked version of RoundButtonTemplate, which now uses this markup extension to map the Background property of the Button to the Fill property of the Ellipse; it also makes sure the Content of the Button is indeed passed to the Content property of the Label:

With this update, you can now create buttons of various colors and textual values. Figure 28-13 shows the result of the updated XAML.

Figure 28-13. Template bindings allow values to pass through to the internal controls.

The Role of ContentPresenter
When you designed your template, you used a Label to display the textual value of the control. Like the Button, the Label supports a Content property. Therefore, given your use of {TemplateBinding}, you could define a Button that contains complex content beyond that of a simple string.
However, what if you need to pass in complex content to a template member that does not have a Content property? When you want to define a generalized content display area in a template, you can use the ContentPresenter class as opposed to a specific type of control (Label or TextBlock). There is no need to do so for this example; however, here is some simple markup that illustrates how you could build a custom template that uses ContentPresenter to show the value of the Content property of the control using the template:

Incorporating Templates into Styles
Currently, your template simply defines a basic look and feel of the Button control. However, the process of establishing the basic properties of the control (content, font size, font weight, etc.) is the responsibility of the Button itself.

If you want, you could establish these values in the template. By doing so, you can effectively create a default look and feel. As you might have already realized, this is a job for WPF styles. When you build a style (to account for basic property settings), you can define a template within the style! Here is your updated application resource in the application resources in App.xaml, which has been rekeyed as RoundButtonStyle:

With this update, you can now create button controls by setting the Style property as so:

While the rendering and behavior of the button are identical, the benefit of nesting templates within styles is that you can provide a canned set of values for common properties. That wraps up your look at how to use Visual Studio and the trigger framework to build custom templates for a control. While there is still much more about the Windows Presentation Foundation API than has been examined here, you should be in a solid position for further study.

Summary
The first part of this chapter examined the resource management system of WPF. You began by looking at how to work with binary resources, and then you examined the role of object resources. As you learned, object resources are named blobs of XAML that can be stored at various locations to reuse content.
Next, you learned about WPF’s animation framework. Here you had a chance to create some animations using C# code, as well as with XAML. You learned that if you define an animation in markup, you use
elements and triggers to control execution. You then looked at the WPF-style mechanism, which makes heavy use of graphics, object resources, and animations.
You examined the relationship between a logical tree and a visual tree. The logical tree is basically a one- to-one correspondence of the markup you author to describe a WPF root element. Behind this logical tree is a much deeper visual tree that contains detailed rendering instructions.
The role of a default template was then examined. Remember, when you are building custom templates, you are essentially ripping out all (or part) of a control’s visual tree and replacing it with your own custom implementation.

CHAPTER 27

WPF Graphics Rendering Services

In this chapter, you’ll examine the graphical rendering capabilities of WPF. As you’ll see, WPF provides three separate ways to render graphical data: shapes, drawings, and visuals. After you understand the pros and cons of each approach, you will start learning about the world of interactive 2D graphics using the classes within System.Windows.Shapes. After this, you’ll see how drawings and geometries allow you to render 2D data in a more lightweight manner. Finally, you’ll learn how the visual layer gives you the greatest level of power and performance.
Along the way, you will explore several related topics, such as how to create custom brushes and pens, how to apply graphical transformations to your renderings, and how to perform hit-test operations. You’ll see how the integrated tools of Visual Studio and an additional tool named Inkscape can simplify your graphical coding endeavors.

■Note Graphics are a key aspect of WPF development. Even if you are not building a graphics-heavy application (such as a video game or multimedia application), the topics in this chapter are critical when you work with services such as control templates, animations, and data-binding customization.

Understanding WPF’s Graphical Rendering Services
WPF uses a particular flavor of graphical rendering that goes by the term retained-mode graphics. Simply put, this means that since you are using XAML or procedural code to generate graphical renderings, it is the responsibility of WPF to persist these visual items and ensure that they are correctly redrawn and refreshed in an optimal manner. Thus, when you render graphical data, it is always present, even when the end user hides the image by resizing or minimizing the window, by covering the window with another, and so forth.
In stark contrast, previous Microsoft graphical rendering APIs (including Windows Forms’ GDI+) were immediate-mode graphical systems. In this model, it was up to the programmer to ensure that rendered visuals were correctly “remembered” and updated during the life of the application. For example, in a Windows Forms application, rendering a shape such as a rectangle involved handling the Paint event (or overriding the virtual OnPaint() method), obtaining a Graphics object to draw the rectangle, and, most important, adding the infrastructure to ensure that the image was persisted when the user resized the window (e.g., creating member variables to represent the position of the rectangle and calling Invalidate() throughout your program).
The shift from immediate-mode to retained-mode graphics is indeed a good thing, as programmers have far less grungy graphics code to author and maintain. However, I’m not suggesting that the WPF graphics API is completely different from earlier rendering toolkits. For example, like GDI+, WPF supports various brush types and pen objects, techniques for hit-testing, clipping regions, graphical transformations,

© Andrew Troelsen, Phil Japikse 2022
A. Troelsen and P. Japikse, Pro C# 10 with .NET 6, https://doi.org/10.1007/978-1-4842-7869-7_27

1197

and so on. So, if you currently have a background in GDI+ (or C/C++-based GDI), you already know a good deal about how to perform basic renderings under WPF.

WPF Graphical Rendering Options
As with other aspects of WPF development, you have a number of choices regarding how to perform your graphical rendering, beyond the decision to do so via XAML or procedural C# code (or perhaps a
combination of both). Specifically, WPF provides the following three distinct ways to render graphical data:
•Shapes: WPF provides the System.Windows.Shapes namespace, which defines a small number of classes for rendering 2D geometric objects (rectangles, ellipses, polygons, etc.). While these types are simple to use and powerful, they do come with a fair amount of memory overhead if used with reckless abandon.
•Drawings and geometries: The WPF API provides a second way to render graphical data, using descendants from the System.Windows.Media.Drawing abstract class. Using classes such as GeometryDrawing or ImageDrawing (in addition to various geometry objects), you can render graphical data in a more lightweight (but less feature-rich) manner.
•Visuals: The fastest and most lightweight way to render graphical data under WPF is using the visual layer, which is accessible only through C# code. Using descendants of System.Windows.Media.Visual, you can speak directly to the WPF graphical subsystem.
The reason for offering different ways to do the same thing (i.e., render graphical data) has to do with memory use and, ultimately, application performance. Because WPF is such a graphically intensive
system, it is not unreasonable for an application to render hundreds or even thousands of different images on a window’s surface, and the choice of implementation (shapes, drawings, or visuals) could have a
huge impact.
Do understand that when you build a WPF application, chances are good you’ll use all three options. As a rule of thumb, if you need a modest amount of interactive graphical data that can be manipulated by the user (receive mouse input, display tooltips, etc.), you’ll want to use members in the System.Windows.Shapes namespace.
In contrast, drawings and geometries are more appropriate when you need to model complex, generally noninteractive, vector-based graphical data using XAML or C#. While drawings and geometries can still respond to mouse events, hit-testing, and drag-and-drop operations, you will typically need to author more code to do so.
Last but not least, if you require the fastest possible way to render massive amounts of graphical data, the visual layer is the way to go. For example, let’s say you are using WPF to build a scientific application that can plot out thousands of points of data. Using the visual layer, you can render the plot points in the most optimal way possible. As you will see later in this chapter, the visual layer is accessible only via C# code and is not XAML-friendly.
No matter which approach you take (shapes, drawings and geometries, or visuals), you will make use of common graphical primitives such as brushes (which fill interiors), pens (which draw exteriors), and transformation objects (which, well, transform the data). To begin the journey, you will start working with the classes of System.Windows.Shapes.

■Note WPF also ships with a full-blown API that can be used to render and manipulate 3D graphics, which is not addressed in this text.

Rendering Graphical Data Using Shapes
Members of the System.Windows.Shapes namespace provide the most straightforward, most interactive, yet most memory-intensive way to render a two-dimensional image. This namespace (defined in the PresentationFramework.dll assembly) is quite small and consists of only six sealed classes that extend the abstract Shape base class: Ellipse, Rectangle, Line, Polygon, Polyline, and Path.
The abstract Shape class inherits from FrameworkElement, which inherits from UIElement. These classes define members to deal with sizing, tooltips, mouse cursors, and whatnot. Given this inheritance chain, when you render graphical data using Shape-derived classes, the objects are just about as functional (as far as user interactivity is concerned) as a WPF control!
For example, determining whether the user has clicked your rendered image is no more complicated than handling the MouseDown event. By way of a simple example, if you authored this XAML of a Rectangle object in the Grid of your initial Window:

you could implement a C# event handler for the MouseDown event that changes the rectangle’s background color when clicked, like so:

private void myRect_MouseDown(object sender, MouseButtonEventArgs e)
{
// Change color of Rectangle when clicked. myRect.Fill = Brushes.Pink;
}

Unlike with other graphical toolkits you may have used, you do not need to author a ton of infrastructure code that manually maps mouse coordinates to the geometry, manually calculates hit-testing, renders to an off-screen buffer, and so forth. The members of System.Windows.Shapes simply respond to the events you register with, just like a typical WPF control (e.g., Button, etc.).
The downside of all this out-of-the-box functionality is that the shapes do take up a fair amount of memory. If you’re building a scientific application that plots thousands of points on the screen, using shapes would be a poor choice (essentially, it would be about as memory intensive as rendering thousands of Button objects!). However, when you need to generate an interactive 2D vector image, shapes are a wonderful choice.
Beyond the functionality inherited from the UIElement and FrameworkElement parent classes, Shape
defines a number of members for each of the children; Table 27-1 shows some of the more useful ones.

Table 27-1. Key Properties of the Shape Base Class

Properties Meaning in Life
DefiningGeometry Returns a Geometry object that represents the overall dimensions of the current shape. This object contains only the plot points that are used to render the data and has no trace of the functionality from UIElement or FrameworkElement.
Fill Allows you to specify a brush object to fill the interior portion of a shape.
GeometryTransform Allows you to apply transformations to a shape before it is rendered on the screen. The inherited RenderTransform property (from UIElement) applies the transformation after it has been rendered on the screen.
(continued)

Table 27-1. (continued)

Properties Meaning in Life
Stretch Describes how to fill a shape within its allocated space, such as its position within a layout manager. This is controlled using the corresponding System. Windows.Media.Stretch enumeration.
Stroke Defines a brush object or, in some cases, a pen object (which is really a brush in disguise) that is used to paint the border of a shape.
StrokeDashArray, StrokeEndLineCap, StrokeStartLineCap, StrokeThickness These (and other) stroke-related properties control how lines are configured when drawing the border of a shape. In a majority of cases, these properties will configure the brush used to draw a border or line.

■Note If you forget to set the Fill and Stroke properties, WPF will give you “invisible” brushes, and, therefore, the shape will not be visible on the screen!

Adding Rectangles, Ellipses, and Lines to a Canvas
You will build a WPF application that can render shapes using XAML and C# and, while doing so, learn a bit about the process of hit-testing. Create a new WPF application named RenderingWithShapes and change the title of MainWindow.xaml to “Fun with Shapes!” Then update the initial XAML of the , replacing the Grid with a containing a (now empty) and a . Note that each contained item has a fitting name via the Name property.

Now, populate the with a set of objects, each of which contains a specific Shape-derived class as content. Notice that each is assigned to the same GroupName (to ensure mutual exclusivity) and is also given a fitting name.

As you can see, declaring Rectangle, Ellipse, and Line objects in XAML is quite straightforward and requires little comment. Recall that the Fill property is used to specify a brush to paint the interior of a shape. When you require a solid-colored brush, just specify a hard-coded string of known values, and the underlying type converter will generate the correct object. One interesting feature of the Rectangle type is that it defines RadiusX and RadiusY properties to allow you to render curved corners.
Line represents its starting and ending points using the X1, X2, Y1, and Y2 properties (given that height and width make little sense when describing a line). Here you are setting up a few additional properties that control how to render the starting and ending points of the Line, as well as how to configure the stroke settings. Figure 27-1 shows the rendered toolbar, as seen through the Visual Studio WPF designer.

Figure 27-1. Using Shapes as content for a set of RadioButtons

Now, using the Properties window of Visual Studio, handle the MouseLeftButtonDown event for the Canvas, and handle the Click event for each RadioButton. In your C# file, your goal is to render the selected shape (a circle, square, or line) when the user clicks within the Canvas. First, define the following nested enum (and corresponding member variable) within your Window-derived class:

public partial class MainWindow : Window
{
private enum SelectedShape
{ Circle, Rectangle, Line }
private SelectedShape _currentShape;
}

Within each Click event handler, set the currentShape member variable to the correct SelectedShape
value, as follows:

private void CircleOption_Click(object sender, RoutedEventArgs e)
{
_currentShape = SelectedShape.Circle;
}

private void RectOption_Click(object sender, RoutedEventArgs e)
{
_currentShape = SelectedShape.Rectangle;
}

private void LineOption_Click(object sender, RoutedEventArgs e)
{
_currentShape = SelectedShape.Line;
}

With the MouseLeftButtonDown event handler of the Canvas, you will render out the correct shape (of a predefined size), using the X,Y position of the mouse cursor as a starting point. Here is the complete implementation, with analysis to follow:

private void CanvasDrawingArea_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)
{
Shape shapeToRender = null;
// Configure the correct shape to draw. switch (_currentShape)
{
case SelectedShape.Circle:
shapeToRender = new Ellipse() { Fill = Brushes.Green, Height = 35, Width = 35 }; break;
case SelectedShape.Rectangle:
shapeToRender = new Rectangle()
{ Fill = Brushes.Red, Height = 35, Width = 35, RadiusX = 10, RadiusY = 10 }; break;
case SelectedShape.Line: shapeToRender = new Line()
{
Stroke = Brushes.Blue, StrokeThickness = 10,
X1 = 0, X2 = 50, Y1 = 0, Y2 = 50,
StrokeStartLineCap= PenLineCap.Triangle, StrokeEndLineCap = PenLineCap.Round
};
break; default:
return;
}
// Set top/left position to draw in the canvas. Canvas.SetLeft(shapeToRender, e.GetPosition(canvasDrawingArea).X); Canvas.SetTop(shapeToRender, e.GetPosition(canvasDrawingArea).Y);
// Draw shape!
canvasDrawingArea.Children.Add(shapeToRender);
}

■Note You might notice that the Ellipse, Rectangle, and Line objects being created in this method have the same property settings as the corresponding XAML definitions! As you might hope, you can streamline this code, but that requires an understanding of the WPF object resources, which you will examine in Chapter 28.

As you can see, you are testing the currentShape member variable to create the correct Shape- derived object. After this point, you set the top-left value within the Canvas using the incoming MouseButtonEventArgs. Last but not least, you add the new Shape-derived type to the collection of UIElement objects maintained by the Canvas. If you run your program now, you should be able to click anywhere in the canvas and see the selected shape rendered at the location of the left mouse-click.

Removing Rectangles, Ellipses, and Lines from a Canvas
With the Canvas maintaining a collection of objects, you might wonder how you can dynamically remove an item, perhaps in response to the user right-clicking a shape. You can certainly do this using a class in the
System.Windows.Media namespace called the VisualTreeHelper. Chapter 28 will explain the roles of “visual trees” and “logical trees” in some detail. Until then, you can handle the MouseRightButtonDown event on your Canvas object and implement the corresponding event handler like so:

private void CanvasDrawingArea_MouseRightButtonDown(object sender, MouseButtonEventArgs e)
{
// First, get the X,Y location of where the user clicked. Point pt = e.GetPosition((Canvas)sender);
// Use the HitTest() method of VisualTreeHelper to see if the user clicked
// on an item in the canvas.
HitTestResult result = VisualTreeHelper.HitTest(canvasDrawingArea, pt);
// If the result is not null, they DID click on a shape! if (result != null)
{
// Get the underlying shape clicked on, and remove it from
// the canvas. canvasDrawingArea.Children.Remove(result.VisualHit as Shape);
}
}

This method begins by obtaining the exact X,Y location the user clicked in the Canvas and performs a hit-test operation via the static VisualTreeHelper.HitTest() method. The return value, a HitTestResult object, will be set to null if the user does not click a UIElement within the Canvas. If HitTestResult is not null, you can obtain the underlying UIElement that was clicked via the VisualHit property, which you are casting into a Shape-derived object (remember, a Canvas can hold any UIElement, not just shapes!). Again, you’ll get more details on exactly what a “visual tree” is in the next chapter.

■Note By default, VisualTreeHelper.HitTest() returns the topmost UIElement clicked and does not provide information on other objects below that item (e.g., objects overlapping by Z-order).

With this modification, you should be able to add a shape to the canvas with a left mouse-click and delete an item from the canvas with a right mouse-click!
So far, so good. At this point, you have used Shape-derived objects to render content on RadioButtons using XAML and populated a Canvas using C#. You will add a bit more functionality to this example when you examine the role of brushes and graphical transformations. On a related note, a different example in this chapter will illustrate drag-and-drop techniques on UIElement objects. Until then, let’s examine the remaining members of System.Windows.Shapes.

Working with Polylines and Polygons
The current example used only three of the Shape-derived classes. The remaining child classes (Polyline, Polygon, and Path) are extremely tedious to render correctly without tool support (such as Microsoft Blend, the companion tool for Visual Studio designed for WPF developers, or other tools that can create vector graphics) simply because they require a large number of plot points to represent their output. Here is an overview of the remaining Shapes types.

The Polyline type lets you define a collection of (x, y) coordinates (via the Points property) to draw a series of line segments that do not require connecting ends. The Polygon type is similar; however, it is
programmed so that it will always close the starting and ending points and fill the interior with the specified brush. Assume you have authored the following in the Kaxaml editor:

Figure 27-2 shows the rendered output in Kaxaml.

Figure 27-2. Polygons and polylines

Working with Paths
Using the Rectangle, Ellipse, Polygon, Polyline, and Line types alone to draw a detailed 2D vector image would be extremely complex, as these primitives do not allow you to easily capture graphical data such as curves, unions of overlapping data, and so forth. The final Shape-derived class, Path, provides the ability
to define complex 2D graphical data represented as a collection of independent geometries. After you have defined a collection of such geometries, you can assign them to the Data property of the Path class, where this information will be used to render your complex 2D image.
The Data property takes a System.Windows.Media.Geometry-derived class, which contains the key members described in Table 27-2.

Table 27-2. Select Members of the System.Windows.Media.Geometry Type

Member Meaning in Life
Bounds Establishes the current bounding rectangle containing the geometry.
FillContains() Determines whether a given Point (or other Geometry object) is within the bounds of a particular Geometry-derived class. This is useful for hit-testing calculations.
GetArea() Returns the entire area that a Geometry-derived type occupies.
GetRenderBounds() Returns a Rect that contains the smallest possible rectangle that could be used to render the Geometry-derived class.
Transform Assigns a Transform object to the geometry to alter the rendering.

The classes that extend Geometry (see Table 27-3) look very much like their Shape-derived counterparts.
For example, EllipseGeometry has similar members to Ellipse. The big distinction is that Geometry- derived classes do not know how to render themselves directly because they are not UIElements. Rather, Geometry-derived classes represent little more than a collection of plot-point data, which say in effect “If a Path uses my data, this is how I would render myself.”

Table 27-3. Geometry-Derived Classes

Geometry Class Meaning in Life
LineGeometry Represents a straight line
RectangleGeometry Represents a rectangle
EllipseGeometry Represents an ellipse
GeometryGroup Allows you to group several Geometry objects
CombinedGeometry Allows you to merge two different Geometry objects into a single shape
PathGeometry Represents a figure composed of lines and curves

■Note Path is not the only class in WPF that can use a collection of geometries. For example, DoubleAnimationUsingPath, DrawingGroup, GeometryDrawing, and even UIElement can all use geometries for rendering, using the PathGeometry, ClipGeometry, Geometry, and Clip properties, respectively.

The following is a Path that makes use of a few Geometry-derived types. Notice that you are setting the Data property of Path to a GeometryGroup object that contains other Geometry-derived objects such as EllipseGeometry, RectangleGeometry, and LineGeometry. Figure 27-3 shows the output.

Figure 27-3. A Path containing various Geometry objects

The image in Figure 27-3 could have been rendered using the Line, Ellipse, and Rectangle classes shown earlier. However, this would have put various UIElement objects in memory. When you use geometries to model the plot points of what to draw and then place the geometry collection into a container that can render the data (Path, in this case), you reduce the memory overhead.
Now recall that Path has the same inheritance chain as any other member of System.Windows.Shapes and therefore can send the same event notifications as other UIElement objects. Thus, if you were to define this same element in a Visual Studio project, you could determine whether the user clicked
anywhere in the sweeping line simply by handling a mouse event (remember, Kaxaml does not allow you to handle events for the markup you have authored).

The Path Modeling “Mini-Language”
Of all the classes listed in Table 27-3, PathGeometry is the most complex to configure in terms of XAML or code. This has to do with the fact that each segment of the PathGeometry is composed of objects that
contain various segments and figures (e.g., ArcSegment, BezierSegment, LineSegment, PolyBezierSegment, PolyLineSegment, PolyQuadraticBezierSegment, etc.). Here is an example of a Path object whose Data property has been set to a composed of various figures and segments:

Now, to be perfectly honest, few programmers will ever need to manually build complex 2D images by directly describing Geometry- or PathSegment-derived classes. Later in this chapter, you will learn how to convert vector graphics into path statements that can be used in XAML.
Even with the assistance of these tools, the amount of XAML required to define a complex Path object would be ghastly, as the data consists of full descriptions of various Geometry- or PathSegment-derived classes. To produce more concise and compact markup, the Path class has been designed to understand a specialized “mini-language.”
For example, rather than setting the Data property of Path to a collection of Geometry- and
PathSegment-derived types, you can set the Data property to a single string literal containing a number of

known symbols and various values that define the shape to be rendered. Here is a simple example, and the resulting output is shown in Figure 27-4:

Figure 27-4. The Path mini-language allows you to compactly describe a Geometry/PathSegment object model

The M command (short for move) takes an X,Y position that represents the starting point of the drawing.
The C command takes a series of plot points to render a curve (a cubic Bézier curve to be exact), while H
draws a horizontal line.
Now, to be perfectly honest, the chances that you will ever need to manually build or parse a string literal containing Path mini-language instructions are slim to none. However, at the least, you will no longer be surprised when you view XAML-generated dedicated tools.

WPF Brushes and Pens
Each of the WPF graphical rendering options (shape, drawing and geometries, and visuals) makes extensive use of brushes, which allow you to control how the interior of a 2D surface is filled. WPF provides six different brush types, all of which extend System.Windows.Media.Brush. While Brush is abstract, the descendants described in Table 27-4 can be used to fill a region with just about any conceivable option.

Table 27-4. WPF Brush-Derived Types

Brush Type Meaning in Life

DrawingBrush Paints an area with a Drawing-derived object (GeometryDrawing, ImageDrawing, or VideoDrawing)
ImageBrush Paints an area with an image (represented by an ImageSource object)
LinearGradientBrush Paints an area with a linear gradient RadialGradientBrush Paints an area with a radial gradient SolidColorBrush Paints a single color, set with the Color property
VisualBrush Paints an area with a Visual-derived object (DrawingVisual, Viewport3DVisual, and ContainerVisual)

The DrawingBrush and VisualBrush classes allow you to build a brush based on an existing Drawing- or Visual-derived class. These brush classes are used when you are working with the other two graphical options of WPF (drawings or visuals) and will be examined later in this chapter.
ImageBrush, as the name suggests, lets you build a brush that displays image data from an external file or embedded application resource, by setting the ImageSource property. The remaining brush types (LinearGradientBrush and RadialGradientBrush) are quite straightforward to use, though typing in the
required XAML can be a tad verbose. Thankfully, Visual Studio supports integrated brush editors that make it simple to generate stylized brushes.

Configuring Brushes Using Visual Studio
Let’s update your WPF drawing program, RenderingWithShapes, to use some more interesting brushes. The three shapes you have employed so far to render data on your toolbar use simple, solid colors, so you can capture their values using simple string literals. To spice things up a tad, you will now use the integrated brush editor. Ensure that the XAML editor of your initial window is the open window within the IDE and select the Ellipse element. Now, in the Properties window, locate the Brush category and then click Fill property listed on the top (see Figure 27-5).

Figure 27-5. Any property that requires a brush can be configured with the integrated brush editor

At the top of the Brushes editor, you will see a set of properties that are all “brush compatible” for the selected item (i.e., Fill, Stroke, and OpacityMask). Below this, you will see a series of tabs that allow you to configure different types of brushes, including the current solid color brush. You can use the color
selector tool, as well as the ARGB (alpha, red, green, and blue, where “alpha” controls transparency) editors to control the color of the current brush. Using these sliders and the related color selection area, you can create any sort of solid color. Use these tools to change the Fill color of your Ellipse and view the resulting XAML. You will notice the color is stored as a hexadecimal value, as follows:

More interestingly, this same editor allows you to configure gradient brushes, which are used to define a series of colors and transition points. Recall that this Brushes editor provides you with a set of tabs, the first of which lets you set a null brush for no rendered output. The other four allow you to set up a solid color brush (what you just examined), gradient brush, tile brush, or image brush.
Click the gradient brush button, and the editor will display a few new options (see Figure 27-6). The three buttons on the lower left allow you to pick a linear gradient, pick a radial gradient, or reverse the gradient stops. The bottommost strip will show you the current color of each gradient stop, each of which is marked by a “thumb” on the strip. As you drag these thumbs around the gradient strip, you can
control the gradient offset. Furthermore, when you click a given thumb, you can change the color for that particular gradient stop via the color selector. Finally, if you click directly on the gradient strip, you can add gradient stops.

Figure 27-6. The Visual Studio brush editor allows you to build basic gradient brushes

Take a few minutes to play around with this editor to build a radial gradient brush containing three gradient stops, set to your colors of choice. Figure 27-6 shows the brush you just constructed, using three different shades of green.
When you are done, the IDE will update your XAML with a custom brush, set to a brush-compatible property (the Fill property of the Ellipse in this example) using property-element syntax, as follows:

Configuring Brushes in Code
Now that you have built a custom brush for the XAML definition of your Ellipse, the corresponding C# code is out-of-date, in that it will still render a solid green circle. To sync things back up, update the correct case statement to use the same brush you just created. The following is the necessary update, which looks more complex than you might expect, just because you are converting the hexadecimal value to a proper Color object via the System.Windows.Media.ColorConverter class (see Figure 27-7 for the modified output):

case SelectedShape.Circle:
shapeToRender = new Ellipse() { Height = 35, Width = 35 };
// Make a RadialGradientBrush in code! RadialGradientBrush brush = new RadialGradientBrush(); brush.GradientStops.Add(new GradientStop(
(Color)ColorConverter.ConvertFromString("#FF77F177"), 0)); brush.GradientStops.Add(new GradientStop(
(Color)ColorConverter.ConvertFromString("#FF11E611"), 1)); brush.GradientStops.Add(new GradientStop(
(Color)ColorConverter.ConvertFromString("#FF5A8E5A"), 0.545)); shapeToRender.Fill = brush;
break;

Figure 27-7. Drawing circles with a bit more pizzazz

By the way, you can build GradientStop objects by specifying a simple color as the first constructor parameter using the Colors enumeration, which returns a configured Color object.

GradientStop g = new GradientStop(Colors.Aquamarine, 1);

Or, if you require even finer control, you can pass in a configured Color object, like so:

Color myColor = new Color() { R = 200, G = 100, B = 20, A = 40 }; GradientStop g = new GradientStop(myColor, 34);

Of course, the Colors enum and Color class are not limited to gradient brushes. You can use them anytime you need to represent a color value in code.

Configuring Pens
In comparison with brushes, a pen is an object for drawing borders of geometries or, in the case of the Line or PolyLine class, the line geometry itself. Specifically, the Pen class allows you to draw a specified thickness, represented by a double value. In addition, a Pen can be configured with the same sort of properties seen in the Shape class, such as starting and stopping pen caps, dot-dash patterns, and so forth. For example, you can add the following markup to a shape to define the pen attributes:

In many cases, you won’t need to directly create a Pen object because this will be done indirectly when you assign a value to properties, such as StrokeThickness to a Shape-derived type (as well as other UIElements). However, building a custom Pen object is handy when working with Drawing-derived types (described later in the chapter). Visual Studio does not have a pen editor per se, but it does allow you to configure all the stroke-centric properties of a selected item using the Properties window.

Applying Graphical Transformations
To wrap up the discussion of using shapes, let’s address the topic of transformations. WPF ships with numerous classes that extend the System.Windows.Media.Transform abstract base class. Table 27-5 documents many of the key out-of-the-box Transform-derived classes.

Table 27-5. Key Descendants of the System.Windows.Media.Transform Type

Type Meaning in Life
MatrixTransform Creates an arbitrary matrix transformation that is used to manipulate objects or coordinate systems in a 2D plane
RotateTransform Rotates an object clockwise about a specified point in a 2D (x, y) coordinate system
ScaleTransform Scales an object in the 2D (x, y) coordinate system
SkewTransform Skews an object in the 2D (x, y) coordinate system
TranslateTransform Translates (moves) an object in the 2D (x, y) coordinate system
TransformGroup Represents a composite Transform composed of other Transform objects

Transformations can be applied to any UIElement (e.g., descendants of Shape as well as controls such as Button controls, TextBox controls, and the like). Using these transformation classes, you can render graphical data at a given angle, skew the image across a surface, and expand, shrink, or flip the target item in a variety of ways.

■Note While transformation objects can be used anywhere, you will find them most useful when working with WPF animations and custom control templates. As you will see later in the chapter, you can use WPF animations to incorporate visual cues to the end user for a custom control.

Transformations (or a whole set of them) can be assigned to a target object (e.g., Button, Path, etc.) using two common properties, LayoutTransform and RenderTransform.
The LayoutTransform property is helpful, in that the transformation occurs before elements are rendered into a layout manager, and therefore the transformation will not affect Z-ordering operations (in other words, the transformed image data will not overlap).
The RenderTransform property, on the other hand, occurs after the items are in their container, and therefore it is quite possible that elements can be transformed in such a way that they could overlap each other, based on how they were arranged in the container.

A First Look at Transformations
You will add some transformational logic to your RenderingWithShapes project in just a moment. However, to see transformation objects in action, open Kaxaml and define a simple StackPanel in the root Page or Window and set the Orientation property to Horizontal. Now, add the following Rectangle, which will be drawn at a 45-degree angle using a RotateTransform object:

Here is a that is skewed across the surface by 20 degrees, using a :

And for good measure, here is an Ellipse that is scaled by 20 degrees with a ScaleTransform (note the values set to the initial Height and Width), as well as a TextBox that has a group of transformation objects applied to it:

Note that when a transformation is applied, you are not required to perform any manual calculations to correctly respond to hit-testing, input focus, or whatnot. The WPF graphics engine handles such tasks on your behalf. For example, in Figure 27-8, you can see that the TextBox is still responsive to keyboard input.

Figure 27-8. The results of graphical transformation objects

Transforming Your Canvas Data
Now, let’s incorporate some transformational logic into your RenderingWithShapes example. In addition to applying a transformation object to a single item (e.g., Rectangle, TextBox, etc.), you can also apply transformation objects to a layout manager to transform all of the internal data. You could, for example, render the entire DockPanel of the main window at an angle.

...

This is a bit extreme for this example, so let’s add a final (less aggressive) feature that allows the user to flip the entire Canvas and all contained graphics. Begin by adding a final ToggleButton to your ToolBar, defined as follows:

Within the Click event handler, create a RotateTransform object and connect it to the Canvas object via the LayoutTransform property if this new ToggleButton is clicked. If the ToggleButton is not clicked, remove the transformation by setting the same property to null.

private void FlipCanvas_Click(object sender, RoutedEventArgs e)
{
if (flipCanvas.IsChecked == true)
{
RotateTransform rotate = new RotateTransform(-180); canvasDrawingArea.LayoutTransform = rotate;
}
else
{
canvasDrawingArea.LayoutTransform = null;
}
}

Run your application and add a bunch of graphics throughout the canvas area, making sure to go edge to edge with them. If you click your new button, you will find that the shape data flows outside of the boundaries of the canvas! This is because you have not defined a clipping region (see Figure 27-9).

Figure 27-9. Oops! Your data is flowing outside of the canvas after the transformation!

Fixing this is trivial. Rather than manually authoring complex clipping-logic code, simply set the ClipToBounds property of the Canvas to true, which prevents child elements from being rendered outside the parent’s boundaries. If you run your program again, you’ll find the data will not bleed off the canvas boundary.

The last tiny modification to make has to do with the fact that when you flip the canvas by pressing your toggle button and then click the canvas to draw a new shape, the point at which you click is not the point where the graphical data is applied. Rather, the data is rendered above the mouse cursor.

To resolve this issue, apply the same transformation object to the shape being drawn before the rendering occurs (via RenderTransform). Here is the crux of the code:

private void CanvasDrawingArea_MouseLeftButtonDown(object sender, MouseButtonEventArgs e)
{
//omitted for brevity
if (flipCanvas.IsChecked == true)
{
RotateTransform rotate = new RotateTransform(-180); shapeToRender.RenderTransform = rotate;
}
// Set top/left to draw in the canvas. Canvas.SetLeft(shapeToRender,
e.GetPosition(canvasDrawingArea).X); Canvas.SetTop(shapeToRender,
e.GetPosition(canvasDrawingArea).Y);

// Draw shape! canvasDrawingArea.Children.Add(shapeToRender);
}

This wraps up your examination of System.Windows.Shapes, brushes, and transformations. Before looking at the role of rendering graphics using drawings and geometries, let’s see how Visual Studio can be used to simplify how you work with primitive graphics.

Working with the Visual Studio Transform Editor
In the previous example, you applied various transformations by manually entering markup and authoring some C# code. While this is certainly useful, you will be happy to know that the latest version of Visual Studio ships with an integrated transformation editor. Recall that any UI element can be the recipient of transformational services, including a layout system containing various UI elements. To illustrate the use of Visual Studio’s transform editor, create a new WPF application named FunWithTransforms.

Building the Initial Layout
First, split your initial Grid into two columns using the integrated grid editor (the exact size does not matter). Now, locate the StackPanel control within your Toolbox and add it to take up the entire space of the first column of the Grid; then add three Button controls to the StackPanel, like so:

Add the handlers for the buttons to the code page, like this:

private void Skew(object sender, RoutedEventArgs e)
{
}
private void Rotate(object sender, RoutedEventArgs e)
{
}
private void Flip(object sender, RoutedEventArgs e)
{
}

To finalize the UI, create a graphic of your choosing (using any of the techniques discussed in this chapter) defined in the second column of the Grid. The markup used in the sample is listed here:

Figure 27-10 shows the final layout for the example.

Figure 27-10. The layout of your transformation example

Applying Transformations at Design Time
As mentioned, Visual Studio provides an integrated Transform editor, which can be found in the Properties panel. Locate this area, and make sure you expand the Transform section to view the RenderTransform and LayoutTransform sections of the editor (see Figure 27-11).

Figure 27-11. The Transform editor

Similar to the Brushes section, the Transform section provides a number of tabs to configure various types of graphical transformation to the currently selected item. Table 27-6 describes each transformation option, listed in the order of evaluating each tab from left to right.

Table 27-6. Blend Transformation Options

Transformation
Option Meaning in Life
Translate Allows you to offset the location of an item on an X, Y position.
Rotate Allows you to rotate an item on a 360-degree angle.
Scale Allows you to grow or shrink an item by a factor in the X and Y directions.
Skew Allows you to skew the bounding box containing the selected item by a factor in the X and Y directions.
Center Point When you rotate or flip an object, the item moves relative to a fixed point, called the object’s center point. By default, an object’s center point is located at the object’s center; however, this transformation allows you to change an object’s center point to rotate or flip the object around a different point.
Flip Flips a selected item based on an X or Y center point.

I suggest you test each of these transformations using your custom shape as a target (just press Ctrl+Z to undo the previous operation). Like many other aspects of the Transform Properties panel, each transformation section has a unique set of configuration options, which should become fairly understandable as you tinker. For example, the Skew transform editor allows you to set the X and Y skew values, the Flip transform editor allows you to flip on the x- or y-axis, and so forth.

Transforming the Canvas in Code
The implementation of each Click event handler will be more or less the same. You will configure a transformation object and assign it to the myCanvas object. Then, when you run the application, you can click a button to see the result of the applied transformation. Here is the complete code for each event handler (notice that you are setting the LayoutTransform property, so the shape data remains positioned relative to the parent container):

private void Flip(object sender, System.Windows.RoutedEventArgs e)
{
myCanvas.LayoutTransform = new ScaleTransform(-1, 1);
}

private void Rotate(object sender, System.Windows.RoutedEventArgs e)
{
myCanvas.LayoutTransform = new RotateTransform(180);
}

private void Skew(object sender, System.Windows.RoutedEventArgs e)
{
myCanvas.LayoutTransform = new SkewTransform(40, -20);
}

Rendering Graphical Data Using Drawings and Geometries
While the Shape types allow you to generate any sort of interactive two-dimensional surface, they entail quite a bit of memory overhead due to their rich inheritance chain. And though the Path class can help remove some of this overhead using contained geometries (rather than a large collection of other shapes), WPF provides a sophisticated drawing and geometry programming interface that renders even more lightweight 2D vector images.
The entry point into this API is the abstract System.Windows.Media.Drawing class (in PresentationCore.dll), which on its own does little more than define a bounding rectangle to hold the rendering. The Drawing class is significantly more lightweight than Shape, given that neither UIElement nor FrameworkElement is in the inheritance chain.
WPF provides various classes that extend Drawing, each of which represents a particular way of drawing the content, as described in Table 27-7.

Table 27-7. WPF Drawing-Derived Types

Type Meaning in Life
DrawingGroup Used to combine a collection of separate Drawing-derived objects into a single composite rendering.
GeometryDrawing Used to render 2D shapes in a very lightweight manner.
GlyphRunDrawing Used to render textual data using WPF graphical rendering services.
ImageDrawing Used to render an image file, or geometry set, into a bounding rectangle.
VideoDrawing Used to play an audio file or video file. This type can only be fully exploited using procedural code. If you would like to play videos via XAML, the MediaPlayer type is a better choice.

Because they are more lightweight, Drawing-derived types do not have intrinsic support for handling input events, as they are not UIElements or FrameworkElements (although it is possible to programmatically perform hit-testing logic).
Another key difference between Drawing-derived types and Shape-derived types is that Drawing-derived types have no ability to render themselves, as they do not derive from UIElement! Rather, derived types must be placed within a hosting object (specifically, DrawingImage, DrawingBrush, or DrawingVisual) to display their content.
DrawingImage allows you to place drawing and geometries inside a WPF Image control, which typically is used to display data from an external file. DrawingBrush allows you to build a brush based on a drawing and its geometries to set a property that requires a brush. Finally, DrawingVisual is used only in the “visual” layer of graphical rendering, which is driven completely via C# code.
Although using drawings is a bit more complex than using simple shapes, this decoupling of graphical composition from graphical rendering makes the Drawing-derived types much more lightweight than the Shape-derived types while still retaining key services.

Building a DrawingBrush Using Geometries
Earlier in this chapter, you filled a Path with a group of geometries, like so:

By doing this, you gain interactivity from Path but are still fairly lightweight given your geometries.
However, if you want to render the same output and have no need for any (out-of-the-box) interactivity, you can place the same inside a DrawingBrush, like this:

When you place a group of geometries into a DrawingBrush, you also need to establish the Pen object used to draw the boundaries because you no longer inherit a Stroke property from the Shape base class. Here, you created a with the same settings used in the Stroke and StrokeThickness values of the previous Path example.
Furthermore, since you no longer inherit a Fill property from Shape, you also need to use property- element syntax to define a brush object to use for the , which here is a solid-colored orange brush, just like the previous Path settings.

Painting with the DrawingBrush
Now that you have a DrawingBrush, you can use it to set the value of any property requiring a brush object. For example, if you are authoring this markup in Kaxaml, you could use property-element syntax to paint your drawing over the entire surface of a Page, like so:

Or you can use this to set a different brush-compatible property, such as the
Background property of a Button.