daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/mvc/controllers/areas.md

10 KiB
Raw Blame History

title author description ms.author ms.date uid
Areas in ASP.NET Core rick-anderson Learn how Areas are an ASP.NET MVC feature used to organize related functionality into a group as a separate namespace (for routing) and folder structure (for views). riande 02/14/2019 mvc/controllers/areas

Areas in ASP.NET Core

By Dhananjay Kumar and Rick Anderson

Areas are an ASP.NET feature used to organize related functionality into a group as a separate namespace (for routing) and folder structure (for views). Using areas creates a hierarchy for the purpose of routing by adding another route parameter, area, to controller and action or a Razor Page page.

Areas provide a way to partition an ASP.NET Core Web app into smaller functional groups, each with its own set of Razor Pages, controllers, views, and models. An area is effectively a structure inside an app. In an ASP.NET Core web project, logical components like Pages, Model, Controller, and View are kept in different folders. The ASP.NET Core runtime uses naming conventions to create the relationship between these components. For a large app, it may be advantageous to partition the app into separate high level areas of functionality. For instance, an e-commerce app with multiple business units, such as checkout, billing, and search. Each of these units have their own area to contain views, controllers, Razor Pages, and models.

Consider using Areas in a project when:

  • The app is made of multiple high-level functional components that can be logically separated.
  • You want to partition the app so that each functional area can be worked on independently.

View or download sample code (how to download). The download sample provides a basic app for testing areas.

If you're using Razor Pages, see Areas with Razor Pages in this document.

Areas for controllers with views

A typical ASP.NET Core web app using areas, controllers, and views contains the following:

Area folder structure

Consider an app that has two logical groups, Products and Services. Using areas, the folder structure would be similar to the following:

  • Project name
    • Areas
      • Products
        • Controllers
          • HomeController.cs
          • ManageController.cs
        • Views
          • Home
            • Index.cshtml
          • Manage
            • Index.cshtml
            • About.cshtml
      • Services
        • Controllers
          • HomeController.cs
        • Views
          • Home
            • Index.cshtml

While the preceding layout is typical when using Areas, only the view files are required to use this folder structure. View discovery searches for a matching area view file in the following order:

/Areas/<Area-Name>/Views/<Controller-Name>/<Action-Name>.cshtml
/Areas/<Area-Name>/Views/Shared/<Action-Name>.cshtml
/Views/Shared/<Action-Name>.cshtml
/Pages/Shared/<Action-Name>.cshtml

The location of non-view folders like Controllers and Models does not matter. For example, the Controllers and Models folder are not required. The content of Controllers and Models is code which gets compiled into a .dll. The content of the Views isn't compiled until a request to that view has been made.

Associate the controller with an Area

Area controllers are designated with the [Area] attribute:

[!code-csharp]

Add Area route

Area routes typically use conventional routing rather than attribute routing. Conventional routing is order-dependent. In general, routes with areas should be placed earlier in the route table as they're more specific than routes without an area.

{area:...} can be used as a token in route templates if url space is uniform across all areas:

[!code-csharp]

In the preceding code, exists applies a constraint that the route must match an area. Using {area:...} is the least complicated mechanism to adding routing to areas.

The following code uses xref:Microsoft.AspNetCore.Builder.MvcAreaRouteBuilderExtensions.MapAreaRoute* to create two named area routes:

[!code-csharp]

When using MapAreaRoute with ASP.NET Core 2.2, see this GitHub issue.

For more information, see Area routing.

Link generation with MVC areas

The following code from the sample download shows link generation with the area specified:

[!code-cshtml]

The links generated with the preceding code are valid anywhere in the app.

The sample download includes a partial view that contains the preceding links and the same links without specifying the area. The partial view is referenced in the layout file, so every page in the app displays the generated links. The links generated without specifying the area are only valid when referenced from a page in the same area and controller.

When the area or controller is not specified, routing depends on the ambient values. The current route values of the current request are considered ambient values for link generation. In many cases for the sample app, using the ambient values generates incorrect links.

For more information, see Routing to controller actions.

Shared layout for Areas using the _ViewStart.cshtml file

To share a common layout for the entire app, move the _ViewStart.cshtml to the application root folder.

Change default area folder where views are stored

The following code changes the default area folder from "Areas" to "MyAreas":

[!code-csharp]

Areas with Razor Pages

Areas with Razor Pages require and Areas/<area name>/Pages folder in the root of the app. The following folder structure is used with the sample download

  • Project name
    • Areas
      • Products
        • Pages
          • _ViewImports
          • About
          • Index
      • Services
        • Pages
          • Manage
            • About
            • Index

Link generation with Razor Pages and areas

The following code from the sample download shows link generation with the area specified (for example, asp-area="Products"):

[!code-cshtml]

The links generated with the preceding code are valid anywhere in the app.

The sample download includes a partial view that contains the preceding links and the same links without specifying the area. The partial view is referenced in the layout file, so every page in the app displays the generated links. The links generated without specifying the area are only valid when referenced from a page in the same area.

When the area is not specified, routing depends on the ambient values. The current route values of the current request are considered ambient values for link generation. In many cases for the sample app, using the ambient values generates incorrect links. For example, consider the links generated from the following code:

[!code-cshtml]

For the preceding code:

  • The link generated from <a asp-page="/Manage/About"> is correct only when the last request was for a page in Services area. For example, /Services/Manage/, /Services/Manage/Index, or /Services/Manage/About.
  • The link generated from <a asp-page="/About"> is correct only when the last request was for a page in /Home.
  • The code is from the sample download.

Import namespace and Tag Helpers with _ViewImports file

A _ViewImports file can be added to each area Pages folder to import the namespace and Tag Helpers to each Razor Page in the folder.

Consider the Services area of the sample code, which doesn't contain a _ViewImports file. The following markup shows the /Services/Manage/About Razor Page:

[!code-cshtml]

In the preceding markup:

  • The fully qualified domain name must be used to specify the model (@model RPareas.Areas.Services.Pages.Manage.AboutModel).
  • Tag Helpers are enabled by @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

In the sample download, the Products area contains the following _ViewImports file:

[!code-cshtml]

The following markup shows the /Products/About Razor Page: [!code-cshtml]

In the preceding file, the namespace and @addTagHelper directive is imported to the file by the Areas/Products/Pages/_ViewImports.cshtml file:

For more information, see Managing Tag Helper scope and Importing Shared Directives.

Shared layout for Razor Pages Areas

To share a common layout for the entire app, move the _ViewStart.cshtml to the application root folder.

Publishing Areas

All *.cshtml and wwwroot/** files are published to output when <Project Sdk="Microsoft.NET.Sdk.Web"> is included in the.csproj* file.