Pkellner built in th #2644
Pkellner built in th #2644
Conversation
…nce to SpeakerController.cs. Improved AnchorTagHelper.md documentation to be more consistent per docs guide.
Added Sample VS Project. Updated AnchorTagHelper.md to include refer…
…ution. Added new documentation for ImageTagHelper.md
…r and ImageTagHelper.
|
Hi @pkellner, I'm your friendly neighborhood .NET Foundation Pull Request Bot (You can call me DNFBOT). Thanks for your contribution! The agreement was validated by .NET Foundation and real humans are currently evaluating your PR. TTYL, DNFBOT; |
|
I'll review it by 10 Feb 2017 - thanks for your contributions |
|
@pkellner You've prob seen that I've sent in consistency PR's here and there. Do you want me to do a pass on it? If not, no worries. I'm just looking to make myself useful around here. |
|
@guardrex I'm not really the one to talk to here. I'm just helping out with docs. Sorry. |
|
@guardrex please review. |
| @@ -11,7 +11,7 @@ Microsoft has included 17 Tag Helpers that can be immediately used in .net Core | |||
|
|
|||
| **[AnchorTagHelper](builtin/resources/AnchorTagHelper.md)** | |||
|
|
|||
| [comment]: **[CacheTagHelper](builtin/resources/AnchorTagHelper.md)** | |||
| **[CacheTagHelper](builtin/resources/CacheTagHelper.md)** | |||
There was a problem hiding this comment.
Should the docs and the link text be titled with spaces? It would read better imo Anchor Tag Helper, Cache Tag Helper, etc.
There was a problem hiding this comment.
I would suggest leaving this as is because this is a list of Core Tag Helpers and their actual names. That is, this is not about in general "Cache" Tag Helpers because that might imply it covers the distributed cache tag helper which it does not. Happy to change, just IMHO.
There was a problem hiding this comment.
@Rick-Anderson suggested by following the format of the doc listed in #2644 (comment) that the TH's would be plainly named for reading purposes; but of course, they'll say what they want to do there. I think they read better in plain language.
There was a problem hiding this comment.
Hey @Rick-Anderson , could you give a quick opinion on this. @guardrex makes a good point that in the forms doc all the tag helpers are expanded out (Cache Tag Helper, not CacheTagHelper). I always do it the CacheTagHelper way but happy to change all my references, just want to make sure I get it right. -thanks
| @@ -8,41 +8,33 @@ By [Peter Kellner](http://peterkellner.net) | |||
|
|
|||
| The ```AnchorTagHelper``` enhances the html anchor (`<a ... ></a>`) 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 redirect URL. That URL can include an optional protocol such as https. | |||
There was a problem hiding this comment.
- Not that it necessarily hurts anything, but three backticks for codeblocks that break across lines and single backticks for in-text code.
- "redirect URL" has special meaning ... I think just "URL" there.
- This passage is a bit confusing. You need prior knowledge or to perhaps read the whole doc to understand that non-standard attributes are converted into standard attributes. I'd refactor this into a complete explanation, and it might even go into the parent document, since it pertains to many of the Tag Helpers.
There was a problem hiding this comment.
points 1 and 2 updated.
I've re-read the passage mentioned a few times and it seems OK to me. There is another section already written by Rick that introduced TH's. I don't see anything there that specifically talks about non-standard attributes being converted to standard attributes but I'm not sure that needs to be mentioned (can't hurt to add it there).
My assumption in writing all these built in TH docs it that the reader knows the basics of tag helpers. Valid assumption?
https://docs.microsoft.com/en-us/aspnet/core/mvc/views/tag-helpers/intro
There was a problem hiding this comment.
Yes, that was my point exactly. For my comment here, I may have assumed incorrectly that the reader doesn't know much (or anything) about TH's. That might be the wrong assumption. I can say ... I think this is fair ... that if the reader were to land on this doc and read that sentence ...
The link generated (on the href tag) is based on a combination of these new attributes that work together to form the final redirect URL.
... that they really wouldn't be able to understand what it means.
Whatever the case with all of that, I would remove the word "redirect" from "redirect URL" there at the end, since that has special meaning.
| @@ -8,41 +8,33 @@ By [Peter Kellner](http://peterkellner.net) | |||
|
|
|||
| The ```AnchorTagHelper``` enhances the html anchor (`<a ... ></a>`) 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 redirect URL. That URL can include an optional protocol such as https. | |||
|
|
|||
| For reference, the following ASP.NET ```startup.cs``` and ```SpeakerController.cs``` are defined as you would expect in a default Visual Studio .Net Core Web Project. | |||
| For reference, the following ASP.NET ```SpeakerController.cs``` is defined as you would expect in a default Visual Studio .Net Core Web Project. | |||
There was a problem hiding this comment.
- ".Net" to ".NET"
- TH's work outside of VS, so I'd drop mentioning the IDE
- The
SpeakerController.csfile isn't a default project file, so I wouldn't expect to see it 😁 ... but I know what you mean. I think you just need to rephrase it a little. You could just go with the old "The following example shows ... {insert description here of what it shows}:"
There was a problem hiding this comment.
Uh oh. I removed startup.cs from the pull request I believe I made. I'm thinking @guardrex reviewed what was already in the branch approved by @Rick-Anderson and not what was in my latest pull request. I'm guessing I'm not following the right protocol for things to be reviewed. Happy to update my process. LMK.
There was a problem hiding this comment.
One more comment/question here for both @Rick-Anderson and and @guardrex . Should we avoid mentioning Visual Studio? There are lots of mentions of VS in other Core docs. For example Identity: https://docs.microsoft.com/en-us/aspnet/core/security/authentication/identity doesn't need VS but it's mentioned a lot.
There was a problem hiding this comment.
My wild guess is not mention VS where it isn't explicitly required to do so. MS seems to want to embrace a full spectrum of IDE's that could be used to create ASP.NET Core apps.
|
|
||
| ## asp-controller | ||
| ## The attributes are defined as follows |
There was a problem hiding this comment.
I suggest instead of a sentence fragment heading to just use a simple section title, such as ## Attributes or ## Anchor Tag Helper attributes ... but the former might be better, since it's understood that the whole doc pertains to this one TH.
|
|
||
| - - - | ||
|
|
||
| ### 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. In our case, to get to a list of all speakers or speaker details you would specify ```asp-controller="Speaker"```. If you only specify ```asp-controller``` and no ```asp-action``` the URL will generate without an error but will likely not be what you expect. |
There was a problem hiding this comment.
Drop the first prepositional phrase and move the comma ... "To get to a list of all speakers or speaker details, you would ..."
If you only specify
asp-controllerand noasp-actionthe URL will generate without an error but will likely not be what you expect.
I find the construction a bit awkward ... "... will generate without ..." ... not a common way to phrase this thought in spoken English. Anyway ... the comma ... at least set the phrase off with a comma: "If you only specify asp-controller and no asp-action, the URL will ..."
There was a problem hiding this comment.
Made some changes tot he asp-controller section but not sure it's perfect.
| ## asp-action | ||
| - - - | ||
|
|
||
| ### 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 a URL will generate without an error but will likely not be what you expect. |
There was a problem hiding this comment.
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.
Choppy ... refactor the start of the sentence or break this into two sentences.
If no
asp-actionis specified then a URL will generate without an error but will likely not be what you expect.
Similar to above: Add a comma after the prepositional phrase and drop "then." Personally, I'd refactor the sentence for something other than the "will generate without" phrase, but that's up to you (and them ... the "real" editors! 😁)
| ## asp-route- | ||
| - - - | ||
|
|
||
| ### asp-route- | ||
|
|
||
| ```asp-route-``` is basically 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 you create a tag as follows: |
There was a problem hiding this comment.
- "wild card" to "wildcard" in IT contexts
- I'd add either an asterisk (
*) or a hint for the attribute ... eitherasp-route-*orasp-route-{value} - For
asp-route-id-="11"below ... no last dash there AFAIK. I think it should beasp-route-id="11". This occurs in a couple of spots here.
Below this line, I see ...
- href should receive backticks
- Codeblocks should break across lines
- The construction of this section seems a bit awkward to me with dangling phrases between code blocks. Personally, I'd clean it up a bit with complete sentences that set off the code examples with colons.
- "html" to "HTML"
| ## asp-route | ||
| - - - | ||
|
|
||
| ### asp-route | ||
|
|
||
| ```asp-route``` provides a way to create a URL that links directly to a named route. Using routing attributes, you can name your routes as shown in the Evaluations method above of the ```SpeakerController```. ```Name = "speakerevals"``` tells the AnchorTagHelper 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``` then the route generated will 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. |
There was a problem hiding this comment.
- Evaluations with backticks
as shown in the Evaluations method above of the
SpeakerController.
Phrasing would be clearer if it were ...
... as shown in the SpeakerController's Evaluations method above.
- "AnchorTagHelper" ... "Anchor Tag Helper"
- "... using the URL
/Speaker/Evaluations." ... but that's a fragment, so maybe say "using the route/Speaker/Evaluations"
If
asp-controllerorasp-actionis specified in addition toasp-routethen the route generated ...
Missing comma and drop "then"
"If asp-controller or asp-action is specified in addition to asp-route, the route generated ..." (comma + drop "then")
will not be what you expect.
The reader is bound to wonder, "What do I expect?" or "What will happen if I do this?" I think the problem should be explained and/or illustrated with an example.
There was a problem hiding this comment.
After researching more, I found reasonable defaults for action and controller methods so I'm updating docs to reflect that. I thought the defaults were not working as I would have expected but I was wrong.
| ## asp-all-route-data | ||
| - - - | ||
|
|
||
| ### asp-all-route-data | ||
|
|
||
| ```asp-all-route-data``` allows you to create on your current .net context (that is, the running c# associated with your razor page) a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key. As the example below shows, you can create an inline dictionary on your razor page and then create the ```AnchorTagHelper``` right after that. You could of course pass in the dictionary with your model or as your model. That avoids having extra c# code on your razor page and gives you better control of the data passed to your view. |
There was a problem hiding this comment.
asp-all-route-dataallows you to create on your current .net context (that is, the running c# associated with your razor page) a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key.
- ".net" to ".NET"
- "c#" to "C#"
- "razor page" to "Razor view" ("Razor page" has special meaning; Razor is a proper noun)
- It's confusing to inject that much parenthetical information (i.e., "that is ...") into the sentence. I think if you explain what the context is first, the sentence will become easier to digest.
You could of course pass in
@tdykstra will be fine with that 😁 (inside joke), but I try to avoid splitting verbs when it isn't necessary. How about just "Of course, you could pass in ..."
... data passed to your view.
Since the data will appear in the view, I wonder if this would go "data passed into your view."
There was a problem hiding this comment.
I think I simplified it. I don't particularly like the design of asp-all-route-data (making it hard to explain). I think the example is more important than the explanation.
| ## asp-fragment | ||
| - - - | ||
|
|
||
| ### asp-fragment | ||
|
|
||
| ```asp-fragment``` appends after a hash (```#```) tag at the end of the URL whatever the value assigned to it is. That is, if you create a tag |
There was a problem hiding this comment.
asp-fragmentappends after a hash (#) tag at the end of the URL whatever the value assigned to it is. That is, 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 (#) automatically. If you create a tag:
There was a problem hiding this comment.
@guardrex I'm confused about some of your changes that look like white space changes. Could you explain a little about how you changed "- - -" and line spacing?
|
|
||
| ### asp-area | ||
|
|
||
| ```asp-area``` sets the area name that ASP.NET core will use to set the appropriate route with. Below are examples of how the area attribute causes a remapping of routes. That is, by setting ```asp-area``` to Blogs will invoke the Areas functionality such that the directory Areas/Blogs will prefix the associated controllers and views for this anchor tag. |
There was a problem hiding this comment.
- "core" to "Core"
- "... will use to set the appropriate route with." ... prob goes against what they're doing with future tense and "with" at the end of the sentence always gives me a tooth ache [but @tdykstra will like it 😁 (another inside joke 🍺)]. How about "... that ASP.NET Core uses to create the appropriate route to an area."
That is, by setting
asp-areato Blogs will invoke the Areas functionality such that the directory Areas/Blogs will prefix the associated controllers and views for this anchor tag.
Setting asp-area to Blogs prefixes the directory Areas/Blogs to the routes of the associated controllers and views for this anchor tag.
There was a problem hiding this comment.
nice @guardrex . You said in about 12 words what took me about 30.
|
|
||
| ```asp-area``` allows for a razor view area to be associated with the hyperlink URL. That is, if you have a project setup in a similar fashion to the project pictured below, the link generated will include as its first segment the area you mention. | ||
| * wwwroot |
There was a problem hiding this comment.
Make wwwroot italics. Same below (I think) for any proper folder or file. Usually, they keep folders and files in italics wherever they appear in docs, including when they appear in lists and tables. @tdykstra will correct me if I'm mistaken.
| * Controllers | ||
|
|
||
|
|
||
|
|
||
| Specifying an area tag that is valid, such as ```area="Blogs"``` when referencing the ```AboutBlog.cshtml``` file will look like the following using the ```AnchorTagHelper```. |
There was a problem hiding this comment.
Comma after "file".
Again, I'd go with "Anchor Tag Helper" (in plain text) in all of these places where it has to be read.
There was a problem hiding this comment.
I'm going with the words separated out as much as I can when I find them.
| @@ -130,9 +151,9 @@ The generated HTML will include the areas segment and will be as follows: | |||
| > [!TIP] | |||
There was a problem hiding this comment.
- Convert this to a
> [!NOTE], as they don't want tips.
There was a problem hiding this comment.
Tips are fine, it's just overuse of them we want to avoid.
| @@ -130,9 +151,9 @@ The generated HTML will include the areas segment and will be as follows: | |||
| > [!TIP] | |||
| > For MVC Areas to work in your web application, the route template must include a reference to the area if it exists. That template (which is the second parameter of the ```routes.MapRoute``` method call) will look as follows: ```template: "{area:exists}/{controller=Home}/{action=Index}"```. | |||
There was a problem hiding this comment.
For MVC Areas to work in your web application, the route template must include a reference to the area if it exists. That template (which is the second parameter of the
routes.MapRoutemethod call) will look as follows:template: "{area:exists}/{controller=Home}/{action=Index}".
For MVC areas to work in your web application, the route template must include a reference to the area if it exists. That template, which is the second parameter of the routes.MapRoute method call, will appear as:
template: "{area:exists}/{controller=Home}/{action=Index}"
There was a problem hiding this comment.
@guardrex not sure how to get the template to work in the "[!TIP]" as a separate line.
|
|
||
|
|
||
| ## asp-protocol | ||
| ### asp-protocol | ||
|
|
There was a problem hiding this comment.
... protocol (such as https) in ...
to
... protocol, such as https, in ...
... will look as follows.
to
... will appear as:
|
I did that once for a note that was placed under a table of values. You can add an asterisk by escaping it with a backslash. |
| @@ -8,41 +8,33 @@ By [Peter Kellner](http://peterkellner.net) | |||
|
|
|||
| The ```AnchorTagHelper``` enhances the html anchor (`<a ... ></a>`) 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 redirect URL. That URL can include an optional protocol such as https. | |||
There was a problem hiding this comment.
points 1 and 2 updated.
I've re-read the passage mentioned a few times and it seems OK to me. There is another section already written by Rick that introduced TH's. I don't see anything there that specifically talks about non-standard attributes being converted to standard attributes but I'm not sure that needs to be mentioned (can't hurt to add it there).
My assumption in writing all these built in TH docs it that the reader knows the basics of tag helpers. Valid assumption?
https://docs.microsoft.com/en-us/aspnet/core/mvc/views/tag-helpers/intro
| @@ -8,41 +8,33 @@ By [Peter Kellner](http://peterkellner.net) | |||
|
|
|||
| The ```AnchorTagHelper``` enhances the html anchor (`<a ... ></a>`) 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 redirect URL. That URL can include an optional protocol such as https. | |||
|
|
|||
| For reference, the following ASP.NET ```startup.cs``` and ```SpeakerController.cs``` are defined as you would expect in a default Visual Studio .Net Core Web Project. | |||
| For reference, the following ASP.NET ```SpeakerController.cs``` is defined as you would expect in a default Visual Studio .Net Core Web Project. | |||
There was a problem hiding this comment.
Uh oh. I removed startup.cs from the pull request I believe I made. I'm thinking @guardrex reviewed what was already in the branch approved by @Rick-Anderson and not what was in my latest pull request. I'm guessing I'm not following the right protocol for things to be reviewed. Happy to update my process. LMK.
… helpers in progress. Anchor, Image and Cache.
There was a problem hiding this comment.
I've finished incorporating and comment on @guardrex 's edits and added a few of my own for Image, Anchor and Cache Tag Helpers. I've committed my changes to my forked GitHub repo. It looks like those automatically got added to the pull request I made here (#2644). is that true @Rick-Anderson ? In the BuiltIn.md file I changed the word "17" to "many". Is that reflected from my latest work?
|
|
||
| - - - | ||
|
|
||
| ### 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. In our case, to get to a list of all speakers or speaker details you would specify ```asp-controller="Speaker"```. If you only specify ```asp-controller``` and no ```asp-action``` the URL will generate without an error but will likely not be what you expect. |
There was a problem hiding this comment.
Made some changes tot he asp-controller section but not sure it's perfect.
| ## asp-route | ||
| - - - | ||
|
|
||
| ### asp-route | ||
|
|
||
| ```asp-route``` provides a way to create a URL that links directly to a named route. Using routing attributes, you can name your routes as shown in the Evaluations method above of the ```SpeakerController```. ```Name = "speakerevals"``` tells the AnchorTagHelper 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``` then the route generated will 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. |
There was a problem hiding this comment.
After researching more, I found reasonable defaults for action and controller methods so I'm updating docs to reflect that. I thought the defaults were not working as I would have expected but I was wrong.
| ## asp-all-route-data | ||
| - - - | ||
|
|
||
| ### asp-all-route-data | ||
|
|
||
| ```asp-all-route-data``` allows you to create on your current .net context (that is, the running c# associated with your razor page) a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key. As the example below shows, you can create an inline dictionary on your razor page and then create the ```AnchorTagHelper``` right after that. You could of course pass in the dictionary with your model or as your model. That avoids having extra c# code on your razor page and gives you better control of the data passed to your view. |
There was a problem hiding this comment.
I think I simplified it. I don't particularly like the design of asp-all-route-data (making it hard to explain). I think the example is more important than the explanation.
| ## asp-fragment | ||
| - - - | ||
|
|
||
| ### asp-fragment | ||
|
|
||
| ```asp-fragment``` appends after a hash (```#```) tag at the end of the URL whatever the value assigned to it is. That is, if you create a tag |
There was a problem hiding this comment.
@guardrex I'm confused about some of your changes that look like white space changes. Could you explain a little about how you changed "- - -" and line spacing?
|
|
||
| ### asp-area | ||
|
|
||
| ```asp-area``` sets the area name that ASP.NET core will use to set the appropriate route with. Below are examples of how the area attribute causes a remapping of routes. That is, by setting ```asp-area``` to Blogs will invoke the Areas functionality such that the directory Areas/Blogs will prefix the associated controllers and views for this anchor tag. |
There was a problem hiding this comment.
nice @guardrex . You said in about 12 words what took me about 30.
| @@ -0,0 +1,46 @@ | |||
| [Back To Built In Tag Helpers List](../../builtin.md) | |||
There was a problem hiding this comment.
@guardrex not following what to do. Leaving as is. Maybe some fancy link syntax?
|
|
||
| The `ImageTagHelper` enhances the html `img` (```<img ... ></img>```) tag. It requires a `src` tag be present as well as the `boolean` attribute `asp-append-version` be included. | ||
|
|
||
| If the image source (```src```) is a static file on the host web server, a unique cache bursting string is appended as a parameter to the image source. This insures that if the file on the host web server changes, a unique request url will be generated that includes the updated request parameter. The cache bursting string is a unique value representing the `Sha512` value of the static image file. |
There was a problem hiding this comment.
confused on SHA512. See if all over the place in abbreviations. Actually, it's SHA256 so changed that at least. @guardrex (Do I need to mention you since it's your comment?)
|
|
||
| If the image source (```src```) is a static file on the host web server, a unique cache bursting string is appended as a parameter to the image source. This insures that if the file on the host web server changes, a unique request url will be generated that includes the updated request parameter. The cache bursting string is a unique value representing the `Sha512` value of the static image file. | ||
|
|
||
| If the image source (```src```) is not a static file (possibly a remote url or the file does not exist on the server) then no unique parameter will be generated and the `img` tag will be generated with no additional cache bursting parameter. |
There was a problem hiding this comment.
@guardrex not following "Contractions Needed".
| > [!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 Resources |
|
|
||
| ## Additional Resources | ||
|
|
||
| * [In Memory Caching](../../../../../performance/caching/memory.md) |
There was a problem hiding this comment.
@guardrex I have a link at the top to the base page (not sure if that is a good plan or not). My guess is people will find these pages on google and not go back to a base page so I think it's best to have the references here. I changed it to "Addional Resource".
Phew. That was a lot of work. Thanks for all the suggestions and fixes. That will help me a lot going forward.
On a logistics note, would it be easier to do pull requests rather than edits for a lot of this kind of stuff? This is my first time using MarkDown and my first time using any of these github management features. Open to ideas to make this have less friction.
|
@pkellner looks complete. I'll make a quick pass. |
|
Hi @pkellner, I'm your friendly neighborhood .NET Foundation Pull Request Bot (You can call me DNFBOT). Thanks for your contribution! The agreement was validated by .NET Foundation and real humans are currently evaluating your PR. TTYL, DNFBOT; |
|
@pkellner looks like we need to update the TOC to show these articles. Do you want some help with the TOC? |
|
Sent from my mobile.
… On Feb 7, 2017, at 5:59 PM, Rick Anderson ***@***.***> wrote:
@pkellner looks like we need to update the TOC to show these articles. Do you want some help with the TOC?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
Yes. I don't know anything about TOC
Sent from my mobile.
… On Feb 7, 2017, at 5:59 PM, Rick Anderson ***@***.***> wrote:
@pkellner looks like we need to update the TOC to show these articles. Do you want some help with the TOC?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
@pkellner don't make any commit, I'm working on this. |
|
Ok. I've got nothing to commit. You've got my latest.
Sent from my mobile.
… On Feb 7, 2017, at 8:00 PM, Rick Anderson ***@***.***> wrote:
@pkellner don't make any commit, I'm working on this.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
@pkellner when you say "the content of the Cache Tag Helper is rendered again" do you mean |
|
RE: The metadata for the tops of docs appears immediately above the first line. Here's an example from the URL Rewriting doc ... Change:
There are a few spots here and there for a final suggestion. I'll add line notes to the doc. Check my general comment here: #2644 (comment), as there were a couple of items that I couldn't make line comments to cover. |
| @@ -2,16 +2,16 @@ | |||
|
|
|||
| By [Peter Kellner](http://peterkellner.net) | |||
|
|
|||
| Microsoft has included 17 Tag Helpers that can be immediately used in .net Core web projects. These Tag Helpers are complete and production quality and are recommended to be used in projects where appropriate. In this section we will outline all the built in Tag Helpers along with a sample of each tag helper in use. | |||
| Microsoft has included multiple Tag Helpers that can be immediately used in .net Core web projects. These Tag Helpers are complete and production quality and are recommended to be used in projects where appropriate. In this section we will outline all the built in Tag Helpers along with a sample of each tag helper in use. | |||
There was a problem hiding this comment.
This was a passage that I couldn't get a line note on the last time. See my general comment on it.
| <br/> | ||
| [comment]: **[ValidationSummaryTagHelper](builtin/resources/ValidationSummaryTagHelper.md)** | ||
|
|
||
| ## Additional Resources |
There was a problem hiding this comment.
## Additional resources
lowercase "r"
|
|
||
| By [Peter Kellner](http://peterkellner.net) | ||
|
|
||
|
|
||
| The ```AnchorTagHelper``` enhances the html anchor (`<a ... ></a>`) 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 redirect URL. That URL can include an optional protocol such as https. | ||
| The Anchor Tag Helper enhances the html anchor (`<a ... ></a>`) 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. |
There was a problem hiding this comment.
I think this is an important point worth restating: It seems unlikely to me that if a reader lands on this doc out of the blue that they will be able to understand what the 2nd and 3rd sentences mean. A quick example might be able to show this concept.
| //... | ||
| } | ||
| ``` | ||
| The speaker controller used in attribute definitions below is shown here. |
There was a problem hiding this comment.
I think most authors are ending these sentences that lead into an example, image, or list with a colon.
| //... | ||
| } | ||
| ``` | ||
| The speaker controller used in attribute definitions below is shown here. | ||
|
|
||
| <br/> |
There was a problem hiding this comment.
Not sure why this is here. Ordinarily, extra lines aren't needed. Perhaps in this case, it is needed, and I don't understand the layout. (In which case, ignore me! 😁)
| If the static file exists on the web server, typically in the directory `..wwwroot/images/asplogo.png` the generated html is: | ||
|
|
||
| ```html | ||
| <img |
There was a problem hiding this comment.
Combine these two lines into one line of code between the two triple-backtick lines ... taking this from four lines to three lines.
| src="/images/asplogo.png?v=Kl_dqr9NVtnMdsM2MUg4qthUnWZm5T1fCEimBPWDNgM"/> | ||
| ``` | ||
|
|
||
| The value assigned to the parameter `v` is the hash value of the file on disk generated using the .NET library method `CryptographyAlgorithms.CreateSHA256().ComputeHash()`. If the web server is unable to obtain read access to the static file referenced, `wwwroot/images/asplogo.png`, no `v` parameters is added to the `src` attribute, and the original src attribute is unchanged. |
There was a problem hiding this comment.
- Extra space before "If"
- "parameters is added" ... to "parameters are added"
- "src" ... to
src(single backticks)
|
|
||
| ### src | ||
|
|
||
| To activate the Image Tag Helper, the src attribute is required on the `<img>` element. |
| To activate the Image Tag Helper, the src attribute is required on the `<img>` element. | ||
|
|
||
| > [!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. |
There was a problem hiding this comment.
- Stray space in front of "The Image Tag Helper ..."
- "
Cacheprovider" ... to "cache provider" - To match above "Sha512" to "SHA512" ... I still think the spec tho is with a dash (e.g., "SHA-512"), but I certainly could be mistaken on that.
- Extra space before "The Cache"
- "The Cache" ... "cache" to lowercase (not a proper noun)
| > [!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 |
There was a problem hiding this comment.
## Resources
... and even tho there is only one, it's merely a section header, so I don't think its plurality has to match the number of resources listed. Since I'm a bit of a nutjob when it comes to the "single bullet list" 😢, I'd try to find a second relevant resource to list here. You could list the Response Caching doc and the Response Caching Middleware doc, which are related to the caching concept. Those would be ...
<xref:performance/caching/response>
<xref:performance/caching/middleware>
There was a problem hiding this comment.
## Additional resources
lowercase "r"
|
I did post a couple notes buried and n there asking for clarification.
Sent from my mobile.
… On Feb 8, 2017, at 3:54 AM, Luke Latham ***@***.***> wrote:
@guardrex commented on this pull request.
Very nice. Coming together really great. Let me know if any of my remarks are unclear.
In aspnetcore/mvc/views/tag-helpers/builtin.md:
> @@ -2,16 +2,16 @@
By [Peter Kellner](http://peterkellner.net)
-Microsoft has included 17 Tag Helpers that can be immediately used in .net Core web projects. These Tag Helpers are complete and production quality and are recommended to be used in projects where appropriate. In this section we will outline all the built in Tag Helpers along with a sample of each tag helper in use.
+Microsoft has included multiple Tag Helpers that can be immediately used in .net Core web projects. These Tag Helpers are complete and production quality and are recommended to be used in projects where appropriate. In this section we will outline all the built in Tag Helpers along with a sample of each tag helper in use.
This was a passage that I couldn't get a line note on the last time. See my general comment on it.
In aspnetcore/mvc/views/tag-helpers/builtin.md:
> @@ -39,9 +39,9 @@ Microsoft has included 17 Tag Helpers that can be immediately used in .net Core
[comment]: **[ValidationMessageTagHelper](builtin/resources/ValidationMessageTagHelper.md)**
-[comment]: **[ValidationSummaryHelper](builtin/resources/ValidationSummaryTagHelper.md)**
-
-<br/>
+[comment]: **[ValidationSummaryTagHelper](builtin/resources/ValidationSummaryTagHelper.md)**
+
+
## Additional Resources
AFAIK the plan is to go with just ## Resources. Although I may be the only one here with this problem, the two word heading in sentence case, Additional resources, looks kind'a funny to me (the small "r" there). I floated that these sections could just be called Resources, and it seems fine with them to go that way.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
By [Peter Kellner](http://peterkellner.net)
-The ```AnchorTagHelper``` enhances the html anchor (`<a ... ></a>`) 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 redirect URL. That URL can include an optional protocol such as https.
+The Anchor Tag Helper enhances the html anchor (`<a ... ></a>`) 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.
I think this is an important point worth restating: It seems unlikely to me that if a reader lands on this doc out of the blue that they will be able to understand what the 2nd and 3rd sentences mean. A quick example might be able to show this concept.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> -
-
-**Startup.cs**
-```
-// This method gets called by the runtime.
-// Use this method to configure the
-// HTTP request pipeline.
-public void Configure(IApplicationBuilder app,
- IHostingEnvironment env,
- ILoggerFactory loggerFactory)
-{
- app.UseMvcWithDefaultRoute();
- //...
-}
-```
+The speaker controller used in attribute definitions below is shown here.
I think most authors are ending these sentences that lead into an example, image, or list with a colon.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> -
-
-**Startup.cs**
-```
-// This method gets called by the runtime.
-// Use this method to configure the
-// HTTP request pipeline.
-public void Configure(IApplicationBuilder app,
- IHostingEnvironment env,
- ILoggerFactory loggerFactory)
-{
- app.UseMvcWithDefaultRoute();
- //...
-}
-```
+The speaker controller used in attribute definitions below is shown here.
<br/>
Not sure why this is here. Ordinarily, extra lines aren't needed. Perhaps in this case, it is needed, and I don't understand the layout. (In which case, ignore me! 😁)
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> @@ -1,74 +1,72 @@
[Back To Built In Tag Helpers List](../../builtin.md)
-# AnchorTagHelper
+# Anchor Tag Helper
By [Peter Kellner](http://peterkellner.net)
Extra line here: Usually, you'll only ever have one blank line between any pair of passages in the doc, code samples/example, lists, and tables.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-## asp-controller
+## Anchor Tag Helper Attributes
Lowercase "attributes" ... all headings are sentence case (first letter of first word and any proper nouns)
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-## asp-action
+`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.
I think that they'll ask you to remove the future tense (e.g., will be), and you're already aware of the bad experience I had as a college kid surrounded by opinionated professors and journal editors on state verbs ("be", "being"). There's a missing a comma after "speakers." The two conditions at the start of the last sentence seem to say the same thing, so I think that can be simplified, but you be the judge. There's an asp-action that should be in code.
The asp-controller attribute specifies the controller for generating the rendered URL. The only valid choice is a controller that exists in the current project. To get to a list of all speakers, you specify asp-controller="Speaker". If no asp-action is specified, the default asp-action will be the name of the the controller method calling this view.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-## asp-route-
+`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.
Ditto on the first sentence from the comment above. I might be repeating myself from the first go-round: "That is" prob passes for very conversational language, but I feel it isn't necessary and results in a choppy sentence. You can also eliminate the word "then" after opening prepositional phrases ... the comma is basically doing the work of "then," especially when the sentence is opened with an "If ..." clause. "wanted" is a bit unusual as an object ... feels better to me as a verb (e.g., you want). Quotes are missing on "Detail" in the code example. There's also that "should be set" in there, which is fine with them and might wake me up on a cold sweat 😁. Here's an alternative version of this ...
The asp-action attribute specifies the controller method for generating the rendered URL. In the example, the route to the Speaker Detail view is set as asp-action="Detail". You should always set asp-controller when specifying asp-action. If no asp-action is specified, the default asp-controller is the current executing controller.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-```<a asp-controller="Speaker" asp-action="Detail" asp-route-id-="11">Speaker 11</a>```
+`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:
"will be interpreted" ... how about "is interpreted"
There might be a secret (but coming soon) style manual directive on using phrases around doc elements (code, images, lists, tables, etc.). I think ... I wildly guess ... that they're against this type of construction, but I might be wrong. I try to write in full sentences around doc elements. If they prefer full sentences, then they'll say so.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-the href generated will be
+`<a asp-controller="Speaker" asp-action="Detail" asp-route-id-="11">Speaker 11</a>`
I suppose I didn't explain this one clearly enough. It's single backticks for in-line code references and triple backticks on their own lines with a language specification for blocks of code. This should be ...
'''html
<a asp-controller="Speaker" asp-action="Detail" asp-route-id-="11">Speaker 11</a>
'''
... but use backticks where I'm showing apostrophes there.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> @@ -89,33 +87,59 @@ The code that this generates looks as follows:
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, 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.
You can restructure to get rid of the "will" (future tense) and the state verb in the last part ...
When the link is clicked, the controller method EvaluationsCurrent is called because that controller has two string parameters that match the route produced by the asp-all-route-data dictionary.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-```asp-fragment``` appends after a hash (```#```) tag at the end of the URL whatever the value assigned to it is. That is, 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 (#) automatically. If you create a tag:
"will add" ... to "adds"
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
```
<a asp-action="Evaluations" asp-controller="Speaker"
asp-fragment="SpeakerEvaluations">About Speaker Evals</a>
```
+
The generated URL will be
"will be" ... to "is"
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-```asp-fragment``` appends after a hash (```#```) tag at the end of the URL whatever the value assigned to it is. That is, 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 (#) automatically. If you create a tag:
```
<a asp-action="Evaluations" asp-controller="Speaker"
asp-fragment="SpeakerEvaluations">About Speaker Evals</a>
I'd suggest just putting these two lines on one line and allowing natural browser word wrap.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> ```
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.
"when doing" ... to "when building" or "when creating"
"can be used" ... to "They're used"
Also, I wonder if that second sentence is clear enough. I wonder if readers will get the "marking and searching in JavaScript" phrase without additional specification.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-```asp-area``` allows for a razor view area to be associated with the hyperlink URL. That is, if you have a project setup in a similar fashion to the project pictured below, the link generated will include as its first segment the area you mention.
+`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..
Single space after the first sentence.
I thought you were putting route segments into code? Blogs and Areas/Blogs ??
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-Specifying an area tag that is valid, such as ```area="Blogs"``` when referencing the ```AboutBlog.cshtml``` file will look like the following using the ```AnchorTagHelper```.
+ * *wwwroot*
+
You can close up and delete all of the extra lines in this list.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> +
+ * *Controllers*
+
+ * *HomeController.cs*
+
+ * *Views*
+
+ * *Home*
+
+ * *Index.cshtml*
+
+ * *AboutBlog.cshtml*
+
+ * *Controllers*
+
+
Two extra lines here that you can delete
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> +
+ * *HomeController.cs*
+
+ * *Views*
+
+ * *Home*
+
+ * *Index.cshtml*
+
+ * *AboutBlog.cshtml*
+
+ * *Controllers*
+
+
+
+Specifying an area tag that is valid, such as ```area="Blogs"``` when referencing the ```AboutBlog.cshtml``` file will look like the following using the Anchor Tag Helper.
Add comma after "file"
single backticks on the inline code references
"will look like" ... to "looks like"
Probably a colon at the end over a period
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> +
+ * *HomeController.cs*
+
+ * *Views*
+
+ * *Home*
+
+ * *Index.cshtml*
+
+ * *AboutBlog.cshtml*
+
+ * *Controllers*
+
+
+
+Specifying an area tag that is valid, such as ```area="Blogs"``` when referencing the ```AboutBlog.cshtml``` file will look like the following using the Anchor Tag Helper.
```
mark as html
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
> @@ -128,20 +152,28 @@ The generated HTML will include the areas segment and will be as follows:
```
> [!TIP]
-> For MVC Areas to work in your web application, the route template must include a reference to the area if it exists. That template (which is the second parameter of the ```routes.MapRoute``` method call) will look as follows: ```template: "{area:exists}/{controller=Home}/{action=Index}"```.
-
+> For MVC areas to work in a web application, the route template must include a reference to the area if it exists. That template, which is the second parameter of the `routes.MapRoute` method call, will appear as: template: '"{area:exists}/{controller=Home}/{action=Index}"'
That's fine. 👍 I should've left that code the way you have it here instead of trying to split it out.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-The ```asp-protocol``` is for specifying a particular protocol (such as ```https```) in your URL. An example ```AnchorTagHelper``` that includes the protocol will look as follows.
+The `asp-protocol` is for specifying a particular protocol (such as `https`) in your URL. An example Anchor Tag Helper that includes the protocol will look as follows.
"will look" ... to "looks"
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
```<a asp-protocol="https" asp-action="About" asp-controller="Home">About</a>```
and will generate HTML as follows.
```<a href="https://localhost/Home/About">About</a>```
-(of course the domain, in the case above is localhost, but this will be substituted for whatever the actual domain hosting the web site is hosted at).
+The domain in the example is localhost, but the Anchor Tag Helper uses the website's public domain when generating the URL.
+
+- - -
Only one line here
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
-The ```asp-protocol``` is for specifying a particular protocol (such as ```https```) in your URL. An example ```AnchorTagHelper``` that includes the protocol will look as follows.
+The `asp-protocol` is for specifying a particular protocol (such as `https`) in your URL. An example Anchor Tag Helper that includes the protocol will look as follows.
```<a asp-protocol="https" asp-action="About" asp-controller="Home">About</a>```
More examples along here where it should be on three lines with an html language specified.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md:
>
```<a asp-protocol="https" asp-action="About" asp-controller="Home">About</a>```
and will generate HTML as follows.
```<a href="https://localhost/Home/About">About</a>```
-(of course the domain, in the case above is localhost, but this will be substituted for whatever the actual domain hosting the web site is hosted at).
+The domain in the example is localhost, but the Anchor Tag Helper uses the website's public domain when generating the URL.
+
+- - -
+
+## Additional Resources
## Resources
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> @@ -0,0 +1,286 @@
+[Back To Built In Tag Helpers List](../../builtin.md)
+
+# Cache Tag Helper
+
+By [Peter Kellner](http://peterkellner.net)
+
+
Delete one line here
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> @@ -0,0 +1,286 @@
+[Back To Built In Tag Helpers List](../../builtin.md)
+
+# 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.
It's their call, but I don't believe in the one sentence paragraph. I can hear Mrs. Calvary now in the 7th grade: "Now Luke, how many times have I told you?! ... There's no such thing as a one-sentence paragraph!!" I'm sure she was thinking after telling me that ten times, "This kid is an IDIOT!" 😁 She finally won I guess.
Also, there's a stray space after the word "The" at the beginning.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +# 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.
+
+Here is an example of the code you include in your `cshtml` page to achieve the default cache behavior described above.
+
+```html
***@***.***<Cache>
+```
+
+If you repeatedly refresh the page that contains `CacheTagHelper`, the first time the current`DateTime`will be shown. Repeated refreshes of the page will continue to show the first `DateTime` shown until the cache expires (which is likely to be twenty minutes unless server memory pressure evicts the cache sooner).
Should CacheTagHelper here be "a Cache Tag Helper"?
It needs a pair of spaces around the first DateTime
The first sentence might need a touch ... If you "repeatedly" leads to "the first time" ... so it seems to mix periods of time. I think you'll need to have a short first sentence that states "the first time" bit. Allow the second sentence to address what happens when the page is refreshed multiple times thereafter.
I think you can drop the parentheses and just introduce the "which" phrase with a comma.
You can also totally drop the "to be" in favor of ", which is likely twenty minutes unless ..."
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +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.
+
+Here is an example of the code you include in your `cshtml` page to achieve the default cache behavior described above.
+
+```html
***@***.***<Cache>
+```
+
+If you repeatedly refresh the page that contains `CacheTagHelper`, the first time the current`DateTime`will be shown. Repeated refreshes of the page will continue to show the first `DateTime` shown until the cache expires (which is likely to be twenty minutes unless server memory pressure evicts the cache sooner).
+
+You can achieve more control of the cache duration of the content by setting any of the following attributes:
+
+## Cache Tag Helper Attributes
+
+- - -
+
Looks like an extra line here
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +
+```html
***@***.***<Cache>
+```
+
+If you repeatedly refresh the page that contains `CacheTagHelper`, the first time the current`DateTime`will be shown. Repeated refreshes of the page will continue to show the first `DateTime` shown until the cache expires (which is likely to be twenty minutes unless server memory pressure evicts the cache sooner).
+
+You can achieve more control of the cache duration of the content by setting any of the following attributes:
+
+## Cache Tag Helper Attributes
+
+- - -
+
+### enabled
+
+
... and here ... and I'll stop repeating this comment, as it looks like these extra lines are common going forward.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +You can achieve more control of the cache duration of the content by setting any of the following attributes:
+
+## Cache Tag Helper Attributes
+
+- - -
+
+### enabled
+
+
+| Attribute Type | Valid Values |
+|---------------- |---------------- |
+| boolean | "true" (default) |
+| | "false" |
+
+
+The attribute `enabled` determines whether any caching is performed of the content inside the Cache Tag Helper. The default is `true`, which results in all other attributes being valid. The default value 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.
Go with one space between sentences
"The default is true" and "The default value is true" ... so this information appears twice
The last sentence has a "will," and the verb form is "affect."
I may have had you add that comma after false, but I'm feel'in an "and" there might be good.
Here's an alternate version ...
If set to false and regardless of what other attributes are specified, this Cache Tag Helper has no caching affect on the rendered output.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +```html
+<Cache enabled="true">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+- - -
+
+### expires-on
+
+| Attribute Type | Example Value |
+|---------------- |---------------- |
+| DateTimeOffset | ***@***.*** DateTime(2025,1,29,17,02,0)" |
+
+
+The attribute `expires-on` sets a deterministic expiration date for caching the content of the Cache Tag Helper when it is first rendered. The example below will cache the contents of the Cache Tag Helper until 5:02 PM on January 29, 2025.
"will cache" ... to "caches"
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +```html
+<Cache ***@***.*** DateTime(2025,1,29,17,02,0)">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+- - -
+
+### expires-after
+
+| Attribute Type | Example Value |
+|---------------- |---------------- |
+| TimeSpan | ***@***.***(120)" |
+
+
+The attribute `expires-after` sets a specific amount of time from the current `DateTime` to cache the contents of the Cache Tag Helper. This value is set when it is first rendered. The example below caches the contents of the Cache Tag Helper for one hundred twenty seconds. If there is memory pressure on the server, the cache may be evicted sooner.
2 spaces after first sentence
"one hundred twenty seconds" ... to "120 seconds"
"the cache may be evicted sooner" ... mmm ... "cached entities" or "cached items" or something like that. It's not really the whole cache necessarily.
You can drop both state verbs if you want ...
If memory pressure develops on the server, the app can evict cached items to free memory.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +```HTML
+<Cache ***@***.***(5)">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+- - -
+
+### expires-sliding
+
+| Attribute Type | Example Value |
+|---------------- |---------------- |
+| TimeSpan | ***@***.***(5)" |
+
+
+The attribute `expires-after` sets a specific amount of time from the current `DateTime` that the contents of the `Cache` tag helper will be kept in cache. This value is set when the `Cache` tag helper is first rendered.
Convert two spaces after the 1st sentence into one space
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +```html
+<Cache vary-by-route="Make,Model">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+- - -
+
+### vary-by-cookie
+
+| Attribute Type | Example Values |
+|---------------- |---------------- |
+| String | ".AspNetCore.Identity.Application" |
+| | ".AspNetCore.Identity.Application,HairColor" |
+
+The attribute `vary-by-cookie` 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 causing the request cookie to be set, The content of the Cache Tag Helper is rendered again, and the cache is reset.
"asp.net" ... to "ASP.NET"
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> + Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+````
+
+- - -
+
+### vary-by-user
+
+| Attribute Type | Example Values |
+|---------------- |---------------- |
+| Boolean | "true" |
+| | "false" (default) |
+
+The attribute `vary-by-user` 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 ***@***.***`.
+
+The example below looks at the current logged in user. When a different user is found, The content of the Cache Tag Helper is rendered again, and the cache is reset.
lowercase the "T" in "The content ..."
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +| | "false" (default) |
+
+The attribute `vary-by-user` 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 ***@***.***`.
+
+The example below looks at the current logged in user. When a different user is found, The content of the Cache Tag Helper is rendered again, and the cache is reset.
+
+Usage Example:
+
+```html
+<Cache vary-by-user="true">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+> [!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, that state is considered a valid cache state, which means that no logged-in user is one cache state, and the contents will be maintained for that condition as well.
There are two spaces after the 1st sentence
There's a stray space before "Using ..."
Add comma before the "which" in "... which references the ..."
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +</Cache>
+```
+
+> [!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, that state is considered a valid cache state, which 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 | ***@***.***" |
+
+
+The attribute `vary-by` 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 any update to any of the concatenated values invalidates the cache.
Comma after "Often"
I don't think "string-concatenation" is hypenated
Two spaces after 3rd sentence
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> + Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+- - -
+
+### priority
+
+| Attribute Type | Example Values |
+|---------------- |---------------- |
+| CacheItemPriority | "High" |
+| | "Low" |
+| | "NeverRemove" |
+| | "Normal" |
+
+The attribute `priority` provides cache ejection guidance to the built-in cache provider. If the web server experiences memory pressure and evicts one or more of your cached entities, it will evict Low priority cache entities first.
I think if you go with the code version of "low" ... i.e., "Low" that you'll have to backtick it into code Low.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +| | "Low" |
+| | "NeverRemove" |
+| | "Normal" |
+
+The attribute `priority` provides cache ejection guidance to the built-in cache provider. If the web server experiences memory pressure and evicts one or more of your cached entities, it will evict Low priority cache entities first.
+
+Usage Example:
+
+```html
+<Cache priority="High">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+> [!WARNING]
+> using the `priority` attribute does not guarantee any specific level of cache retention. It is simply a suggestion to the Cache Provider. To be extra clear, setting this attribute to `NeverRemove` does not guarantee that the cache will not be evicted. More details can be found in the additional resources listed below.
Use the contraction "It's simply ..."
Use the contraction "doesn't" over "does not"
I think it should be "a specific level"
I think "Cache Provider" here would be lowercase (not a proper noun)
Two spaces before "More"
Stray space at the start before "using" and it should be capitalized "Using"
For this ...
To be extra clear, setting this attribute to NeverRemove does not guarantee that the cache will not be evicted.
mmm ... "to be" ... they'll allow it. It makes me cringe a little bit. The "extra" is like saying "very" imo. Several style manuals call for dropping "very." I think the thinking is that it conveys little (or no) additional information.
Otherwise tho ... the sentence is a "double negative" expression. As an alternate suggestion ...
Using the priority attribute doesn't guarantee a specific level of cache retention. It's simply a suggestion to the cache provider. Setting this attribute to NeverRemove doesn't guarantee cache item persistence. For more information, see the additional resources listed below.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +Usage Example:
+
+```html
+<Cache priority="High">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+> [!WARNING]
+> using the `priority` attribute does not guarantee any specific level of cache retention. It is simply a suggestion to the Cache Provider. To be extra clear, setting this attribute to `NeverRemove` does not guarantee that the cache will not be evicted. More details can be found in the additional resources listed below.
+
+- - -
+
+
+>[!NOTE]
+> The Cache Tag Helper is dependent on the built in Memory Cache service being included in the `startup.cs` ConfigureServices method. Adding this service is not necessary because the built in Tag Helper extensions take care of this in the `AddMvc` method call.
"built in" ... to "built-in"
"service being included" ... to "service included"
Capitalize "S" in "Startup.cs" and that filename should be in italics
Put ConfigureServices in code with single backticks
Two spaces after the first sentence
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +```html
+<Cache priority="High">
+ Current Time Inside Cache Tag Helper: @DateTime.Now
+</Cache>
+```
+
+> [!WARNING]
+> using the `priority` attribute does not guarantee any specific level of cache retention. It is simply a suggestion to the Cache Provider. To be extra clear, setting this attribute to `NeverRemove` does not guarantee that the cache will not be evicted. More details can be found in the additional resources listed below.
+
+- - -
+
+
+>[!NOTE]
+> The Cache Tag Helper is dependent on the built in Memory Cache service being included in the `startup.cs` ConfigureServices method. Adding this service is not necessary because the built in Tag Helper extensions take care of this in the `AddMvc` method call.
+
+## Additional Resources
## Resources
In aspnetcore/mvc/views/tag-helpers/builtin/resources/CacheTagHelper.md:
> +
+> [!WARNING]
+> using the `priority` attribute does not guarantee any specific level of cache retention. It is simply a suggestion to the Cache Provider. To be extra clear, setting this attribute to `NeverRemove` does not guarantee that the cache will not be evicted. More details can be found in the additional resources listed below.
+
+- - -
+
+
+>[!NOTE]
+> The Cache Tag Helper is dependent on the built in Memory Cache service being included in the `startup.cs` ConfigureServices method. Adding this service is not necessary because the built in Tag Helper extensions take care of this in the `AddMvc` method call.
+
+## Additional Resources
+
+* <xref:performance/caching/memory>
+* <xref:security/authentication/identity>
+
+
Delete extra lines down to just one blank line at the bottom
In aspnetcore/mvc/views/tag-helpers/builtin/resources/ImageTagHelper.md:
> +
+By [Peter Kellner](http://peterkellner.net)
+
+The Image Tag Helper enhances the `img` (`<img>`) tag. It requires a `src` tag as well as the `boolean` attribute `asp-append-version`.
+
+If the image source (`src`) is a static file on the host web server, a unique cache busting string is appended as a query parameter to the image source. This insures that if the file on the host web server changes, a unique request URL is generated that includes the updated request parameter. The cache busting string is a unique value representing the `SHA256` hash of the static image file.
+
+If the image source (`src`) isn't a static file, possibly a remote URL or the file doesn't exist on the server, the `<img>` tag's `src` attribute is generated with no cache busting query string parameter.
+
+## Image Tag Helper Attributes
+
+- - -
+
+### asp-append-version
+
+`asp-append-version` is the only attribute available for the Image Tag Helper. When specified along with a `src` attribute, this Image Tag Helper is invoked.
Kill one space before "When"
In aspnetcore/mvc/views/tag-helpers/builtin/resources/ImageTagHelper.md:
> +## Image Tag Helper Attributes
+
+- - -
+
+### asp-append-version
+
+`asp-append-version` is the only attribute available for the Image Tag Helper. When specified along with a `src` attribute, this Image Tag Helper is invoked.
+
+An example of a valid `img` tag helper is:
+
+```html
+<img src="~/images/asplogo.png"
+ asp-append-version="true" />
+```
+
+If the static file exists on the web server, typically in the directory `..wwwroot/images/asplogo.png` the generated html is:
Comma after the directory path
If you want to use the two dots in the path, use ../wwwroot/images/asplogo.png
"html" ... to "HTML"
In aspnetcore/mvc/views/tag-helpers/builtin/resources/ImageTagHelper.md:
> +
+### asp-append-version
+
+`asp-append-version` is the only attribute available for the Image Tag Helper. When specified along with a `src` attribute, this Image Tag Helper is invoked.
+
+An example of a valid `img` tag helper is:
+
+```html
+<img src="~/images/asplogo.png"
+ asp-append-version="true" />
+```
+
+If the static file exists on the web server, typically in the directory `..wwwroot/images/asplogo.png` the generated html is:
+
+```html
+<img
Combine these two lines into one line of code between the two triple-backtick lines ... taking this from four lines to three lines.
In aspnetcore/mvc/views/tag-helpers/builtin/resources/ImageTagHelper.md:
> +
+An example of a valid `img` tag helper is:
+
+```html
+<img src="~/images/asplogo.png"
+ asp-append-version="true" />
+```
+
+If the static file exists on the web server, typically in the directory `..wwwroot/images/asplogo.png` the generated html is:
+
+```html
+<img
+ src="/images/asplogo.png?v=Kl_dqr9NVtnMdsM2MUg4qthUnWZm5T1fCEimBPWDNgM"/>
+```
+
+The value assigned to the parameter `v` is the hash value of the file on disk generated using the .NET library method `CryptographyAlgorithms.CreateSHA256().ComputeHash()`. If the web server is unable to obtain read access to the static file referenced, `wwwroot/images/asplogo.png`, no `v` parameters is added to the `src` attribute, and the original src attribute is unchanged.
Extra space before "If"
"parameters is added" ... to "parameters are added"
"src" ... to src (single backticks)
In aspnetcore/mvc/views/tag-helpers/builtin/resources/ImageTagHelper.md:
> +```
+
+If the static file exists on the web server, typically in the directory `..wwwroot/images/asplogo.png` the generated html is:
+
+```html
+<img
+ src="/images/asplogo.png?v=Kl_dqr9NVtnMdsM2MUg4qthUnWZm5T1fCEimBPWDNgM"/>
+```
+
+The value assigned to the parameter `v` is the hash value of the file on disk generated using the .NET library method `CryptographyAlgorithms.CreateSHA256().ComputeHash()`. If the web server is unable to obtain read access to the static file referenced, `wwwroot/images/asplogo.png`, no `v` parameters is added to the `src` attribute, and the original src attribute is unchanged.
+
+- - -
+
+### src
+
+To activate the Image Tag Helper, the src attribute is required on the `<img>` element.
"src" ... to src @
In aspnetcore/mvc/views/tag-helpers/builtin/resources/ImageTagHelper.md:
> +
+```html
+<img
+ src="/images/asplogo.png?v=Kl_dqr9NVtnMdsM2MUg4qthUnWZm5T1fCEimBPWDNgM"/>
+```
+
+The value assigned to the parameter `v` is the hash value of the file on disk generated using the .NET library method `CryptographyAlgorithms.CreateSHA256().ComputeHash()`. If the web server is unable to obtain read access to the static file referenced, `wwwroot/images/asplogo.png`, no `v` parameters is added to the `src` attribute, and the original src attribute is unchanged.
+
+- - -
+
+### src
+
+To activate the Image Tag Helper, the src attribute is required on the `<img>` element.
+
+> [!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.
Stray space in front of "The Image Tag Helper ..."
"Cache provider" ... to "cache provider"
To match above "Sha512" to "SHA512" ... I still think the spec tho is with a dash (e.g., "SHA-512"), but I certainly could be mistaken on that.
Extra space before "The Cache"
"The Cache" ... "cache" to lowercase (not a proper noun)
In aspnetcore/mvc/views/tag-helpers/builtin/resources/ImageTagHelper.md:
> +<img
+ src="/images/asplogo.png?v=Kl_dqr9NVtnMdsM2MUg4qthUnWZm5T1fCEimBPWDNgM"/>
+```
+
+The value assigned to the parameter `v` is the hash value of the file on disk generated using the .NET library method `CryptographyAlgorithms.CreateSHA256().ComputeHash()`. If the web server is unable to obtain read access to the static file referenced, `wwwroot/images/asplogo.png`, no `v` parameters is added to the `src` attribute, and the original src attribute is unchanged.
+
+- - -
+
+### src
+
+To activate the Image Tag Helper, the src attribute is required on the `<img>` element.
+
+> [!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
... and even tho there is only one, it's merely a section header, so I don't think its plurality has to match the number of resources listed. Since I'm a bit of a nutjob when it comes to the "single bullet list" 😢, I'd try to find a second relevant resource to list here. You could list the Response Caching doc and the Response Caching Middleware doc, which are related to the caching concept. Those would be ...
<xref:performance/caching/response>
<xref:performance/caching/middleware>
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
|
yes, that is what I mean.Are you updating that or should I? (I don't see
that this comment points to source, is there a way to know which lines?)
…On Tue, Feb 7, 2017 at 8:55 PM, Rick Anderson ***@***.***> wrote:
@pkellner <https://github.com/pkellner> when you say "the content of the
Cache Tag Helper is rendered again" do you mean
the content of the Cache Tag Helper is rendered and cached again?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#2644 (comment)>, or mute
the thread
<https://github.com/notifications/unsubscribe-auth/AAOuEkid-e_O61yVCBqIIBLtCpXDeOquks5raUqkgaJpZM4L0NC0>
.
--
Peter Kellner
http://PeterKellner.net
Microsoft MVP (ASP.NET)
|
|
Hey @Rick-Anderson . You said hold off on making updates 13 hours ago. @guardrex made some more suggestions including I think how to add the "TOC Block" at the top of each page. Are you (Rick) working on that for me or do you want me to do it. LMK when it's OK to update my pull request again. |
|
I'll add the TOC and add "the content of the Cache Tag Helper is rendered and cached again" |
|
Sorry ... I did miss a couple. Most of them require little or no action or refer to general issues. I think I can just summarize and clarify this handful of comments here. RE: TOC The TOC ("Table Of Contents") is a different doc. I see he just added a comment on that.
It's just that when you link two independent clauses into one sentence but where the second sentence opens with a word or clause of its own that requires a comma, the two independent clauses get a semi-colon instead of a comma. For example, we only need a comma for the two independent clauses in ... Jack fell down and broke his crown, and Jill laughed her ass off. ... but we need a semi-colon for the two independent clauses in ... Jack fell down and broke his crown; and with great joy, Jill laughed her ass off. ... because the 2nd one starts with a prepositional phrase "with great joy." ☝️ I don't think Mrs. Calvary, my 7th grade English teacher, would approve of those examples 😁, but that's the basic idea.
My only concern there really is that the other doc seems to imply that
Nah ... not really. You can just respond without the direct mentions.
Just stuff like "do not" to "don't" and "is not" to "isn't" ... contractions
I see what you mean, but it's not a common practice. We'll have to see what the "real editor" 😜 thinks. Remember, I'm just an "unreal editor" ... I don't exist. 😁 That was a good one. 😄
Not sure, but that sounds like a good idea to batch up the commits for each set of changes. They haven't yelled at me (yet 😁) for not using a 2nd branch to batch up changes for the PR branch. On a separate note, I hazard a guess that it's easier to work on these when there is one PR per doc and the docs are handled separately. They'll say whether or not they want one PR for each different doc. As for the rest, I'm learning as well. This was my first time with the GH review feature.
idk on that one. I think there were just a couple of spots where just a few more sentences might ensure that if someone landed on the doc cold that they wouldn't get lost in the language.
Not sure what you mean by "how you changed" ... maybe they made changes? I think you fixed the vast majority of those spots where I saw extra line spaces, and I think I list in last night's comments any others that I saw. On the use of the horizontal rule, I'm not sure what they prefer. It isn't common to use them to separate sections in docs where a section heading is present. It's just one blank line ... the heading
Not sure ... but I build them with no extra spaces, three dashes only, and frequently leave off the opening and closing bars (but that's optional ... you can have them if you like). For that one table, I'd put or If you want to center (or right-justify a column), use the colon: I've also had some good luck with paragraphs where I need to separate a description from the setting values. Renders as ...
They decided on |
|
@Rick-Anderson @guardrex I'm confused on this pull request process. Doesn't Rick need to merge this pull request into the pkellner-th-branch first, then make the changes? (then I can pull back to my fork and make more changes). Please correct me if there is a better way. It seems to me that we should make a branch underneath pkellner-th-branch for each remaining tag helper (happy to make the list) and then manage each separately. Then, we can close this pull request and as each of the other th's are completed, they can be merged into this branch (pkellner-th-branch). Then, eventually, after all the th's are done, pkellner-th-branch can be merged into the production one. |
|
@pkellner at this point I think it's easier to close:
This PR diverged from master so much I couldn't create a TOC. |
|
Once we get #2698 merged updates will be much smoother/quicker. Thanks for all your efforts. |
|
I think so. Go ahead. You've got my latest in that PR so nothing lost.
Sent from my mobile.
… On Feb 8, 2017, at 6:05 PM, Rick Anderson ***@***.***> wrote:
@pkellner at this point I think it's easier to close:
close this PR
@pkellner copies #2698 and creates a new PR with that
This PR diverged from master so much I couldn't create a TOC.
Does that work?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub, or mute the thread.
|
Process
Considerations
|
Hi @Rick-Anderson This pull requests contains the updates you suggested to AnchorTagHelper as well as doc pages for the Tag Helpers ImageTagHelper and CacheTagHelper. It's all original content. I did not use any content from other sources. Please give me an idea when you plan on reviewing so I can schedule my time to create the rest of the docs. Your feedback is a huge help as I go forward and create the others.