Consider adding topic that covers ChangeToken

[divega]

ChangeToken is exposed in the configuration API surface but it is also a general purpose low level building block you can use by itself.

Although using it to have logging automatically updated from configuration files can be very straightforward (e.g. it only requires setting a flag on the configuration provider), customers keep hitting some complexity when they try to use ChangeToken directly. Typically the first thing they hit is that it is a one time use rather than an event mechanism, so every time it fires you need to re-register to get a notification from the next ChangeToken if you need it.

Here is one example of a customer hitting this and the workaround: aspnet/Configuration#432 (comment), but we had a few internal people hitting it during verification as well.

[guardrex]

@Rick-Anderson I'll have an outline for this shortly.

• Where do you want this in the TOC? It doesn't just apply to watching config files ... you can watch any kind of file and execute code on a file change, so it's fundamental feature.
• Title? Detect file changes with ChangeToken in ASP.NET Core

[guardrex]

@divega @HaoK @Tratcher @Rick-Anderson @scottaddie

Metadata

Title: Detect changes with Change Tokens in ASP.NET Core
TOC Title: Detect changes with Change Tokens
UID: <location>/change-token

TOC

This is a primitive feature (Microsoft.Extensions.Primitives). I think it's the first such low-level feature to have its own topic. Two options leap to mind:

1. Place it into fundamentals ... perhaps just under "Request Features" in the list of topics.
2. Create a primitives entry in the TOC (i.e., things like StringSegment and StringValues may get their own topics someday). Have a Primitives (or other title) index page (that will only list ChangeToken for now). The topic appears at fundamentals/primitives/change-tokens

I'm all 👂 👂 👂 🌽 👂 on which way @Rick-Anderson wants to go there.

Outline

• Introduction
  • ChangeToken feature description
  • Sample link
• Describe the OnChange overloads and the IChangeToken interface
• OnChange can fire multiple times when watching files; I propose showing how to perform file hash checks to ensure single execution of user code when monitoring files (but tell me if that's bad/wrong/overkill/goofy). For details, see: ChangeToken.OnChange fires twice when listening for configuration changes (FileSystem/287).
• Monitoring changes
  • In configuration files and other files
  • Monitoring changes generally in user code

Currently, my Razor Pages sample implements one of the ChangeToken overloads ... and only for file changes. I'd like to demo both overloads of ChangeToken in the sample. I'll also add a class that derives from IChangeToken and have something that monitors in a non-file scenario.

[Rick-Anderson]

@HaoK @Tratcher can one of you approve the outline?

Create a primitives entry in the TOC (i.e., things like StringSegment and StringValues may get their own topics someday). Have a Primitives (or other title) index page (that will only list ChangeToken for now). The topic appears at fundamentals/primitives/change-token

I like fundamentals/primitives/change-token
@scottaddie - where should it go?

[guardrex]

The only thing that concerns me ☝️ is the use of "Primitives" as the TOC title. We want ppl to see the ChangeToken topic, and I'm not sure the name is interesting enough to click.

Let's brainstorm ... "Primitive features" ... "Fundamental features" ... "Building blocks" (as @divega mentioned) ... but if u really want to get some clicks ... "Primal features" ... everyone will click that. lol

[EDIT]

• I'll go with Primitives in ASP.NET Core.
• Because a token is really called a "change token" (with a space) and they'll probably usually be implemented as many tokens (as they're re-created) (plural), I'll make the title: Detect changes with Change Tokens in ASP.NET Core.

[scottaddie]

@Rick-Anderson @guardrex I also vote for fundamentals/primitives/change-token. I like the word "primitives" only because it matches the namespace in which ChangeToken is found.

[HaoK]

Outline looks good to me

[Tratcher]

These are also used for MemoryCache eviction.

[guardrex]

@Tratcher Are you suggesting mentioning it in passing? ... or are you looking for more significant coverage than that?

[Tratcher]

It's definitely worth mentioning, it's one of the main recipients of change notifications. Adding a small sample wouldn't hurt either. The samples for this on https://docs.microsoft.com/en-us/aspnet/core/performance/caching/memory are a little strange.

[guardrex]

The caching topic is certainly feature-focused ... change tokens not being mentioned at all.

• I thought that the caching change tokens are an implementation detail handled by the API and not meant to be handled directly by the dev. Is that incorrect?
• Do we want to show how to build a token-based caching system when the OOB caching is professionally produced, performant, and supported?
• Tea leaves indicate an overhaul of caching on the horizon: https://github.com/aspnet/Caching/issues/289 ... well ... [@]JunTaoLuo opened the issue in March, but I wildly guess it could happen for 3.0. If a sample did deal with the caching tokens directly today, is it likely to require attention when the overhaul is performed?

RE the current sample: If one is going to trigger a callback on a token to run some code, they could just as easily call a method to do that work. What I'd like to do is push the sample a bit further forward: Sure, code can run (with state) on the callbacks, but it probably makes sense to develop the scenario where HasChanged must be checked to block additional callbacks while that code is running ... or something along those lines. We already decided (@HaoK said) not to get into CompositeChangeToken too deeply, so I'm not trying to develop a multi-token scenario. I won't be doing that.

I'm wrapping up the LoggerMessage topic today. Before I tackle the sample setup and outline for the RP unit+integration testing topic, I'll see if I can improve this part of the sample.

[Tratcher]

A dev may need to flow a change token from the source to the consumer. E.g. Read a file into cache and add a change token that listens for file changes to remove the file from cache so it can be recreated.

[Tratcher]

Any hypothetical design changes are too far out to worry about for the current discussion.

[guardrex]

I think that would work best as an add-on example to what's currently there and not as a replacement. I like showing the file handling in a simple way initially not tied to any other feature. I can add an example to the sample that does what you're proposing.