Edit pass on the porting ASP.NET eBook

docs/architecture/porting-existing-aspnet-apps/app-startup-differences.md

@@ -7,21 +7,21 @@ ms.date: 11/13/2020
 
 # App startup differences between ASP.NET MVC and ASP.NET Core
 
-ASP.NET MVC applications lived entirely within Internet Information Server (IIS), the primary web server available on Windows operating systems. Unlike ASP.NET MVC, ASP.NET Core applications are executable applications. You can run them from the command line, using `dotnet run`. They have an entry point method like all C# programs, typically `public static void main()` or a similar variation (perhaps with arguments or async support). This is perhaps the biggest architectural difference between ASP.NET Core and ASP.NET MVC, and is one of several differences that allows ASP.NET Core to run on non-Windows systems.
+ASP.NET MVC apps lived entirely within Internet Information Server (IIS), the primary web server available on Windows operating systems. Unlike ASP.NET MVC, ASP.NET Core apps are executable apps. You can run them from the command line, using `dotnet run`. They have an entry point method like all C# programs, typically `public static void main()` or a similar variation (perhaps with arguments or async support). This is perhaps the biggest architectural difference between ASP.NET Core and ASP.NET MVC, and is one of several differences that allows ASP.NET Core to run on non-Windows systems.
 
 ## ASP.NET MVC Startup
 
-Hosted within IIS, ASP.NET applications rely on IIS to instantiate certain objects and call certain methods when a request arrives. ASP.NET creates an instance of the `Global.asax` file's class, which derives from `HttpApplication`. When the first request is received, before handling the request itself, ASP.NET calls the `Application_Start` method in the `Global.asax` file's class. Any logic that needs to run when the ASP.NET MVC application begins can be added to this method.
+Hosted within IIS, ASP.NET apps rely on IIS to instantiate certain objects and call certain methods when a request arrives. ASP.NET creates an instance of the `Global.asax` file's class, which derives from `HttpApplication`. When the first request is received, before handling the request itself, ASP.NET calls the `Application_Start` method in the `Global.asax` file's class. Any logic that needs to run when the ASP.NET MVC app begins can be added to this method.
 
