Introducing ASP.NET Core 2.0

Editor's Notes

• #15: Almost all ASP.NET apps use a standard Startup class to configure how the app will work. ASP.NET Core apps run inside of a web host, and even before Startup is called, a WebHostBuilder is used to create a host that then runs.
• #16: Most ASP.NET Core project templates include a Program.cs file, which holds a public static void Main entry point for the app. It’s where the web host is built and run. You don’t actually need a Startup class at all to create an ASP.NET Core app – you can perform all of the configuration inside of WebHostBuilder if you want.
• #18: Using WebHostBuilder, which isn’t strictly required.
• #21: Almost all ASP.NET apps use a standard Startup class to configure how the app will work. ASP.NET Core apps run inside of a web host, and even before Startup is called, a WebHostBuilder is used to create a host that then runs.
• #27: Using the built-in container…
• #28: Note that Startup is not a strongly typed contract. Methods can have arbitrary signatures and some support different return types.
• #30: Logging is no longer done here. Data seeding should not be done here, since migrations run after this.
• #31: Your ASP.NET Core app’s request pipeline is composed of components called middleware. ASP.NET Core ships with a bunch of useful middleware that your apps can use, and it’s pretty straightforward to create your own.
• #38: For most apps, you won’t have to write any middleware yourself. You’ll probably use a higher-level framework, like MVC, and some of the built-in middleware that ships with ASP.NET Core. There are several interesting pieces of middleware that are very useful when developing your app. The DeveloperExceptionPage will let you see details about exceptions that are unhandled by your app. You don’t want this to be enabled in production, as it could reveal sensitive data, but it’s great during development. The DatabaseErrorPage is helpful when you’re first creating an app and haven’t yet configured its database. It can help you get that set up. BrowserLink works with Visual Studio to speed up how quickly changes you make in your app are reflected in the browser, without always have to restart the app and refresh the browser. You can specify an Exception Handler route, so that any unhandled exceptions that occur result in the display of an “oops” or similar page for users in production. If you want custom pages for certain status codes, such as a humorous 404 Not Found page, the UseStatusCodePages middleware can provide this functionality. The Welcome pages provide some very basic information, and is useful for ensuring the app is functioning at its most basic level Finally, the ElmPage and ElmCapture middleware are part of the Error Logging Middleware, or ELM, which can be used to record developer exception pages for later review.
• #39: UseIdentity is used to allow your app to use the built-in membership and identity services. It’s used with authentication and authorization. Static files middleware is required for the app to server up static content, such as script and style files, and images. Some apps may require additional file serving functionality, in which case you can add support for default files, like default.aspx or index.htm. You can configure the app to act as a server-side file browser, and if you need all of this functionality you can simply add the FileServer middleware. If you need to customize routes and routing in your app, you can use Router middleware. Most apps will work at a higher level than this, though, such as with the Model View Controller, or MVC framework, which uses Router internally. Version 1.1 of ASP.NET Core added some additional middleware to support URL rewriting, response compression, and response caching.
• #43: ASP.NET Core doesn’t just support dependency injection, it uses it internally to achieve its goals of being modular and loosely coupled. Your application code can leverage this capability in the same way ASP.NET Core does.
• #44: Dependency injection, or DI, is a software design technique in which collaborating classes are injected into the class that needs them, rather than being referenced directly. One could even call it collaborator injection. The collaborator, or dependency, is injected into the class by way of parameters, or sometimes by setting properties. The most common technique involves passing the dependencies into the constructor of the class that will need them, which then assigns the instances to local fields. This approach produces a more flexible and modular design, since classes do not have direct dependence on specific implementations of their collaborators. This also ensure the classes follow the Explicit Dependencies Principle and the Dependency Inversion Principle.
• #45: The Explicit Dependencies Principle states that classes should express their requirements through their constructor. If the class cannot function without certain collaborating classes being available, then it should be up front about these dependencies and request them as part of its constructor. If instead the class directly instantiates its dependencies, or references them statically, it creates hidden dependencies and tight coupling that may only become apparent at runtime. For example, if you have a class that interacts with a database, and it does so by calling a static helper method, it’s likely this class will fail with an exception at runtime if the database isn’t available. However, if you’re interested in testing the behavior of the class, perhaps swapping in a fake database or using an in memory data store instead for test purposes, it will be very difficult to do so when the dependency is implicit within the class and not exposed as a parameter. This can also be an example of violating the Open/Closed Principle, because the class’s behavior could not be changed without changing its source code. Classes that have hidden or implicit dependencies aren’t being honest about their functional requirements. If the class or method needs a database (or some data store) in order to function, it should declare this dependency as a parameter. If only one method has a dependency, it may make sense to only add the parameter at the method rather than the class level. However, many frameworks provide support for automatically populating dependencies on the constructor, so even in the case where only one method has a dependency, it may make sense to inject it through the class constructor.
• #46: At the end of the last chapter, we created a simple MVC app and looked at how we can use ASP.NET Core’s dependency injection feature to inject services into controllers. In this chapter, we’ll provide an overview of ASP.NET Core MVC that should let you get started building business apps on top of this framework. This will include building Web APIs with ASP.NET Core MVC. In ASP.NET MVC 5 and Web API 2, support for web APIs was in a separate set of classes and packages from MVC. In ASP.NET Core, this is no longer the case, and web API functionality is built directly into ASP.NET Core MVC.
• #47: The entry point for each request to your ASP.NET Core MVC application is an action. Actions are methods, and collections of actions are grouped together into cohesive sets by Controllers. Controllers are useful for routing and URL generation, as well as to support constructor dependency injection. In ASP.NET Core MVC, controllers do not need to inherit from any special type – they just need to be named with the Controller suffix. However, the Microsoft.AspNetCore.Mvc.Controller type provides many helpful methods that you can use. Here you can see an example of a simple controller that inherits from the Controller base class and defines several action methods. Actions are simply methods that handle individual requests. Each request made to the application maps to an action method by way of routing middleware. Individual actions can return raw data, a view, or an action result. Actions can be synchronous or async. Here is an example of a simple async action that displays a view for a Login page in an application. Since it is async, its return type is a Task of IActionResult instead of just an IActionResult. It also uses the Await keyword in its body when it calls out to async methods. This action method is also decorated with two attributes. The first one, HttpGet, specifies the HTTP verb this action will respond to, and is used by the routing engine. The second attribute, AllowAnonymous, will override an attribute set at a higher level requiring the user to be authenticated, and will allow an anonymous request to run this action.
• #50: You can specify default routes for MVC when you configure it in the Configure method in Startup. The default MVC templates add code like this, which defines a default route template. This template should be familiar to you if you’ve used MVC 5 or earlier. It uses the routing convention of controller/action/id, where id is optional. It also specifies default values for the controller and action, so if not present Home and Index are used. ASP.NET Core MVC supports attribute routing, which lets you define route information close to the actions that will use be associated with the route. The Route attribute is used to specify the route at the controller and/or action level, and if routes are specified for both they are combined.
• #51: Here are my tips for working with routing in ASP.NET Core MVC. First, use the default route convention wherever possible. It works well and will be familiar to any developers who must work on your application later, whether they’re coming from Core MVC or legacy ASP.NET MVC. Embrace attribute routing and use it wherever you need to stray from the defaults. Microsoft especially recommends this for API methods. API method can define routes directly within their HTTP Verb attributes, so for instance you can specify a route or partial route as part of an [HttpGet] or [HttpPost] attribute. This action-level route will be combined with any controller-specified route. To reduce the number of magic strings you need to specify in your routes, you can use token replacements for area, controller, and action. These tokens will be replaced with the actual area, controller, or action name where the route attribute is applied. This feature is especially powerful when combined with inheritance. For example, if you want all of your API methods to use a route starting with /api and followed by controllername and actionname, you can specify this route attribute on a base api controller class, as shown.
• #52: Clients, whether web browsers or other applications, can send data to your application as web requests. MVC uses a process called model binding to convert data sent by requests into parameters on action methods. Model binding takes place before the action is invoked. This is important to remember since occasionally there may be errors or other behavior going on during model binding that may not be immediately apparent to you if you’re expecting your action to be the first code to be executed by a request. Don’t forget about model binding! Parameters on action methods may be simple primitive types like ints and strings, or they may be complex objects. Model binding can support all of these scenarios. Data coming into an action may come from form values, route components, or query strings, in this order. Model types can also have validation rules specified, and model validation occurs before the action method is called. Your actions should always check model validity, especially in methods that will make changes to application state. You should avoid using data model types in your UI layer, but if you must, you should especially avoid using them in actions that accept data and use model binding. Doing so can allow malicious users to save properties you may not have meant to expose, because they could guess these properties exist, pass them into the request, and model binding will automatically populate these properties (which you might then save in your action). Finally, you can use the FromBody attribute on a single parameter to specify that it should be found to the body of the request. By default the expected format is JSON, but you can configure other input formatters to support formats like XML.
• #53: Clients, whether web browsers or other applications, can send data to your application as web requests. MVC uses a process called model binding to convert data sent by requests into parameters on action methods. Model binding takes place before the action is invoked. This is important to remember since occasionally there may be errors or other behavior going on during model binding that may not be immediately apparent to you if you’re expecting your action to be the first code to be executed by a request. Don’t forget about model binding! Parameters on action methods may be simple primitive types like ints and strings, or they may be complex objects. Model binding can support all of these scenarios. Data coming into an action may come from form values, route components, or query strings, in this order. Model types can also have validation rules specified, and model validation occurs before the action method is called. Your actions should always check model validity, especially in methods that will make changes to application state. You should avoid using data model types in your UI layer, but if you must, you should especially avoid using them in actions that accept data and use model binding. Doing so can allow malicious users to save properties you may not have meant to expose, because they could guess these properties exist, pass them into the request, and model binding will automatically populate these properties (which you might then save in your action). Finally, you can use the FromBody attribute on a single parameter to specify that it should be found to the body of the request. By default the expected format is JSON, but you can configure other input formatters to support formats like XML.
• #57: The default MVC project template in visual studio uses EF Core if you specify that you want to have individual user accounts. You’ll find a line of code in your startup class that adds support for EF Core to the app by adding it in the ConfigureServices method. This is where you specify your application’s DbContext class, which inherits from the base DbContext class defined by EF Core. You also specify how it will connect to Sql Server. EF Core has built-in support for an InMemory database provider. This support requires installing a separate package and modifying the configuration of your DbContext type as shown. You’ll probably also need to specify the Microsoft.EntityFrameworkCore namespace for the UseInMemoryDatabase extension method to work. The in-memory data store is reset each time the application starts.
• #58: In your ASP.NET Core applications, you should never be instantiating your application’s DbContext implementation directly. This advice applies to previous MVC implementations, too, but it was much easier to instantiate an EF6 dbcontext than it is to instantiate an EF Core one. This is at least partly by design – in EF Core the team has embraced dependency injection and wants code to fall into this pattern by default. Thus, to make use of EF Core in your application, you should simply request your DbContext implementation from the constructor of the type that needs it. That said, you should also try to follow the Dependency Inversion Principle, which means you want to avoid having your UI types, like Controllers, depending on details. EF Core is an implementation detail for how your app gets and persists data. Rather than depending on it directly, your classes should depend on abstractions. The common pattern that describes these persistence abstractions is the Repository. You may hear some in the developer community decry this pattern, or say that it’s not needed because EF already implements this pattern. In my experience, not following this pattern will bit you later, and following it is simple and easy, so you’re better off following it. You’ll have more loosely coupled code that’s easier to change and test if you follow this recommendation.
• #59: If you’re building an app of any complexity, you’ll probably get some value out of testing it so that you know it works as you expect. You can manually test your application, but your time is valuable and computers can do that sort of thing much faster than humans can, so why not automate it?
• #60: One of my favorite features in ASP.NET Core is the TestServer. The TestServer makes it extremely easy to write integration tests for ASP.NET Core that run through the full ASP.NET Core MVC stack. You configure a TestServer using a WebHostBuilder. The configuration might look just like the builder you use for your application, but you can modify it if necessary to make it work for testing. For instance, you might want to change how it gets its data or configure it with test data your tests will expect. Once you have a WebHostbuilder configured, use it to create a TestServer instance, and then you can get an HttpClient from the TestServer. This HttpClient is pre-configured to connect to the TestServer, all of which happens without going through your system’s network stack, so you don’t run into issues with firewalls or other problems when using this approach. Once you have the client, you can use it to make requests to your application, and then verify the responses.
• #61: To perform integration testing on ASP.NET core, get an HttpClient that connects to your TestServer, and make a request. Capture the response, and verify it’s correct. You can start by verifying that the status code was what you expected. Then deserialize the response, if required. The response will be a string. If you want to get it back into an object, you can deserialize it using JSON or XML or whatever format it’s in. For view-based responses, the result will typically be a string containing HTML. Assert that the response includes the values you’re expecting to complete your test. You’ll find using this approach that testing API methods if pretty easy. Testing views requires a little more setup initially, and the assertions on the results can be more brittle depending on how you specific you are about your assertion. We’ll look at both of these scenarios next.
• #66: Migration Notes: https://docs.microsoft.com/en-us/aspnet/core/migration/1x-to-2x/index 1. Update TargetFramework to netcoreapp2.0 2. update global.json to version 2.0.0 (if used) 3. Update package references. Use new MS.AspNetCore.All 2.0.0 package. Includes EF Core 2.0. 4. Update other packages to 2.0.0 if needed. 5. Update .NET Core CLI Tools 6. Change PackageTargetFallback to AssetTargetFallback 7. Update Main in Program.cs 8. Make sure you're not doing DB setup in Startup.Configure. Move it to Main in Program.cs. 9. Remove MvcRazorCompileOnPublish = true from .csproj files -- it is now on by default. If targeting .NET Framework, need to reference ViewCompilation package. 10. If you're not explicitly using App Insights, remove from .csproj, program.cs, and your _Layout file. 11. Migrate Auth/Identity to 2.0