From e19d25bf311f75ecff234a790f8b9b759867e1ae Mon Sep 17 00:00:00 2001 From: pkellner Date: Thu, 16 Feb 2017 12:23:28 -0800 Subject: [PATCH 01/14] Put in more reasonable cache times for examples. --- .../tag-helpers/built-in/AnchorTagHelper.md | 2 +- .../tag-helpers/built-in/CacheTagHelper.md | 13 +++++-------- .../tag-helpers/built-in/ImageTagHelper.md | 18 ++++++++++++++++-- 3 files changed, 22 insertions(+), 11 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index 8280591ac235..5c51bd9dc8db 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -182,7 +182,7 @@ The domain in the example is localhost, but the Anchor Tag Helper uses the websi - - - -## Additional Resources +## Resources * [Areas](xref:mvc/controllers/areas) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md index 60d57467d39a..83e82f1628d6 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md @@ -80,7 +80,7 @@ Usage Example: | Attribute Type | Example Value | |---------------- |---------------- | -| TimeSpan | "@TimeSpan.FromSeconds(10)" | +| TimeSpan | "@TimeSpan.FromSeconds(120)" | Sets the length of time from the first request time to cache the contents. @@ -88,7 +88,7 @@ Sets the length of time from the first request time to cache the contents. Usage Example: ```html - + Current Time Inside Cache Tag Helper: @DateTime.Now ``` @@ -99,7 +99,7 @@ Usage Example: | Attribute Type | Example Value | |---------------- |---------------- | -| TimeSpan | "@TimeSpan.FromSeconds(5)" | +| TimeSpan | "@TimeSpan.FromSeconds(60)" | Sets the time that a cache entry should be evicted if it has not been accessed. @@ -107,7 +107,7 @@ Sets the time that a cache entry should be evicted if it has not been accessed. Usage Example: ```html - + Current Time Inside Cache Tag Helper: @DateTime.Now ``` @@ -280,12 +280,9 @@ Usage Example: ``` -> [!WARNING] -> The `priority` attribute does not guarantee a specific level of cache retention. `CacheItemPriority` is only a suggestion to the Cache Provider. Setting this attribute to `NeverRemove` does not guarantee that the cache will not be evicted. `CacheItemPriority` sets the priority the cache evicts items under memory pressure. See [Additional Resources](#additional-resources) for more information. - The Cache Tag Helper is dependent on the the [memory cache service](xref:performance/caching/memory). The Cache Tag Helper adds the service if it has not been added. -## Additional Resources +## Resources * * diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md index c35069ccc49b..1f6ba0e29551 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md @@ -1,4 +1,18 @@ -# ImageTagHelper +title: Anchor Tag Helper | Microsoft Docs +author: Peter Kellner +description: Shows how to work with Image Tag Helper +keywords: ASP.NET Core,tag helper +ms.author: riande +manager: wpickett +ms.date: 02/14/2017 +ms.topic: article +ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a010 +ms.technology: aspnet +ms.prod: aspnet-core +uid: mvc/views/tag-helpers/builtin-th/ImageTagHelper +--- + +# ImageTagHelper By [Peter Kellner](http://peterkellner.net) @@ -40,7 +54,7 @@ To activate the Image Tag Helper, the src attribute is required on the `` e > [!NOTE] > The Image Tag Helper uses the `Cache` provider on the local web server to store the calculated `Sha512` of a given file. If the file is requested again the `Sha512` does not need to be recalculated. The Cache is invalidated by a file watcher that is attached to the file when the file's `Sha512` is calculated. -## Additional Resource +## Resources * From 9ce4629840f959f35402e854cbad5b7f705106ce Mon Sep 17 00:00:00 2001 From: pkellner Date: Thu, 16 Feb 2017 12:28:41 -0800 Subject: [PATCH 02/14] Added to ImageTagHelper.md a block on the top and guessed at updating assetid by incrementing 1. Renamed all Additional Resources to Resources per @DevGuard, fixed incorrect expires-sliding code example, removed warning about Cache NeverRemove. --- aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md index 1f6ba0e29551..2348af135260 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md @@ -6,7 +6,7 @@ ms.author: riande manager: wpickett ms.date: 02/14/2017 ms.topic: article -ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a010 +ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a013 ms.technology: aspnet ms.prod: aspnet-core uid: mvc/views/tag-helpers/builtin-th/ImageTagHelper From 00edd4d8cd2c818e014a5b72a4d21e9128d0cc4f Mon Sep 17 00:00:00 2001 From: pkellner Date: Thu, 16 Feb 2017 15:58:07 -0800 Subject: [PATCH 03/14] fixed blank lines below toc entry, made consistent "Additional resources", put back in warning about NeverRemove based on feedback from team: https://github.com/aspnet/Docs/pull/2698#issuecomment-280456257 --- .../mvc/views/tag-helpers/built-in/AnchorTagHelper.md | 3 +-- .../mvc/views/tag-helpers/built-in/CacheTagHelper.md | 7 +++++-- .../mvc/views/tag-helpers/built-in/ImageTagHelper.md | 6 +++--- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index 5c51bd9dc8db..0d3af0929abc 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -12,7 +12,6 @@ ms.technology: aspnet ms.prod: aspnet-core uid: mvc/views/tag-helpers/builtin-th/AnchorTagHelper --- - # Anchor Tag Helper By [Peter Kellner](http://peterkellner.net) @@ -182,7 +181,7 @@ The domain in the example is localhost, but the Anchor Tag Helper uses the websi - - - -## Resources +## Additional resources * [Areas](xref:mvc/controllers/areas) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md index 83e82f1628d6..d85a7915f162 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md @@ -12,7 +12,6 @@ ms.technology: aspnet ms.prod: aspnet-core uid: mvc/views/tag-helpers/builtin-th/CacheTagHelper --- - # Cache Tag Helper By [Peter Kellner](http://peterkellner.net) @@ -280,9 +279,13 @@ Usage Example: ``` +> [!WARNING] +> The `priority` attribute does not guarantee a specific level of cache retention. `CacheItemPriority` is only a suggestion. Setting this attribute to `NeverRemove` does not guarantee that the cache will always be retained. See [Additional Resources](#additional-resources) for more information. + + The Cache Tag Helper is dependent on the the [memory cache service](xref:performance/caching/memory). The Cache Tag Helper adds the service if it has not been added. -## Resources +## Additional resources * * diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md index 2348af135260..356116139d74 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md @@ -1,4 +1,5 @@ -title: Anchor Tag Helper | Microsoft Docs +--- +title: Anchor Tag Helper | Microsoft Docs author: Peter Kellner description: Shows how to work with Image Tag Helper keywords: ASP.NET Core,tag helper @@ -11,7 +12,6 @@ ms.technology: aspnet ms.prod: aspnet-core uid: mvc/views/tag-helpers/builtin-th/ImageTagHelper --- - # ImageTagHelper By [Peter Kellner](http://peterkellner.net) @@ -54,7 +54,7 @@ To activate the Image Tag Helper, the src attribute is required on the `` e > [!NOTE] > The Image Tag Helper uses the `Cache` provider on the local web server to store the calculated `Sha512` of a given file. If the file is requested again the `Sha512` does not need to be recalculated. The Cache is invalidated by a file watcher that is attached to the file when the file's `Sha512` is calculated. -## Resources +## Additional resources * From c2769b2942c464f584d1abf1e3bd649c84e11f07 Mon Sep 17 00:00:00 2001 From: Rick Anderson Date: Fri, 17 Feb 2017 17:04:40 -1000 Subject: [PATCH 04/14] clean up --- .../tag-helpers/built-in/AnchorTagHelper.md | 47 ++++++++++++------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index 0d3af0929abc..88c4336f3192 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -1,4 +1,4 @@ ---- +--- title: Anchor Tag Helper | Microsoft Docs author: Peter Kellner description: Shows how to work with Anchor Tag Helper @@ -17,9 +17,9 @@ uid: mvc/views/tag-helpers/builtin-th/AnchorTagHelper By [Peter Kellner](http://peterkellner.net) -The Anchor Tag Helper enhances the html anchor (``) tag. A new set of attributes are defined that work with the anchor tag. The link generated (on the `href` tag) is based on a combination of these new attributes that work together to form the final URL. That URL can include an optional protocol such as https. +The Anchor Tag Helper enhances the html anchor (``) tag by adding new attributes. The link generated (on the `href` tag) is created using the new attributes. That URL can include an optional protocol such as https. -The speaker controller used in attribute definitions below is shown here. +The speaker controller below is used in samples in this document.
**SpeakerController.cs** @@ -33,35 +33,43 @@ The speaker controller used in attribute definitions below is shown here. ### asp-controller -`asp-controller` is used to associate which controller will be used to generate the final URL. The only valid choices are controllers that exist in the current project. To get to a list of all speakers specifying `asp-controller="Speaker"` is required. If only the `asp-controller` and no `asp-action` is specified, the default asp-action will be the name of the the controller method calling this view page. +`asp-controller` is used to associate which controller will be used to generate the URL. The controllers specified must exist in the current project. The following code lists all speakers: [TODO complete markup] +`asp-controller="Speaker"` is required. + +If the `asp-controller` is specifed and `asp-action` is not, the default asp-action will be the controller method calling the view. - - - ### asp-action -`asp-action` is the name of the method in the controller that will be included in the final URL. That is, in the example, if the route to the Speaker Detail page is wanted, then the attribute should be set to `asp-action=Detail`. You should always set `asp-controller` when specifying `asp-action`. If no `asp-action` is specified then the default `asp-controller` will be the current executing controller. - +`asp-action` is the name of the action method in the controller that will be included in the final URL. For example, the folowing code gets the route to the Speaker Detail page: +TODO Complete markup `asp-action=Detail`. + `asp-controller` is required when specifying `asp-action`. - - - ### asp-route-{value} -`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as the parameter to pass into the route. For example, if a tag is created as follows: - +`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as the parameter to pass into the route. The following code: +[REVIEW - Doesn't this depend on the default route? ] `Speaker 11` -the `href` generated will be +[REVIEW - consider passing in @model.SpeakerID rather than hard coded values] + +generates the following HTML: `Speaker 11` -This is because a route was found that matched a single parameter "id" in the ```SpeakerController``` method ```Detail```. If there was no parameter match, say for example you created the tag helper +A route was found that matched a single parameter "id" in the ```SpeakerController``` method ```Detail```. + +In the following example, there is no matching parameter: `Ronald` -you would get generated the html +Which generates the following HTML: `Ronald` -This is because there was no route found that matched a controller that had a method named `Detail` with one string parameter titled `name`. +There was no route found that matched a controller that had a method named `Detail` with one string parameter titled `name`. - - - @@ -77,6 +85,11 @@ This is because there was no route found that matched a controller that had a me `asp-all-route-data` allows creating on a .NET context (that is, the running C# associated with your Razor view) a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key. +Can't you just say: +`asp-all-route-data` allows creating a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key. + +[If not you need to explain that better in shorter sentences.] + As the example below shows, an inline dictionary is created and the data is passed to the razor view. The data could also be passed in with your model to keep the Razor view simpler. ``` @@ -92,19 +105,19 @@ As the example below shows, an inline dictionary is created and the data is pass asp-all-route-data="dict">SpeakerEvals ``` -The code that this generates looks as follows: +The code above generates the following HTML: ``` http://localhost/Speaker/EvaluationsCurrent?speakerId=11¤tYear=true ``` -When the link is clicked, this will call the controller method `EvaluationsCurrent` because that controller has two string parameters that match what has been created from the `asp-all-route-data` dictionary. +When the link is clicked, the controller method `EvaluationsCurrent`is called: It is called because that controller has two string parameters that match what has been created from the `asp-all-route-data` dictionary. - - - ### asp-fragment -`asp-fragment` defines a URL fragment to append to the URL. The Anchor Tag Helper will add the hash character (#) automatically. If you create a tag: +`asp-fragment` defines a URL fragment to append to the URL. The Anchor Tag Helper will add the hash character (#). If you create a tag: ``` About``` From ee26301eac049b614fbd3e98a699cecb3f860d72 Mon Sep 17 00:00:00 2001 From: pkellner Date: Sat, 18 Feb 2017 08:33:05 -0500 Subject: [PATCH 05/14] created Distributed and Environment Tag Helper Doc Pages and worked on environment. --- .../built-in/DistributedCacheTagHelper.md | 295 ++++++++++++++++++ .../built-in/EnvironmentTagHelper.md | 45 +++ 2 files changed, 340 insertions(+) create mode 100644 aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md create mode 100644 aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md new file mode 100644 index 000000000000..9f6cf6bb1c12 --- /dev/null +++ b/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md @@ -0,0 +1,295 @@ +--- +title: Distributed Cache Tag Helper | Microsoft Docs +author: Peter Kellner +description: Shows how to work with Cache Tag Helper +keywords: ASP.NET Core,tag helper +ms.author: riande +manager: wpickett +ms.date: 02/14/2017 +ms.topic: article +ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a012 +ms.technology: aspnet +ms.prod: aspnet-core +uid: mvc/views/tag-helpers/builtin-th/CacheTagHelper +--- +# Cache Tag Helper + +By [Peter Kellner](http://peterkellner.net) + + +The Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET Core app by caching its content to the internal ASP.NET Core cache provider. + +A simple example that shows the Cache Tag Helper in action sets the current time in its content area. The Razor View Engine sets the default `expires-after` to twenty minutes, which is the default if you specify no additional attributes. + +The following Razor markup caches the date/time: + +```html +@DateTime.Now +``` + +The first request to the page that contains `CacheTagHelper` will display the current date/time. Additional requests will show the cached value until the cache expires (default 20 minutes) or is evicted by memory pressure. + +You can set the cache duration with the following attributes: + +## Cache Tag Helper Attributes + +- - - + +### enabled + + +| Attribute Type | Valid Values | +|---------------- |---------------- | +| boolean | "true" (default) | +| | "false" | + + +Determines whether the content enclosed by the Cache Tag Helper is cached. The default is `true`. If set to `false`, regardless of what other attributes are specified, this Cache Tag Helper will have no caching effect on the rendered output. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### expires-on + +| Attribute Type | Example Value | +|---------------- |---------------- | +| DateTimeOffset | "@new DateTime(2025,1,29,17,02,0)" | + + +Sets an absolute expiration date. The example below will cache the contents of the Cache Tag Helper until 5:02 PM on January 29, 2025. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### expires-after + +| Attribute Type | Example Value | +|---------------- |---------------- | +| TimeSpan | "@TimeSpan.FromSeconds(120)" | + + +Sets the length of time from the first request time to cache the contents. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### expires-sliding + +| Attribute Type | Example Value | +|---------------- |---------------- | +| TimeSpan | "@TimeSpan.FromSeconds(60)" | + + +Sets the time that a cache entry should be evicted if it has not been accessed. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### vary-by-header + +| Attribute Type | Example Values | +|---------------- |---------------- | +| String | "User-Agent" | +| | "User-Agent,content-encoding" | + +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below monitors the header value `User-Agent`, which will cache the content for every different `User-Agent` presented to the web server. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### vary-by-query + +| Attribute Type | Example Values | +|---------------- |---------------- | +| String | "Make" | +| | "Make,Model" | + +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below looks at the values of `Make` and `Model`. + +Usage Example: + +``` +html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### vary-by-route + +| Attribute Type | Example Values | +|---------------- |---------------- | +| String | "Make" | +| | "Make,Model" | + +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. +Usage Example: + +*Startup.cs* + +```csharp +routes.MapRoute( + name: "default", + template: "{controller=Home}/{action=Index}/{Make?}/{Model?}"); +``` + +*Index.cshtml* + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### vary-by-cookie + +| Attribute Type | Example Values | +|---------------- |---------------- | +| String | ".AspNetCore.Identity.Application" | +| | ".AspNetCore.Identity.Application,HairColor" | + +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below looks at the cookie associated with asp.net Identity. When a user is authenticated the request cookie to be set which triggers a cache refresh. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +```` + +- - - + +### vary-by-user + +| Attribute Type | Example Values | +|---------------- |---------------- | +| Boolean | "true" | +| | "false" (default) | + +Specifies whether or not the cache should reset when the logged-in user (or Context Principal) changes. The current user is also known as the Request Context Principal and can be viewed in a Razor view by referencing `@User.Identity.Name`. + +The example below looks at the current logged in user. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +> [!NOTE] +> Using the attribute `vary-by-user` maintains the contents in cache through a log-in and log-out cycle. When using `vary-by-cookie` which references the `.AspNetCore.Identity.Application` as shown above, a log-in and log-out action invalidates the cache for the same authenticated user (because a new cookie value is generated). If no user is authenticated, the state is considered a valid. [REVIEW, don't understand this] This means that no logged-in user is one cache state, and the contents will be maintained for that condition as well. + +- - - + +### vary-by + +| Attribute Type | Example Values | +|---------------- |---------------- | +| String | "@Model" | + + +Allows for customization of what data gets cached. When the object referenced by the attribute's string value changes, the content of the Cache Tag Helper is updated. Often a string-concatenation of model values are assigned to this attribute. Effectively, that means an update to any of the concatenated values invalidates the cache. + +The example below assumes the controller method rendering the view sums the integer value of the two route parameters, `myParam1` and `myParam2`, and returns that as the single model property. When this sum changes, the content of the Cache Tag Helper is rendered and cachee again. + +Usage Example: + + +*Controller* + +```csharp +public IActionResult Index(string myParam1,string myParam2,string myParam3) +{ + int num1; + int num2; + int.TryParse(myParam1, out num1); + int.TryParse(myParam2, out num2); + return View(viewName, num1 + num2); +} +``` + +*Index.cshtml* + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +- - - + +### priority + +| Attribute Type | Example Values | +|---------------- |---------------- | +| CacheItemPriority | "High" | +| | "Low" | +| | "NeverRemove" | +| | "Normal" | + +Provides cache eviction guidance to the built-in cache provider. The web server will evict `Low` cache entries first when it's under memory pressure. + +Usage Example: + +```html + + Current Time Inside Cache Tag Helper: @DateTime.Now + +``` + +> [!WARNING] +> The `priority` attribute does not guarantee a specific level of cache retention. `CacheItemPriority` is only a suggestion. Setting this attribute to `NeverRemove` does not guarantee that the cache will always be retained. See [Additional Resources](#additional-resources) for more information. + + +The Cache Tag Helper is dependent on the the [memory cache service](xref:performance/caching/memory). The Cache Tag Helper adds the service if it has not been added. + +## Additional resources + +* +* + + + + diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md new file mode 100644 index 000000000000..be937bff5d4b --- /dev/null +++ b/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md @@ -0,0 +1,45 @@ +--- +title: Environment Tag Helper | Microsoft Docs +author: Peter Kellner +description: ASP.Net Core Environment Tag Helper defined including all properties +keywords: ASP.NET Core,tag helper +ms.author: riande +manager: wpickett +ms.date: 02/14/2017 +ms.topic: article +ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a0XX +ms.technology: aspnet +ms.prod: aspnet-core +uid: mvc/views/tag-helpers/builtin-th/EnvironmentTagHelper +--- +# Environment Tag Helper + +NOTETOSELF: +EnvironmentName Staging,Development,Production +HostingEnvironment.EnvironmentName + +By [Peter Kellner](http://peterkellner.net) + +The Environment Tag Helper conditionally renders its enclosed content based on the current hosting environment. Its single attribute `names` is a comma separated list of environment names that if any match to the current environment, will trigger the enclosed content to be rendered. + +## Environment Tag Helper Attributes + +### names + +Accepts a single hosting environment name or a comma-separated list of hosting environment names that trigger the rendering of the enclosed content. + +These value(s) are compared to the current value returned from the ASP.NET Core static property `HostingEnvironment.EnvironmentName`. This value will be **Staging**, **Development** or **Production**. The comparison ignores case. + +An example of a valid `environment` tag helper is: + +```html + + HostingEnvironment.EnvironmentName is Staging or Production + +``` + +## Additional resources + +* + + From 561ff5c34024e02ece264d8e6f8deeb5b678d85a Mon Sep 17 00:00:00 2001 From: pkellner Date: Mon, 20 Feb 2017 19:27:11 -0800 Subject: [PATCH 06/14] Reworked sections from @rick-anderson previous commit and removed review comments. --- .../tag-helpers/built-in/AnchorTagHelper.md | 105 +++++++++++++----- 1 file changed, 80 insertions(+), 25 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index 88c4336f3192..9c6eb38945ce 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -33,43 +33,104 @@ The speaker controller below is used in samples in this document. ### asp-controller -`asp-controller` is used to associate which controller will be used to generate the URL. The controllers specified must exist in the current project. The following code lists all speakers: [TODO complete markup] -`asp-controller="Speaker"` is required. +`asp-controller` is used to associate which controller will be used to generate the URL. The controllers specified must exist in the current project. The following code lists all speakers: -If the `asp-controller` is specifed and `asp-action` is not, the default asp-action will be the controller method calling the view. +``` +All Speakers +``` + +The generated URL will be + +``` +All Speakers +``` + +If the `asp-controller` is specified and `asp-action` is not, the default asp-action will be the controller method calling the view. - - - ### asp-action -`asp-action` is the name of the action method in the controller that will be included in the final URL. For example, the folowing code gets the route to the Speaker Detail page: -TODO Complete markup `asp-action=Detail`. - `asp-controller` is required when specifying `asp-action`. +`asp-action` is the name of the action method in the controller that will be included in the final URL. For example, the following code gets the route to the Speaker Detail page: + +``` +Speaker Detail +``` + +The generated URL will be + +``` +Speaker Detail +``` + +If no `asp-controller` attribute is specified, the default controller calling the view will be used. + +If the attribute `asp-action` is `Index`, then no action is appended to the URL leading to the default `Index` method being called. The action specified must exist in the controller referenced or defaulted.a - - - ### asp-route-{value} -`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as the parameter to pass into the route. The following code: -[REVIEW - Doesn't this depend on the default route? ] -`Speaker 11` +`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as a potential route parameter. If a default route is not found, this route prefix will be appended to the generated href as a request parameter and value. Otherwise it will be substituted in the route template. -[REVIEW - consider passing in @model.SpeakerID rather than hard coded values] +Assuming you have a controller method defined as follows: -generates the following HTML: +```csharp +public IActionResult AnchorTagHelper(string id) +{ + var speaker = new SpeakerData() + { + SpeakerId = 12 + }; + return View(viewName, speaker); +} +``` + +and have the default route template defined in your **startup.cs** as follows: + +```csharp +app.UseMvc(routes => +{ + routes.MapRoute( + name: "default", + template: "{controller=Home}/{action=Index}/{id?}"); +}); + +``` + +The **cshtml** file that contains the Anchor Tag Helper necessary to use the **speaker** model parameter passed in from the controller to the view is as follows: + +```html +@model SpeakerData + + +SpeakerId: @Model.SpeakerId + +``` + +The generated html will then be as follows because **id** was found in the default route. -`Speaker 11` +```html +SpeakerId: 12 +``` -A route was found that matched a single parameter "id" in the ```SpeakerController``` method ```Detail```. +If the route prefix is not part of the routing template found, which is the case with the following **cshtml** file: -In the following example, there is no matching parameter: +```html +@model SpeakerData + + +SpeakerId: @Model.SpeakerId + +``` -`Ronald` +The generated html will then be as follows because **speakerid** was not found in the route matched: -Which generates the following HTML: -`Ronald` +```html +SpeakerId: 12 +``` -There was no route found that matched a controller that had a method named `Detail` with one string parameter titled `name`. +If either `asp-controller` or `asp-action` are not specified, then the same default processing is followed as is in the `asp-route` attribute. - - - @@ -83,14 +144,9 @@ There was no route found that matched a controller that had a method named `Deta ### asp-all-route-data -`asp-all-route-data` allows creating on a .NET context (that is, the running C# associated with your Razor view) a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key. - -Can't you just say: `asp-all-route-data` allows creating a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key. -[If not you need to explain that better in shorter sentences.] - -As the example below shows, an inline dictionary is created and the data is passed to the razor view. The data could also be passed in with your model to keep the Razor view simpler. +As the example below shows, an inline dictionary is created and the data is passed to the razor view. As an alternative, the data could also be passed in with your model. ``` @{ @@ -126,7 +182,6 @@ When the link is clicked, the controller method `EvaluationsCurrent`is called: I The generated URL will be - ``` http://localhost/Speaker/Evaluations#SpeakerEvaluations ``` From 48481a39de5bca49401734a57b34f3f3e6f547fe Mon Sep 17 00:00:00 2001 From: pkellner Date: Tue, 21 Feb 2017 15:03:54 -0800 Subject: [PATCH 07/14] Updated Anchor Tag Helper's definition of asp-action and asp-controller to be more explicit about defaults as well as say "href" instead of "final URL". --- .../tag-helpers/built-in/AnchorTagHelper.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index 9c6eb38945ce..b51e5b245a61 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -45,27 +45,33 @@ The generated URL will be All Speakers ``` -If the `asp-controller` is specified and `asp-action` is not, the default asp-action will be the controller method calling the view. +If the `asp-controller` is specified and `asp-action` is not, the default `asp-action` will be the default controller method of the currently executing view. That is, in the above example, if `asp-action` is left out, and this Anchor Tag Helper generated from the Home index view (**/Home**), the generated markup will be: + + +```html +All Speakers +``` - - - ### asp-action -`asp-action` is the name of the action method in the controller that will be included in the final URL. For example, the following code gets the route to the Speaker Detail page: +`asp-action` is the name of the action method in the controller that will be included in the generated `href`. For example, the following code set the generated `href` to point to the speaker detail page: -``` +```html Speaker Detail ``` The generated URL will be -``` +```html Speaker Detail ``` -If no `asp-controller` attribute is specified, the default controller calling the view will be used. +If no `asp-controller` attribute is specified, the default controller calling the view executing the current view will be used. -If the attribute `asp-action` is `Index`, then no action is appended to the URL leading to the default `Index` method being called. The action specified must exist in the controller referenced or defaulted.a +If the attribute `asp-action` is `Index`, then no action is appended to the URL, leading to the default `Index` method being called. The action specified (or defaulted), must exist in the controller referenced in `asp-controller`. + - - - ### asp-route-{value} From d5b124ccd58ef9854805983f8e444b68bfc332db Mon Sep 17 00:00:00 2001 From: pkellner Date: Tue, 21 Feb 2017 16:34:28 -0800 Subject: [PATCH 08/14] I realized that asp-all-route-data also behaves like asp-route-* with routing parameters so I updated the doc to reflect that. --- aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index b51e5b245a61..6307f1c4a5c1 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -175,6 +175,8 @@ http://localhost/Speaker/EvaluationsCurrent?speakerId=11¤tYear=true When the link is clicked, the controller method `EvaluationsCurrent`is called: It is called because that controller has two string parameters that match what has been created from the `asp-all-route-data` dictionary. +If any keys in the dictionary match route parameters, those values will be substituted in the route as appropriate and the other non-matching values will be generated as request parameters. + - - - ### asp-fragment From d2c7085a1f11c453bf81f4a6fb90ef4e2390bf9d Mon Sep 17 00:00:00 2001 From: pkellner Date: Sat, 4 Mar 2017 07:51:16 -0800 Subject: [PATCH 09/14] Updated var-by-route definition following comments from Damien in old github post https://github.com/aspnet/Mvc/issues/1552 --- aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md index d85a7915f162..72b5a55080bc 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md @@ -159,7 +159,7 @@ html | String | "Make" | | | "Make,Model" | -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when the route data parameter value(s) change. Usage Example: *Startup.cs* From c45a2c99fbb4d5e4d5b8b7bccbe25506911729ff Mon Sep 17 00:00:00 2001 From: pkellner Date: Mon, 6 Mar 2017 07:11:52 -0800 Subject: [PATCH 10/14] Cleanup of Tag Helper Docs --- .../tag-helpers/built-in/CacheTagHelper.md | 2 +- .../built-in/DistributedCacheTagHelper.md | 260 ++---------------- .../built-in/EnvironmentTagHelper.md | 9 +- .../mvc/views/tag-helpers/built-in/index.md | 4 +- 4 files changed, 28 insertions(+), 247 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md index d85a7915f162..43b63cf8f34f 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md @@ -1,5 +1,5 @@ --- -title: Anchor Tag Helper | Microsoft Docs +title: Cache Tag Helper | Microsoft Docs author: Peter Kellner description: Shows how to work with Cache Tag Helper keywords: ASP.NET Core,tag helper diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md index 9f6cf6bb1c12..f7eda81528da 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md @@ -7,286 +7,66 @@ ms.author: riande manager: wpickett ms.date: 02/14/2017 ms.topic: article -ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a012 +ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a022 ms.technology: aspnet ms.prod: aspnet-core -uid: mvc/views/tag-helpers/builtin-th/CacheTagHelper +uid: mvc/views/tag-helpers/builtin-th/DistributedCacheTagHelper --- -# Cache Tag Helper +# Distributed Cache Tag Helper By [Peter Kellner](http://peterkellner.net) -The Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET Core app by caching its content to the internal ASP.NET Core cache provider. +The Distributed Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET Core app by caching its content to a distributed cache source. -A simple example that shows the Cache Tag Helper in action sets the current time in its content area. The Razor View Engine sets the default `expires-after` to twenty minutes, which is the default if you specify no additional attributes. +The Distributed Cache Tag Helper inherits from the same base class as the Cache Tag Helper. All attributes associated with the Cache Tag Helper will also work on the Distributed Tag Helper. -The following Razor markup caches the date/time: -```html -@DateTime.Now -``` - -The first request to the page that contains `CacheTagHelper` will display the current date/time. Additional requests will show the cached value until the cache expires (default 20 minutes) or is evicted by memory pressure. - -You can set the cache duration with the following attributes: - -## Cache Tag Helper Attributes - -- - - - -### enabled +The Distributed Cache Tag Helper follows the **Explicit Dependencies Principle** known as **Constructor Injection**. Specifically, the `IDistributedCache` interface container is passed into the Distributed Cache Tag Helper's constructor. If no specific concrete implementation of `IDistributedCache` has been created in `ConfigureServices`, usually found in startup.cs, then the Distributed Cache Tag Helper will use the same in-memory provider for storing cached data as the basic Cache Tag Helper. - -| Attribute Type | Valid Values | -|---------------- |---------------- | -| boolean | "true" (default) | -| | "false" | - - -Determines whether the content enclosed by the Cache Tag Helper is cached. The default is `true`. If set to `false`, regardless of what other attributes are specified, this Cache Tag Helper will have no caching effect on the rendered output. - -Usage Example: - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` - -- - - - -### expires-on - -| Attribute Type | Example Value | -|---------------- |---------------- | -| DateTimeOffset | "@new DateTime(2025,1,29,17,02,0)" | - - -Sets an absolute expiration date. The example below will cache the contents of the Cache Tag Helper until 5:02 PM on January 29, 2025. - -Usage Example: - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` +## Distributed Cache Tag Helper Attributes - - - -### expires-after - -| Attribute Type | Example Value | -|---------------- |---------------- | -| TimeSpan | "@TimeSpan.FromSeconds(120)" | - - -Sets the length of time from the first request time to cache the contents. - -Usage Example: +### enabled expires-on expires-after expires-sliding vary-by-header vary-by-query vary-by-route vary-by-cookie vary-by-user vary-by priority -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` +See Cache Tag Helper for definitions. Distributed Cache Tag Helper inherits from the same class as Cache Tag Helper so all these attributes are common from Cache Tag Helper. - - - -### expires-sliding +### name (required) | Attribute Type | Example Value | |---------------- |---------------- | -| TimeSpan | "@TimeSpan.FromSeconds(60)" | - - -Sets the time that a cache entry should be evicted if it has not been accessed. - -Usage Example: - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` - -- - - - -### vary-by-header - -| Attribute Type | Example Values | -|---------------- |---------------- | -| String | "User-Agent" | -| | "User-Agent,content-encoding" | - -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below monitors the header value `User-Agent`, which will cache the content for every different `User-Agent` presented to the web server. - -Usage Example: - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` - -- - - - -### vary-by-query - -| Attribute Type | Example Values | -|---------------- |---------------- | -| String | "Make" | -| | "Make,Model" | - -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below looks at the values of `Make` and `Model`. - -Usage Example: - -``` -html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` - -- - - - -### vary-by-route - -| Attribute Type | Example Values | -|---------------- |---------------- | -| String | "Make" | -| | "Make,Model" | - -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. -Usage Example: - -*Startup.cs* - -```csharp -routes.MapRoute( - name: "default", - template: "{controller=Home}/{action=Index}/{Make?}/{Model?}"); -``` - -*Index.cshtml* - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` - -- - - - -### vary-by-cookie - -| Attribute Type | Example Values | -|---------------- |---------------- | -| String | ".AspNetCore.Identity.Application" | -| | ".AspNetCore.Identity.Application,HairColor" | - -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below looks at the cookie associated with asp.net Identity. When a user is authenticated the request cookie to be set which triggers a cache refresh. - -Usage Example: - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -```` - -- - - +| string | "my-distributed-cache-unique-key-101" | -### vary-by-user - -| Attribute Type | Example Values | -|---------------- |---------------- | -| Boolean | "true" | -| | "false" (default) | - -Specifies whether or not the cache should reset when the logged-in user (or Context Principal) changes. The current user is also known as the Request Context Principal and can be viewed in a Razor view by referencing `@User.Identity.Name`. - -The example below looks at the current logged in user. +The required `name` attribute is used as a key to that cache stored for each instance of a Distributed Cache Tag Helper. Unlike the basic Cache Tag Helper that assigns a key to each Cache Tag Helper instance based on the Razor page name and location of the tag helper in the razor page, the Distributed Cache Tag Helper only bases it's key on the attribute `name` Usage Example: ```html - - Current Time Inside Cache Tag Helper: @DateTime.Now + + Time Inside Cache Tag Helper: @DateTime.Now ``` -> [!NOTE] -> Using the attribute `vary-by-user` maintains the contents in cache through a log-in and log-out cycle. When using `vary-by-cookie` which references the `.AspNetCore.Identity.Application` as shown above, a log-in and log-out action invalidates the cache for the same authenticated user (because a new cookie value is generated). If no user is authenticated, the state is considered a valid. [REVIEW, don't understand this] This means that no logged-in user is one cache state, and the contents will be maintained for that condition as well. - -- - - - -### vary-by - -| Attribute Type | Example Values | -|---------------- |---------------- | -| String | "@Model" | - +## Distributed Cache Tag Helper IDistributedCache Implementations -Allows for customization of what data gets cached. When the object referenced by the attribute's string value changes, the content of the Cache Tag Helper is updated. Often a string-concatenation of model values are assigned to this attribute. Effectively, that means an update to any of the concatenated values invalidates the cache. +There are two implementations of `IDistributedCache` built in to ASP.NET Core. One is based on **Sql Server** and the other is based on **Redis**. Details of these implementations can be found at the resource referenced below named "Working with a distributed cache". Both implementations involve setting an instance of `IDistributedCache` in ASP.NET Core's **startup.cs**. -The example below assumes the controller method rendering the view sums the integer value of the two route parameters, `myParam1` and `myParam2`, and returns that as the single model property. When this sum changes, the content of the Cache Tag Helper is rendered and cachee again. - -Usage Example: +There no tag attributes specifically associated with using any specific implementation of `IDistributedCache`. -*Controller* - -```csharp -public IActionResult Index(string myParam1,string myParam2,string myParam3) -{ - int num1; - int num2; - int.TryParse(myParam1, out num1); - int.TryParse(myParam2, out num2); - return View(viewName, num1 + num2); -} -``` - -*Index.cshtml* - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` - - - -### priority - -| Attribute Type | Example Values | -|---------------- |---------------- | -| CacheItemPriority | "High" | -| | "Low" | -| | "NeverRemove" | -| | "Normal" | - -Provides cache eviction guidance to the built-in cache provider. The web server will evict `Low` cache entries first when it's under memory pressure. - -Usage Example: - -```html - - Current Time Inside Cache Tag Helper: @DateTime.Now - -``` - -> [!WARNING] -> The `priority` attribute does not guarantee a specific level of cache retention. `CacheItemPriority` is only a suggestion. Setting this attribute to `NeverRemove` does not guarantee that the cache will always be retained. See [Additional Resources](#additional-resources) for more information. - -The Cache Tag Helper is dependent on the the [memory cache service](xref:performance/caching/memory). The Cache Tag Helper adds the service if it has not been added. ## Additional resources +* +* +* * * diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md index be937bff5d4b..b51cfb686377 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md @@ -7,7 +7,7 @@ ms.author: riande manager: wpickett ms.date: 02/14/2017 ms.topic: article -ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a0XX +ms.assetid: c045d485-d1dc-4cea-a675-46be83b7a035 ms.technology: aspnet ms.prod: aspnet-core uid: mvc/views/tag-helpers/builtin-th/EnvironmentTagHelper @@ -20,7 +20,7 @@ HostingEnvironment.EnvironmentName By [Peter Kellner](http://peterkellner.net) -The Environment Tag Helper conditionally renders its enclosed content based on the current hosting environment. Its single attribute `names` is a comma separated list of environment names that if any match to the current environment, will trigger the enclosed content to be rendered. +The Environment Tag Helper conditionally renders its enclosed content based on the current hosting environment. Its single attribute `names` is a comma separated list of environment names, that if any match to the current environment, will trigger the enclosed content to be rendered. ## Environment Tag Helper Attributes @@ -28,7 +28,7 @@ The Environment Tag Helper conditionally renders its enclosed content based on t Accepts a single hosting environment name or a comma-separated list of hosting environment names that trigger the rendering of the enclosed content. -These value(s) are compared to the current value returned from the ASP.NET Core static property `HostingEnvironment.EnvironmentName`. This value will be **Staging**, **Development** or **Production**. The comparison ignores case. +These value(s) are compared to the current value returned from the ASP.NET Core static property `HostingEnvironment.EnvironmentName`. This value is one of the following: **Staging**; **Development** or **Production**. The comparison ignores case. An example of a valid `environment` tag helper is: @@ -40,6 +40,7 @@ An example of a valid `environment` tag helper is: ## Additional resources -* +* +* diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/index.md b/aspnetcore/mvc/views/tag-helpers/built-in/index.md index 4f6208db71a4..6d79561691dd 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/index.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/index.md @@ -13,9 +13,9 @@ Microsoft has included multiple Tag Helpers that can be immediately used in .net **[Cache Tag Helper](CacheTagHelper.md)** -[comment]: **[DistributedTagHelper](builtin-th/AnchorTagHelper.md)** +**[Distributed Cache Tag Helper](DistributedCacheTagHelper.md)** -[comment]: **[EnvironmentTagHelper](builtin-th/EnvironmentTagHelper.md)** +**[Environment Tag Helper](EnvironmentTagHelper.md)** [comment]: **[FormActionTagHelper](builtin-th/FormActionTagHelper.md)** From 24276dfb91cdf5018a4f868f849db25e2d4e416a Mon Sep 17 00:00:00 2001 From: pkellner Date: Wed, 8 Mar 2017 15:49:49 -0800 Subject: [PATCH 11/14] changed author to pkellner from Peter Kellner per @mairaw --- .../mvc/views/tag-helpers/built-in/AnchorTagHelper.md | 2 +- aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md | 2 +- .../views/tag-helpers/built-in/DistributedCacheTagHelper.md | 2 +- .../mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md | 6 +----- aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md | 2 +- 5 files changed, 5 insertions(+), 9 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index 6307f1c4a5c1..ab7790ac5e6d 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -1,6 +1,6 @@ --- title: Anchor Tag Helper | Microsoft Docs -author: Peter Kellner +author: pkellner description: Shows how to work with Anchor Tag Helper keywords: ASP.NET Core,tag helper ms.author: riande diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md index 0b85b391f5df..423dac22121f 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md @@ -1,6 +1,6 @@ --- title: Cache Tag Helper | Microsoft Docs -author: Peter Kellner +author: pkellner description: Shows how to work with Cache Tag Helper keywords: ASP.NET Core,tag helper ms.author: riande diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md index f7eda81528da..70aacf9ae632 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/DistributedCacheTagHelper.md @@ -1,6 +1,6 @@ --- title: Distributed Cache Tag Helper | Microsoft Docs -author: Peter Kellner +author: pkellner description: Shows how to work with Cache Tag Helper keywords: ASP.NET Core,tag helper ms.author: riande diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md index b51cfb686377..117873747950 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/EnvironmentTagHelper.md @@ -1,6 +1,6 @@ --- title: Environment Tag Helper | Microsoft Docs -author: Peter Kellner +author: pkellner description: ASP.Net Core Environment Tag Helper defined including all properties keywords: ASP.NET Core,tag helper ms.author: riande @@ -14,10 +14,6 @@ uid: mvc/views/tag-helpers/builtin-th/EnvironmentTagHelper --- # Environment Tag Helper -NOTETOSELF: -EnvironmentName Staging,Development,Production -HostingEnvironment.EnvironmentName - By [Peter Kellner](http://peterkellner.net) The Environment Tag Helper conditionally renders its enclosed content based on the current hosting environment. Its single attribute `names` is a comma separated list of environment names, that if any match to the current environment, will trigger the enclosed content to be rendered. diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md index 356116139d74..0e2c14b198af 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/ImageTagHelper.md @@ -1,6 +1,6 @@ --- title: Anchor Tag Helper | Microsoft Docs -author: Peter Kellner +author: pkellner description: Shows how to work with Image Tag Helper keywords: ASP.NET Core,tag helper ms.author: riande From 95f9e53caed4be099e013f55da70c694ad5361da Mon Sep 17 00:00:00 2001 From: Rick Anderson Date: Wed, 21 Jun 2017 08:27:24 -0700 Subject: [PATCH 12/14] Update AnchorTagHelper.md --- aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md | 1 - 1 file changed, 1 deletion(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index ab7790ac5e6d..d7b888ca8b93 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -16,7 +16,6 @@ uid: mvc/views/tag-helpers/builtin-th/AnchorTagHelper By [Peter Kellner](http://peterkellner.net) - The Anchor Tag Helper enhances the html anchor (``) tag by adding new attributes. The link generated (on the `href` tag) is created using the new attributes. That URL can include an optional protocol such as https. The speaker controller below is used in samples in this document. From 2b539f8b2421c1cb9c1dfc0e6c1203e2e2577674 Mon Sep 17 00:00:00 2001 From: Rick Anderson Date: Fri, 30 Jun 2017 12:12:18 -0700 Subject: [PATCH 13/14] Update CacheTagHelper.md --- .../tag-helpers/built-in/CacheTagHelper.md | 56 +++++++++---------- 1 file changed, 26 insertions(+), 30 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md index 423dac22121f..cac4e10c1873 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/CacheTagHelper.md @@ -1,5 +1,5 @@ ---- -title: Cache Tag Helper | Microsoft Docs +--- +title: Cache Tag Helper in ASP.NET Core MVC author: pkellner description: Shows how to work with Cache Tag Helper keywords: ASP.NET Core,tag helper @@ -12,14 +12,14 @@ ms.technology: aspnet ms.prod: aspnet-core uid: mvc/views/tag-helpers/builtin-th/CacheTagHelper --- -# Cache Tag Helper +# Cache Tag Helper in ASP.NET Core MVC By [Peter Kellner](http://peterkellner.net) The Cache Tag Helper provides the ability to dramatically improve the performance of your ASP.NET Core app by caching its content to the internal ASP.NET Core cache provider. -A simple example that shows the Cache Tag Helper in action sets the current time in its content area. The Razor View Engine sets the default `expires-after` to twenty minutes, which is the default if you specify no additional attributes. +The Razor View Engine sets the default `expires-after` to twenty minutes. The following Razor markup caches the date/time: @@ -44,9 +44,9 @@ You can set the cache duration with the following attributes: | | "false" | -Determines whether the content enclosed by the Cache Tag Helper is cached. The default is `true`. If set to `false`, regardless of what other attributes are specified, this Cache Tag Helper will have no caching effect on the rendered output. +Determines whether the content enclosed by the Cache Tag Helper is cached. The default is `true`. If set to `false` this Cache Tag Helper will have no caching effect on the rendered output. -Usage Example: +Example: ```html @@ -63,9 +63,9 @@ Usage Example: | DateTimeOffset | "@new DateTime(2025,1,29,17,02,0)" | -Sets an absolute expiration date. The example below will cache the contents of the Cache Tag Helper until 5:02 PM on January 29, 2025. +Sets an absolute expiration date. The following example will cache the contents of the Cache Tag Helper until 5:02 PM on January 29, 2025. -Usage Example: +Example: ```html @@ -84,7 +84,7 @@ Usage Example: Sets the length of time from the first request time to cache the contents. -Usage Example: +Example: ```html @@ -103,7 +103,7 @@ Usage Example: Sets the time that a cache entry should be evicted if it has not been accessed. -Usage Example: +Example: ```html @@ -120,9 +120,9 @@ Usage Example: | String | "User-Agent" | | | "User-Agent,content-encoding" | -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below monitors the header value `User-Agent`, which will cache the content for every different `User-Agent` presented to the web server. +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The following example monitors the header value `User-Agent`. The example will cache the content for every different `User-Agent` presented to the web server. -Usage Example: +Example: ```html @@ -139,9 +139,9 @@ Usage Example: | String | "Make" | | | "Make,Model" | -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below looks at the values of `Make` and `Model`. +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when the header value changes. The following example looks at the values of `Make` and `Model`. -Usage Example: +Example: ``` html @@ -160,7 +160,7 @@ html | | "Make,Model" | Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when the route data parameter value(s) change. -Usage Example: +Example: *Startup.cs* @@ -187,9 +187,9 @@ routes.MapRoute( | String | ".AspNetCore.Identity.Application" | | | ".AspNetCore.Identity.Application,HairColor" | -Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when they change. The example below looks at the cookie associated with asp.net Identity. When a user is authenticated the request cookie to be set which triggers a cache refresh. +Accepts a single header value or a comma-separated list of header values that trigger a cache refresh when the header values(s) change. The following example looks at the cookie associated with ASP.NET Identity. When a user is authenticated the request cookie to be set which triggers a cache refresh. -Usage Example: +Example: ```html @@ -206,11 +206,11 @@ Usage Example: | Boolean | "true" | | | "false" (default) | -Specifies whether or not the cache should reset when the logged-in user (or Context Principal) changes. The current user is also known as the Request Context Principal and can be viewed in a Razor view by referencing `@User.Identity.Name`. +Specifies whether or not the cache should reset when the logged-in user (or Context Principal) changes. The current user is also known as the Request Context Principal and can be viewed in a Razor view by referencing `@User.Identity.Name`. -The example below looks at the current logged in user. +The following example looks at the current logged in user. -Usage Example: +Example: ```html @@ -218,8 +218,7 @@ Usage Example: ``` -> [!NOTE] -> Using the attribute `vary-by-user` maintains the contents in cache through a log-in and log-out cycle. When using `vary-by-cookie` which references the `.AspNetCore.Identity.Application` as shown above, a log-in and log-out action invalidates the cache for the same authenticated user (because a new cookie value is generated). If no user is authenticated, the state is considered a valid. [REVIEW, don't understand this] This means that no logged-in user is one cache state, and the contents will be maintained for that condition as well. +Using the attribute `vary-by-user` maintains the contents in cache through a log-in and log-out cycle. When using `vary-by-cookie` which references the `.AspNetCore.Identity.Application` as shown above, a log-in and log-out action invalidates the cache for the same authenticated user (because a new cookie value is generated). If no user is authenticated, the state is considered a valid. [REVIEW, don't understand this] This means that no logged-in user is one cache state, and the contents will be maintained for that condition as well. - - - @@ -232,12 +231,11 @@ Usage Example: Allows for customization of what data gets cached. When the object referenced by the attribute's string value changes, the content of the Cache Tag Helper is updated. Often a string-concatenation of model values are assigned to this attribute. Effectively, that means an update to any of the concatenated values invalidates the cache. -The example below assumes the controller method rendering the view sums the integer value of the two route parameters, `myParam1` and `myParam2`, and returns that as the single model property. When this sum changes, the content of the Cache Tag Helper is rendered and cachee again. - -Usage Example: +The following example assumes the controller method rendering the view sums the integer value of the two route parameters, `myParam1` and `myParam2`, and returns that as the single model property. When this sum changes, the content of the Cache Tag Helper is rendered and cached again. +Example: -*Controller* +Action: ```csharp public IActionResult Index(string myParam1,string myParam2,string myParam3) @@ -271,7 +269,7 @@ public IActionResult Index(string myParam1,string myParam2,string myParam3) Provides cache eviction guidance to the built-in cache provider. The web server will evict `Low` cache entries first when it's under memory pressure. -Usage Example: +Example: ```html @@ -279,9 +277,7 @@ Usage Example: ``` -> [!WARNING] -> The `priority` attribute does not guarantee a specific level of cache retention. `CacheItemPriority` is only a suggestion. Setting this attribute to `NeverRemove` does not guarantee that the cache will always be retained. See [Additional Resources](#additional-resources) for more information. - +The `priority` attribute does not guarantee a specific level of cache retention. `CacheItemPriority` is only a suggestion. Setting this attribute to `NeverRemove` does not guarantee that the cache will always be retained. See [Additional Resources](#additional-resources) for more information. The Cache Tag Helper is dependent on the the [memory cache service](xref:performance/caching/memory). The Cache Tag Helper adds the service if it has not been added. From 076af51da209ff506058d291df79d8b0333a40d6 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Fri, 30 Jun 2017 14:54:45 -0500 Subject: [PATCH 14/14] Minor tweaks --- .../tag-helpers/built-in/AnchorTagHelper.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md index d7b888ca8b93..1df9a19e03ad 100644 --- a/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md +++ b/aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md @@ -16,7 +16,7 @@ uid: mvc/views/tag-helpers/builtin-th/AnchorTagHelper By [Peter Kellner](http://peterkellner.net) -The Anchor Tag Helper enhances the html anchor (``) tag by adding new attributes. The link generated (on the `href` tag) is created using the new attributes. That URL can include an optional protocol such as https. +The Anchor Tag Helper enhances the HTML anchor (``) tag by adding new attributes. The link generated (on the `href` tag) is created using the new attributes. That URL can include an optional protocol such as https. The speaker controller below is used in samples in this document. @@ -38,13 +38,13 @@ The speaker controller below is used in samples in this document. All Speakers ``` -The generated URL will be +The generated URL will be: ``` All Speakers ``` -If the `asp-controller` is specified and `asp-action` is not, the default `asp-action` will be the default controller method of the currently executing view. That is, in the above example, if `asp-action` is left out, and this Anchor Tag Helper generated from the Home index view (**/Home**), the generated markup will be: +If the `asp-controller` is specified and `asp-action` is not, the default `asp-action` will be the default controller method of the currently executing view. That is, in the above example, if `asp-action` is left out, and this Anchor Tag Helper is generated from *HomeController*'s `Index` view (**/Home**), the generated markup will be: ```html @@ -61,7 +61,7 @@ If the `asp-controller` is specified and `asp-action` is not, the default `asp-a Speaker Detail ``` -The generated URL will be +The generated URL will be: ```html Speaker Detail @@ -75,7 +75,7 @@ If the attribute `asp-action` is `Index`, then no action is appended to the URL, ### asp-route-{value} -`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as a potential route parameter. If a default route is not found, this route prefix will be appended to the generated href as a request parameter and value. Otherwise it will be substituted in the route template. +`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as a potential route parameter. If a default route is not found, this route prefix will be appended to the generated href as a request parameter and value. Otherwise it will be substituted in the route template. Assuming you have a controller method defined as follows: @@ -90,7 +90,7 @@ public IActionResult AnchorTagHelper(string id) } ``` -and have the default route template defined in your **startup.cs** as follows: +And have the default route template defined in your **Startup.cs** as follows: ```csharp app.UseMvc(routes => @@ -112,7 +112,7 @@ The **cshtml** file that contains the Anchor Tag Helper necessary to use the **s ``` -The generated html will then be as follows because **id** was found in the default route. +The generated HTML will then be as follows because **id** was found in the default route. ```html SpeakerId: 12 @@ -128,7 +128,7 @@ If the route prefix is not part of the routing template found, which is the case ``` -The generated html will then be as follows because **speakerid** was not found in the route matched: +The generated HTML will then be as follows because **speakerid** was not found in the route matched: ```html @@ -143,7 +143,7 @@ If either `asp-controller` or `asp-action` are not specified, then the same defa `asp-route` provides a way to create a URL that links directly to a named route. Using routing attributes, a route can be named as shown in the `SpeakerController` and used in its `Evaluations` method. -`Name = "speakerevals"` tells the Anchor Tag Helper to generate a route directly to that controller method using the URL `/Speaker/Evaluations`. If `asp-controller` or `asp-action` is specified in addition to `asp-route`, the route generated may not be what you expect. `asp-route` should not be used with either of the attributes `asp-controller` or `asp-action` to avoid a route conflict. +`Name = "speakerevals"` tells the Anchor Tag Helper to generate a route directly to that controller method using the URL `/Speaker/Evaluations`. If `asp-controller` or `asp-action` is specified in addition to `asp-route`, the route generated may not be what you expect. `asp-route` should not be used with either of the attributes `asp-controller` or `asp-action` to avoid a route conflict. - - - @@ -172,7 +172,7 @@ The code above generates the following HTML: http://localhost/Speaker/EvaluationsCurrent?speakerId=11¤tYear=true ``` -When the link is clicked, the controller method `EvaluationsCurrent`is called: It is called because that controller has two string parameters that match what has been created from the `asp-all-route-data` dictionary. +When the link is clicked, the controller method `EvaluationsCurrent` is called. It is called because that controller has two string parameters that match what has been created from the `asp-all-route-data` dictionary. If any keys in the dictionary match route parameters, those values will be substituted in the route as appropriate and the other non-matching values will be generated as request parameters. @@ -187,19 +187,19 @@ If any keys in the dictionary match route parameters, those values will be subst asp-fragment="SpeakerEvaluations">About Speaker Evals ``` -The generated URL will be +The generated URL will be: ``` http://localhost/Speaker/Evaluations#SpeakerEvaluations ``` -Hash tags are useful when doing client side applications. They can be used for easy marking and searching in JavaScript for example. +Hash tags are useful when building client-side applications. They can be used for easy marking and searching in JavaScript, for example. - - - ### asp-area -`asp-area` sets the area name that ASP.NET Core uses to set the appropriate route. Below are examples of how the area attribute causes a remapping of routes. Setting `asp-area` to Blogs prefixes the directory `Areas/Blogs` to the routes of the associated controllers and views for this anchor tag. +`asp-area` sets the area name that ASP.NET Core uses to set the appropriate route. Below are examples of how the area attribute causes a remapping of routes. Setting `asp-area` to Blogs prefixes the directory `Areas/Blogs` to the routes of the associated controllers and views for this anchor tag. * Project name @@ -244,11 +244,11 @@ The generated HTML will include the areas segment and will be as follows: ### asp-protocol -The `asp-protocol` is for specifying a protocol (such as `https`) in your URL. An example Anchor Tag Helper that includes the protocol will look as follows. +The `asp-protocol` is for specifying a protocol (such as `https`) in your URL. An example Anchor Tag Helper that includes the protocol will look as follows: ```About``` -and will generate HTML as follows. +and will generate HTML as follows: ```About```