-Many NuGet packages for ASP.NET MVC and Web API use the [WebActivator](https://github.com/davidebbo/WebActivator) package to let them run some code during application startup. By convention, this code would typically be added to an `App_Start` folder and would be configured via attribute to run either immediately before or just after `Application_Start`.
+Many NuGet packages for ASP.NET MVC and Web API use the [WebActivator](https://github.com/davidebbo/WebActivator) package to let them run some code during app startup. By convention, this code would typically be added to an `App_Start` folder and would be configured via attribute to run either immediately before or just after `Application_Start`.
 
-It's also possible to use the [Open Web Interface for .NET (OWIN) and Project Katana with ASP.NET MVC](https://docs.microsoft.com/aspnet/aspnet/overview/owin-and-katana/getting-started-with-owin-and-katana). When doing so, the application will include a `Startup.cs` file that is responsible for setting up request middleware in a way that's very similar to how ASP.NET Core behaves.
+It's also possible to use the [Open Web Interface for .NET (OWIN) and Project Katana with ASP.NET MVC](https://docs.microsoft.com/aspnet/aspnet/overview/owin-and-katana/getting-started-with-owin-and-katana). When doing so, the app will include a `Startup.cs` file that is responsible for setting up request middleware in a way that's very similar to how ASP.NET Core behaves.
 
 If you need to run code when your ASP.NET MVC app starts up, it will typically use one of these approaches.
 
 ## ASP.NET Core Startup
 
-As noted previously, ASP.NET Core applications are standalone programs. As such, they typically include a `Program.cs` file containing the entry point for the application. A typical such file is shown in Figure 2-1.
+As noted previously, ASP.NET Core apps are standalone programs. As such, they typically include a `Program.cs` file containing the entry point for the app. A typical example of this file is shown in Figure 2-1.
 
 ```csharp
 public class Program
@@ -42,11 +42,11 @@ public class Program
 
 **Figure 2-1**. A typical ASP.NET Core Program.cs file.
 
-The code shown in Figure 2-1 creates a *host* for the application, builds it, and runs it. The ASP.NET Core application runs within the host configured by the `IHostBuilder` shown. While it's possible to completely configure an ASP.NET Core app using the `IHostBuilder`, typically the bulk of this work is done in a `Startup` class.
+The code shown in Figure 2-1 creates a *host* for the app, builds it, and runs it. The ASP.NET Core app runs within the host configured by the `IHostBuilder` shown. While it's possible to completely configure an ASP.NET Core app using the `IHostBuilder`, typically the bulk of this work is done in a `Startup` class.
 
 The `Startup` class exposes two methods to the host: `ConfigureServices` and `Configure`. The `ConfigureServices` method is used to define the services the app will use and their respective lifetimes. The `Configure` method is used to define how each request to the app will be handled by setting up a request pipeline composed of middleware.
 
-In addition to code related to configuring the application's services or request pipeline, apps may have other code that must run when the app begins. Such code is typically placed in `Program.cs` or registered as an `IHostedService` which will be started by the [generic host](https://docs.microsoft.com/aspnet/core/fundamentals/host/generic-host?view=aspnetcore-3.1) when the application starts.
+In addition to code related to configuring the app's services or request pipeline, apps may have other code that must run when the app begins. Such code is typically placed in `Program.cs` or registered as an `IHostedService`, which will be started by the [generic host](https://docs.microsoft.com/aspnet/core/fundamentals/host/generic-host?view=aspnetcore-3.1) when the app starts.
 
 The `IHostedService` interface just exposes two methods, `StartAsync` and `StopAsync`. You register the interface in `ConfigureServices` and the host does the rest, calling the `StartAsync` method before the app starts up.
 

docs/architecture/porting-existing-aspnet-apps/architectural-differences.md

@@ -13,7 +13,7 @@ There are many architectural differences between ASP.NET MVC on .NET Framework a
 
 ## Breaking changes
 
-Because .NET Core is a complete rewrite of .NET, designed from the ground up to be cross-platform, there are many [breaking changes between the two frameworks](https://docs.microsoft.com/dotnet/core/compatibility/fx-core). The following sections identify specific differences between how ASP.NET MVC and ASP.NET Core apps are designed and developed, but take care also to examine the documentation to determine which framework libraries you're using that may need to be changed. In many cases, a replacement NuGet package exists to fill in any gaps left between .NET Framework and .NET Core. In rare cases, you may need to find a third-party solution or implement new custom code to address incompatibilities.
+.NET Core is a cross-platform rewrite of .NET Framework. There are many [breaking changes between the two frameworks](https://docs.microsoft.com/dotnet/core/compatibility/fx-core). The following sections identify specific differences between how ASP.NET MVC and ASP.NET Core apps are designed and developed. Take care to also examine the documentation to determine which framework libraries you're using that may need to change. In many cases, a replacement NuGet package exists to fill in any gaps left between .NET Framework and .NET Core. In rare cases, you may need to find a third-party solution or implement new custom code to address incompatibilities.
 
 >[!div class="step-by-step"]
 >[Previous](additional-migration-resources.md)

docs/architecture/porting-existing-aspnet-apps/authentication-differences.md

@@ -1,11 +1,11 @@
 ---
-title: Comparing Authentication and Authorization between ASP.NET MVC and ASP.NET Core
+title: Compare Authentication and Authorization between ASP.NET MVC and ASP.NET Core
 description: A summary of authentication and authorization differences between ASP.NET MVC and ASP.NET Core.
 author: ardalis
 ms.date: 11/13/2020
 ---
 
-# Comparing authentication and authorization between ASP.NET MVC and ASP.NET Core
+# Compare authentication and authorization between ASP.NET MVC and ASP.NET Core
 
 In ASP.NET MVC 5, authentication is configured in `Startup.Auth.cs` in the `App_Start` folder. In ASP.NET Core MVC, this configuration occurs in `Startup.cs`. Authentication and authorization are performed using middleware added to the request pipeline in `ConfigureServices`:
 
@@ -28,13 +28,13 @@ app.UseEndpoints(endpoints =>
 
 It's important to add the auth middleware in the appropriate location in the middleware pipeline. Only requests that make it to the middleware will be impacted by it. For instance, if a call to `UseStaticFiles()` was placed above the code shown here, it wouldn't be protected by authentication and authorization.
 
-In ASP.NET MVC and Web API, applications often refer to the current user using the `ClaimsPrincipal.Current` property. This property isn't set in ASP.NET Core, and any behavior in your app that depends on it will need to [migrate from ClaimsPrincipal.Current](https://docs.microsoft.com/aspnet/core/migration/claimsprincipal-current) by using the `User` property on `ControllerBase` or getting access to the current `HttpContext` and referencing its `User` property. If neither of these solutions is an option, services can request the User as an argument, in which case it must be supplied from elsewhere in the app, or the `IHttpContextAccessor` can be requested and used to get the `HttpContext`.
+In ASP.NET MVC and Web API, apps often refer to the current user using the `ClaimsPrincipal.Current` property. This property isn't set in ASP.NET Core, and any behavior in your app that depends on it will need to [migrate from ClaimsPrincipal.Current](https://docs.microsoft.com/aspnet/core/migration/claimsprincipal-current) by using the `User` property on `ControllerBase` or getting access to the current `HttpContext` and referencing its `User` property. If neither of these solutions is an option, services can request the User as an argument, in which case it must be supplied from elsewhere in the app, or the `IHttpContextAccessor` can be requested and used to get the `HttpContext`.
 
 ## Authorization
 
-Authorization defines what a given user can do within the app. It's separate from authentication, which is concerned merely with identifying who the user is. ASP.NET Core provides a simple, declarative role and a rich policy-based model for authorization. Specifying that a resource requires authorization is often as simple as adding the `[Authorize]` attribute to the action or controller. If you're migrating to Razor Pages from MVC views, you should [specify conventions for authorization when you configure Razor Pages in Startup](https://docs.microsoft.com/aspnet/core/security/authorization/razor-pages-authorization).
+Authorization defines what a given user can do within the app. It's separate from authentication, which is concerned merely with identifying who the user is. ASP.NET Core provides a simple, declarative role and a rich, policy-based model for authorization. Specifying that a resource requires authorization is often as simple as adding the `[Authorize]` attribute to the action or controller. If you're migrating to Razor Pages from MVC views, you should [specify conventions for authorization when you configure Razor Pages in Startup](https://docs.microsoft.com/aspnet/core/security/authorization/razor-pages-authorization).
 
-Authorization in ASP.NET Core may be as simple as prohibiting anonymous users while allowing authenticated users. Or it can scale up to support role-based, claims-based, or policy-based authorization approaches. For more information on these approaches, see the documentation on [authorization in ASP.NET Core](https://docs.microsoft.com/aspnet/core/security/authorization/introduction). It's likely you'll find that one of them is fairly closely aligned with your current authorization approach.
+Authorization in ASP.NET Core may be as simple as prohibiting anonymous users while allowing authenticated users. Or it can scale up to support role-based, claims-based, or policy-based authorization approaches. For more information on these approaches, see the documentation on [authorization in ASP.NET Core](https://docs.microsoft.com/aspnet/core/security/authorization/introduction). You'll likely find that one of them is closely aligned with your current authorization approach.
 
 ## References
 

docs/architecture/porting-existing-aspnet-apps/choose-net-core-version.md

@@ -9,11 +9,11 @@ ms.date: 11/13/2020
 
 The largest consideration for most organizations when choosing a version of .NET Core to target is the support lifecycle. Long Term Support (LTS) releases ship less frequently but have a longer support window than Current (non-LTS) releases. Currently, LTS releases are scheduled to ship every other year. Customers can choose which releases to target, and can install different releases of .NET Core side by side on the same machine. LTS releases will receive only critical and compatible fixes throughout their lifecycle. Current releases will receive these same fixes and will also be updated with compatible innovations and features. LTS releases are supported for three years after their initial release. Current releases are supported for three months after a subsequent Current or LTS release.
 
-Most customers looking to migrate a large .NET Framework application to .NET Core today are probably looking for a stable destination, given that they haven't already made the move to an earlier version of .NET Core. In this case, the best .NET Core version to target for the migration is .NET Core 3.1, which is the current LTS version. Support for .NET Core 3.1 ends in December 2022. The next planned LTS release will be .NET 6.0, slated to ship in November 2021.
+Most customers looking to migrate a large .NET Framework app to .NET Core today are probably looking for a stable destination, given that they haven't already made the move to an earlier version of .NET Core. In this case, the best .NET Core version to target for the migration is .NET Core 3.1, which is the current LTS version. Support for .NET Core 3.1 ends in December 2022. The next planned LTS release will be .NET 6.0, slated to ship in November 2021.
 
-Updating from .NET Core 3.1 to .NET 5.0 (the next version) is relatively straightforward and certainly will require substantially less effort than porting from .NET Framework to .NET Core. For this reason, the recommendation for most customers is to upgrade to .NET Core 3.1 first. Then decide whether the next update should be to the latest current release (.NET 5.0) or to wait for the next LTS release (.NET 6.0) before upgrading further.
+Updating from .NET Core 3.1 to .NET 5.0 (the next version) requires much less effort than porting from .NET Framework to .NET Core. For this reason, the recommendation for most customers is to upgrade to .NET Core 3.1 first. Then decide whether the next update should be to the latest current release (.NET 5.0) or to wait for the next LTS release (.NET 6.0) before upgrading further.
 
-This book assumes .NET Framework applications will be upgraded to .NET Core 3.1.
+This book assumes .NET Framework apps will be upgraded to .NET Core 3.1.
 
 ## References
 

docs/architecture/porting-existing-aspnet-apps/comparing-razor-pages-aspnet-mvc.md

@@ -1,11 +1,11 @@
 ---
-title: Comparing Razor Pages to ASP.NET MVC
+title: Compare Razor Pages to ASP.NET MVC
 description: Razor Pages offer a better way to organize responsibilities than traditional MVC views for page-based apps. Learn how they compare to the traditional ASP.NET MVC approach in this section.
 author: ardalis
 ms.date: 11/13/2020
 ---
 
-# Comparing Razor Pages to ASP.NET MVC
+# Compare Razor Pages to ASP.NET MVC
 
 Razor Pages is the preferred way to create page- or form-based apps in ASP.NET Core. From the [docs](https://docs.microsoft.com/aspnet/core/razor-pages/), "Razor Pages can make coding page-focused scenarios easier and more productive than using controllers and views." If your ASP.NET MVC app makes heavy use of views, you may want to consider migrating from actions and views to Razor Pages.