Added info about calling generic methods to the Razor syntax topic (#4576)
* Added info about calling generic methods to the Razor syntax topic Info added in the sections on Razor code blocks, implicit expressions, and explicit expressions. * Made edits suggested by reviewer @guardrex * Update razor.md * Update razor.md * Update razor.mdpull/4577/head
Dan Vicarel
Rick Anderson
parent
74bc947c96
commit
a873f862c8
|
|
@ -1,11 +1,11 @@
|
|||
---
|
||||
title: Razor syntax reference for ASP.NET Core
|
||||
author: guardrex
|
||||
author: rick-anderson
|
||||
description: Learn about Razor markup syntax for embedding server-based code into webpages.
|
||||
keywords: ASP.NET Core,Razor,Razor directives
|
||||
ms.author: riande
|
||||
manager: wpickett
|
||||
ms.date: 09/29/2017
|
||||
ms.date: 10/18/2017
|
||||
ms.topic: article
|
||||
ms.technology: aspnet
|
||||
ms.prod: asp.net-core
|
||||
|
|
@ -13,13 +13,13 @@ uid: mvc/views/razor
|
|||
---
|
||||
# Razor syntax for ASP.NET Core
|
||||
|
||||
By [Rick Anderson](https://twitter.com/RickAndMSFT), [Luke Latham](https://github.com/guardrex), and [Taylor Mullen](https://twitter.com/ntaylormullen)
|
||||
By [Rick Anderson](https://twitter.com/RickAndMSFT), [Luke Latham](https://github.com/guardrex), [Taylor Mullen](https://twitter.com/ntaylormullen), and [Dan Vicarel](https://github.com/Rabadash8820)
|
||||
|
||||
Razor is a markup syntax for embedding server-based code into webpages. The Razor syntax consists of Razor markup, C#, and HTML. Files containing Razor generally have a *.cshtml* file extension.
|
||||
|
||||
## Rendering HTML
|
||||
|
||||
The default Razor language is HTML. Rendering HTML from Razor markup is no different than rendering HTML from an HTML file. If you place HTML markup into a *.cshtml* Razor file, it's rendered by the server unchanged.
|
||||
The default Razor language is HTML. Rendering HTML from Razor markup is no different than rendering HTML from an HTML file. HTML markup in *.cshtml* Razor files is rendered by the server unchanged.
|
||||
|
||||
## Razor syntax
|
||||
|
||||
|
|
@ -54,12 +54,25 @@ Implicit Razor expressions start with `@` followed by C# code:
|
|||
<p>@DateTime.IsLeapYear(2016)</p>
|
||||
```
|
||||
|
||||
With the exception of the C# `await` keyword, implicit expressions must not contain spaces. You can intermingle spaces if the C# statement has a clear ending:
|
||||
With the exception of the C# `await` keyword, implicit expressions must not contain spaces. If the C# statement has a clear ending, spaces can be intermingled:
|
||||
|
||||
```cshtml
|
||||
<p>@await DoSomething("hello", "world")</p>
|
||||
```
|
||||
|
||||
Implicit expressions **cannot** contain C# generics, as the characters inside the brackets (`<>`) are interpreted as an HTML tag. The following code is **not** valid:
|
||||
|
||||
```cshtml
|
||||
<p>@GenericMethod<int>()</p>
|
||||
```
|
||||
|
||||
The preceding code generates a compiler error similar to one of the following:
|
||||
|
||||
* The "int" element was not closed. All elements must be either self-closing or have a matching end tag.
|
||||
* Cannot convert method group 'GenericMethod' to non-delegate type 'object'. Did you intend to invoke the method?`
|
||||
|
||||
Generic method calls must be wrapped in an [explicit Razor expression](#explicit-razor-expressions) or a [Razor code block](#razor-code-blocks). This restriction doesn't apply to *.vbhtml* Razor files because Visual Basic syntax places parentheses around generic type parameters instead of brackets.
|
||||
|
||||
## Explicit Razor expressions
|
||||
|
||||
Explicit Razor expressions consist of an `@` symbol with balanced parenthesis. To render last week's time, the following Razor markup is used:
|
||||
|
|
@ -80,7 +93,7 @@ The code renders the following HTML:
|
|||
<p>Last week: 7/7/2016 4:39:52 PM - TimeSpan.FromDays(7)</p>
|
||||
```
|
||||
|
||||
You can use an explicit expression to concatenate text with an expression result:
|
||||
Explicit expressions can be used to concatenate text with an expression result:
|
||||
|
||||
```cshtml
|
||||
@{
|
||||
|
|
@ -92,6 +105,26 @@ You can use an explicit expression to concatenate text with an expression result
|
|||
|
||||
Without the explicit expression, `<p>Age@joe.Age</p>` is treated as an email address, and `<p>Age@joe.Age</p>` is rendered. When written as an explicit expression, `<p>Age33</p>` is rendered.
|
||||
|
||||
|
||||
Explicit expressions can be used to render output from generic methods in *.cshtml* files. In an implicit expression, the characters inside the brackets (`<>`) are interpreted as an HTML tag. The following markup is **not** valid Razor:
|
||||
|
||||
```cshtml
|
||||
<p>@GenericMethod<int>()</p>
|
||||
```
|
||||
|
||||
The preceding code generates a compiler error similar to one of the following:
|
||||
|
||||
* The "int" element was not closed. All elements must be either self-closing or have a matching end tag.
|
||||
* Cannot convert method group 'GenericMethod' to non-delegate type 'object'. Did you intend to invoke the method?`
|
||||
|
||||
The following markup shows the correct way write this code. The code is written as an explicit expression:
|
||||
|
||||
```cshtml
|
||||
<p>@(GenericMethod<int>())</p>
|
||||
```
|
||||
|
||||
Note: this restriction doesn't apply to *.vbhtml* Razor files. With *.vbhtml* Razor files, Visual Basic syntax places parentheses around generic type parameters instead of brackets.
|
||||
|
||||
## Expression encoding
|
||||
|
||||
C# expressions that evaluate to a string are HTML encoded. C# expressions that evaluate to `IHtmlContent` are rendered directly through `IHtmlContent.WriteTo`. C# expressions that don't evaluate to `IHtmlContent` are converted to a string by `ToString` and encoded before they're rendered.
|
||||
|
|
@ -154,7 +187,7 @@ The code renders the following HTML:
|
|||
|
||||
### Implicit transitions
|
||||
|
||||
The default language in a code block is C#, but you can transition back to HTML:
|
||||
The default language in a code block is C#, but the Razor Page can transition back to HTML:
|
||||
|
||||
```cshtml
|
||||
@{
|
||||
|
|
@ -165,7 +198,7 @@ The default language in a code block is C#, but you can transition back to HTML:
|
|||
|
||||
### Explicit delimited transition
|
||||
|
||||
To define a sub-section of a code block that should render HTML, surround the characters for rendering with the Razor **\<text>** tag:
|
||||
To define a subsection of a code block that should render HTML, surround the characters for rendering with the Razor **\<text>** tag:
|
||||
|
||||
```cshtml
|
||||
@for (var i = 0; i < people.Length; i++)
|
||||
|
|
@ -175,9 +208,12 @@ To define a sub-section of a code block that should render HTML, surround the ch
|
|||
}
|
||||
```
|
||||
|
||||
Use this approach when you want to render HTML that isn't surrounded by an HTML tag. Without an HTML or Razor tag, you receive a Razor runtime error.
|
||||
Use this approach to render HTML that isn't surrounded by an HTML tag. Without an HTML or Razor tag, a Razor runtime error occurs.
|
||||
|
||||
The **\<text>** tag is also useful to control whitespace when rendering content. Only the content between the **\<text>** tags is rendered, and no whitespace before or after the **\<text>** tags appears in the HTML output.
|
||||
The **\<text>** tag is useful to control whitespace when rendering content:
|
||||
|
||||
* Only the content between the **\<text>** tag is rendered.
|
||||
* No whitespace before or after the **\<text>** tag appears in the HTML output.
|
||||
|
||||
### Explicit Line Transition with @:
|
||||
|
||||
|
|
@ -191,11 +227,13 @@ To render the rest of an entire line as HTML inside a code block, use the `@:` s
|
|||
}
|
||||
```
|
||||
|
||||
Without the `@:` in the code, you recieve a Razor runtime error.
|
||||
Without the `@:` in the code, a Razor runtime error is generated.
|
||||
|
||||
Warning: Extra `@` characters in a Razor file can cause cause compiler errors at statements later in the block. These compiler errors can be difficult to understand because the actual error occurs before the reported error. This error is common after combining multiple implicit/explicit expressions into a single code block.
|
||||
|
||||
## Control Structures
|
||||
|
||||
Control structures are an extension of code blocks. All aspects of code blocks (transitioning to markup, inline C#) also apply to the following structures.
|
||||
Control structures are an extension of code blocks. All aspects of code blocks (transitioning to markup, inline C#) also apply to the following structures:
|
||||
|
||||
### Conditionals @if, else if, else, and @switch
|
||||
|
||||
|
|
@ -225,7 +263,7 @@ else
|
|||
}
|
||||
```
|
||||
|
||||
You can use a switch statement like this:
|
||||
The following markup shows how to use a switch statement:
|
||||
|
||||
```cshtml
|
||||
@switch (value)
|
||||
|
|
@ -244,7 +282,7 @@ You can use a switch statement like this:
|
|||
|
||||
### Looping @for, @foreach, @while, and @do while
|
||||
|
||||
You can render templated HTML with looping control statements. To render a list of people:
|
||||
Templated HTML can be rendered with looping control statements. To render a list of people:
|
||||
|
||||
```cshtml
|
||||
@{
|
||||
|
|
@ -257,7 +295,7 @@ You can render templated HTML with looping control statements. To render a list
|
|||
}
|
||||
```
|
||||
|
||||
You can use any of the following looping statements:
|
||||
The following looping statements are supported:
|
||||
|
||||
`@for`
|
||||
|
||||
|
|
@ -310,7 +348,8 @@ You can use any of the following looping statements:
|
|||
|
||||
### Compound @using
|
||||
|
||||
In C#, a `using` statement is used to ensure an object is disposed. In Razor, the same mechanism is used to create HTML Helpers that contain additional content. For instance, you can utilize HTML Helpers to render a form tag with the `@using` statement:
|
||||
In C#, a `using` statement is used to ensure an object is disposed. In Razor, the same mechanism is used to create HTML Helpers that contain additional content. In the following code, HTML Helpers render a form tag with the `@using` statement:
|
||||
|
||||
|
||||
```cshtml
|
||||
@using (Html.BeginForm())
|
||||
|
|
@ -323,7 +362,7 @@ In C#, a `using` statement is used to ensure an object is disposed. In Razor, th
|
|||
}
|
||||
```
|
||||
|
||||
You can also perform scope-level actions with [Tag Helpers](xref:mvc/views/tag-helpers/intro).
|
||||
Scope-level actions can be performed with [Tag Helpers](xref:mvc/views/tag-helpers/intro).
|
||||
|
||||
### @try, catch, finally
|
||||
|
||||
|
|
@ -412,7 +451,7 @@ The `@model` directive specifies the type of the model passed to a view:
|
|||
@model TypeNameOfModel
|
||||
```
|
||||
|
||||
If you create an ASP.NET Core MVC app with individual user accounts, the *Views/Account/Login.cshtml* view contains the following model declaration:
|
||||
In an ASP.NET Core MVC app created with individual user accounts, the *Views/Account/Login.cshtml* view contains the following model declaration:
|
||||
|
||||
```cshtml
|
||||
@model LoginViewModel
|
||||
|
|
@ -430,17 +469,17 @@ Razor exposes a `Model` property for accessing the model passed to the view:
|
|||
<div>The Login Email: @Model.Email</div>
|
||||
```
|
||||
|
||||
The `@model` directive specifies the type of this property. The directive specifies the `T` in `RazorPage<T>` that the generated class that your view derives from. If you don't specify the `@model` directive, the `Model` property is of type `dynamic`. The value of the model is passed from the controller to the view. See [Strongly typed models and the @model keyword](xref:tutorials/first-mvc-app/adding-model#strongly-typed-models-keyword-label) for more information.
|
||||
The `@model` directive specifies the type of this property. The directive specifies the `T` in `RazorPage<T>` that the generated class that the view derives from. If the `@model` directive iisn't specified, the `Model` property is of type `dynamic`. The value of the model is passed from the controller to the view. For more information, see [Strongly typed models and the @model keyword.
|
||||
|
||||
### @inherits
|
||||
|
||||
The `@inherits` directive gives you full control of the class your view inherits:
|
||||
The `@inherits` directive provides full control of the class the view inherits:
|
||||
|
||||
```cshtml
|
||||
@inherits TypeNameOfClassToInheritFrom
|
||||
```
|
||||
|
||||
The following is a custom Razor page type:
|
||||
The following code is a custom Razor page type:
|
||||
|
||||
[!code-csharp[Main](razor/sample/Classes/CustomRazorPage.cs)]
|
||||
|
||||
|
|
@ -454,11 +493,11 @@ The code renders the following HTML:
|
|||
<div>Custom text: Gardyloo! - A Scottish warning yelled from a window before dumping a slop bucket on the street below.</div>
|
||||
```
|
||||
|
||||
You can't use `@model` and `@inherits` in the same view. You can have `@inherits` in a *_ViewImports.cshtml* file that the view imports:
|
||||
`@model` and `@inherits` can be used in the same view. `@inherits` can be in a *_ViewImports.cshtml* file that the view imports:
|
||||
|
||||
[!code-cshtml[Main](razor/sample/Views/_ViewImportsModel.cshtml)]
|
||||
|
||||
The following is an example of a strongly-typed view:
|
||||
The following code is an example of a strongly-typed view:
|
||||
|
||||
[!code-cshtml[Main](razor/sample/Views/Home/Login1.cshtml)]
|
||||
|
||||
|
|
@ -471,11 +510,12 @@ If "rick@contoso.com" is passed in the model, the view generates the following H
|
|||
|
||||
### @inject
|
||||
|
||||
The `@inject` directive enables you to inject a service from your [service container](xref:fundamentals/dependency-injection) into your view. See [Dependency injection into views](xref:mvc/views/dependency-injection) for more information.
|
||||
|
||||
The `@inject` directive enables the Razor Page to inject a service from the [service container](xref:fundamentals/dependency-injection) into a view. For more information, see [Dependency injection into views](xref:mvc/views/dependency-injection).
|
||||
|
||||
### @functions
|
||||
|
||||
The `@functions` directive enables you to add function-level content to a view:
|
||||
The `@functions` directive enables a Razor Page to add function-level content to a view:
|
||||
|
||||
```cshtml
|
||||
@functions { // C# Code }
|
||||
|
|
@ -497,7 +537,7 @@ The following code is the generated Razor C# class:
|
|||
|
||||
### @section
|
||||
|
||||
The `@section` directive is used in conjunction with the [layout](xref:mvc/views/layout) to enable views to render content in different parts of the HTML page. See [Sections](xref:mvc/views/layout#layout-sections-label) for more information.
|
||||
The `@section` directive is used in conjunction with the [layout](xref:mvc/views/layout) to enable views to render content in different parts of the HTML page. For more information, see [Sections](xref:mvc/views/layout#layout-sections-label).
|
||||
|
||||
## Tag Helpers
|
||||
|
||||
|
|
@ -548,7 +588,7 @@ C# Razor keywords must be double-escaped with `@(@C# Razor Keyword)` (for exampl
|
|||
|
||||
## Viewing the Razor C# class generated for a view
|
||||
|
||||
Add the following class to your ASP.NET Core MVC project:
|
||||
Add the following class to the ASP.NET Core MVC project:
|
||||
|
||||
[!code-csharp[Main](razor/sample/Utilities/CustomTemplateEngine.cs)]
|
||||
|
||||
|
|
@ -566,7 +606,12 @@ The Razor view engine performs case-sensitive lookups for views. However, the ac
|
|||
|
||||
* File based source:
|
||||
* On operating systems with case insensitive file systems (for example, Windows), physical file provider lookups are case insensitive. For example, `return View("Test")` results in matches for */Views/Home/Test.cshtml*, */Views/home/test.cshtml*, and any other casing variant.
|
||||
* On case sensitive file systems (for example, Linux, OSX, and with `EmbeddedFileProvider`), lookups are case sensitive. For example, `return View("Test")` specifically matches */Views/Home/Test.cshtml*.
|
||||
* On case-sensitive file systems (for example, Linux, OSX, and with `EmbeddedFileProvider`), lookups are case-sensitive. For example, `return View("Test")` specifically matches */Views/Home/Test.cshtml*.
|
||||
* Precompiled views: With ASP.Net Core 2.0 and later, looking up precompiled views is case insensitive on all operating systems. The behavior is identical to physical file provider's behavior on Windows. If two precompiled views differ only in case, the result of lookup is non-deterministic.
|
||||
|
||||
Developers are encouraged to match the casing of file and directory names to the casing of area, controller, and action names. This ensures your deployments will find their views regardless of the underlying file system.
|
||||
Developers are encouraged to match the casing of file and directory names to the casing of:
|
||||
|
||||
* Area, controller, and action names.
|
||||
* Razor Pages.
|
||||
|
||||
Matching case ensures the deployments find their views regardless of the underlying file system.
|
||||
|
|
|
|||
Loading…
Reference in New Issue