Update Azure Key Vault Config Provider topic and sample

[guardrex]

cc/ @anurse (partner in crime on this topic), @blowdart, @pakrym, @olavt, @Coderrob

Fixes #3369

🔥 HOT! 🔥 updates in this one:

• Sample added to demo the prefix key vault secret manager for different app versions, not app names.
• 2.0 samples added. Note that tabs aren't required because the topic's example code is the same across 1.x and 2.x versions. However, the 1.1 and 2.0 samples are linked separately when mentioning to the reader what they can download.
• Reacted to the feedback in Issues with KeyVaultConfigProviderSample #3369 and the discussion in Add KeyDelimiter replacement to GetKey function. #3525, including adding a security note that it isn't recommended to prefix app names or environments to secrets in the same vault.

[guardrex]

@anurse @blowdart 🎉🎈 We're off WIP now. 🎈🎉 Do u want to review the updates? @Rick-Anderson, plz 🔪 the WIP label, too.

Couple of known things to address:

• Getting away here from environmental config as a security best practice. The samples go with merely an app version prefix. There's a warning now not to stuff dev/prod and secrets for multiple apps into the same vault.
• I think the config here in the 2.0 samples is as clean and neat as it gets right now. I wish I could pull down those appsetting.json values for the config provider in ConfigureAppConfiguration from CreateDefaultBuilder, but that probably ain't gonna happen. See what u think about my approach, and this might get more discussion generally on Can I get a value loaded by CreateDefaultBuilder for use in ConfigureAppConfiguration? aspnet/Configuration#707.
• I use the WebHost directly in Main. I was warned off of the NutJob™️ programming pattern that I like 😀 (i.e., minimizing the number of files and lines of code used) by our good friend @ctolkien on Slack. I need more feedback tho: If I don't use BuildWebHost().Run(); and public static IWebHost BuildWebHost(string[] args) => WebHost.XXXX and just go directly with WebHost.XXXX.Run() in Main, what problems might that create? ... is that approach just a big 'ole 💣? [EDIT] Received a partial answer from an Announcement on 2.0 EF Core: "The static Program.BuildWebHost method enables EF Core to access the application's service provider at design time." This pattern then is important enough to reinforce everywhere and make consistent.

[Rick-Anderson]

@anurse can you do a quick review (or recommend someone)?

[guardrex]

Ugh ... In spite of the 2.0 sample just working on the prerelease packages, the sample is breaking now with 2.0 release packages. I'll see if I can sort it out.

I need to sort out the cross-targeting situation (netcoreapp2.0 and net461). Something changed ... this just worked prior to release, but it chokes now ...

error NU1202: Package Microsoft.AspNetCore.All 2.0.0 is not compatible with net461 (.NETFramework,Version=v4.6.1) / win7-x86. Package Microsoft.AspNetCore.All 2.0.0 supports: netcoreapp2.0 (.NETCoreApp,Version=v2.0)

Nevermind! on WebHost. It was a VS Code problem ... not a problem with accessibility to WebHost.

[guardrex]

Let's see if conditioning that <ItemGroup> is the right way to go there.

[guardrex]

It's all sorted out now thanks to Kevin @PinpointTownes.

In the first case, I was using a 🪲 bug as a "feature" to cross-target net461 and netcoreapp2.0 without conditioning the All package: aspnet/MetaPackages#142

In the second case, Microsoft.AspNetCore isn't a metapackage ... it has real implementation goodness in it. The ticket to getting access to the public WebHost is either using that or using the All package, which has it.

We're good now! ... first day fun with 2.0 release bits. This PR is ready for 👀.

[scottaddie]

Add missing "e" to "sampl"

[guardrex]

My keyboard hates me! I know I didn't type it that way initially. lol

[scottaddie]

I recommend including a space on either side of the forward slash. This will make the version numbers a bit easier to read. Also, it may be best to explicitly state "ASP.NET Core 1.1" and "ASP.NET Core 2.x" instead of 1.1 and 2.x, respectively.

[guardrex]

I'm going to try a list of three fully-qualified items on the next commit. 🤞

[guardrex]

@scottaddie 👍 Try that list revision ... I think it works.

[guardrex]

@Rick-Anderson @tdykstra @scottaddie Hold a sec before u pull the trigger here. 🔫

I'm concerned about the sample naming scheme. I went off to work the URL Rewriting Middleware samples, and it's clear that I need guidance on the naming of samples and folders.

The last sample on these for the prior major version is 1.1. It's easy to see that they should prob be called "the ASP.NET Core 1.1 sample." The folder path to it is simply .../samples/1.1/.

Things get hairy for 2.0/2.x. Any of the following schemes work:

1. Call the sample what it really is: "ASP.NET Core 2.0 sample" ... the folder is at .../samples/2.0/. Problem later: What happens if someone jumps in and makes it 2.1 and mods it with 2.1 features? It would need a "ASP.NET Core 2.1 sample" with another folder at .../samples/2.1/.
2. Call the sample by its major version (attempting to harden the topic in some ways by not needing to roll the minor version up): "ASP.NET Core 2.x" ... the folder is at .../samples/2.x/. Makes sense: Can roll the minor version at any time. Later at the end of the 2.x sequence ... 2.2 ... 2.3 ... whatever it is, this can be sealed into the final name with 3.0 ships (i.e., fix it to, for example, "ASP.NET Core 2.3" at .../samples/2.3/ when 3.0 ships).
3. Forget minor versions. Everything is just "ASP.NET Core 1.x" at .../samples/1.x/ with a 1.1 sample in it, an "ASP.NET Core 2.x" at .../samples/2.x with a 2.0, 2.1, 2.2 ... whatever it reaches ... in it, and so on for 3.x, 4.x, etc. Minor downside: Can't jump in easily and make a separate minor release sample (e.g., have a 2.0 but also have a separate 2.1 sample).

Which way to u want to go?

... and sit on this PR for just a sec after u respond. I need to touch it based on your guidance.

[tdykstra]

I don't think you need that much detail. I use sample1 and sample2 for 1.x and 2.x.

[guardrex]

If they only say "sample1," "sample2," etc. it might be harder to grok what those are. I'll put in a plug for something like (depending on minor version handling) ...

samples
    1.x
    2.x
    3.x

or

samples
    1.1
    2.0
    2.1
    3.0

However if u met and figured it out that they should just be "sampleX," then I'll just do that here and on the upcoming PR's.

[tdykstra]

I wouldn't say we settled on a rule for everyone to follow; you're welcome to adopt your own pattern here unless Rick/Scott think otherwise. But I think single digits work generally because it's not likely we have to maintain multiple minor versions very often.

[Rick-Anderson]

I though we were only maintaining one sample. Why do we need more than the current?

[scottaddie]

If we decide to maintain more than 1 sample, then I prefer the 1.x, 2.x, 3.x convention.

[guardrex]

I like the 1.x, 2.x, 3.x. It may solve a few problems:

• When someone just lands in the samples folder, they can immediately grok what those are.
• Samples can easily be x.1, x.2,. x.3 at any time on demand with little topic attention required for the samples. The author can just update the sample and concentrate on the topic language for whatever the minor version is offering.
• It limits in a good way what has to be maintained. No worries on keeping samples until the major version reaches the end of support (3 years IIRC). Probably limits total samples per topic to no more than four ... totally manageable I suspect.

I thought we were only maintaining one sample. Why do we need more than the current?

Another great option, but I have a feel'in in my bones: Some enterprise devs will get handed projects and told "add this thing to the project," and it will be, say, a 1.x-era project. Assume that the docs have rolled forward to version 3.0 with only a 3.0 sample showing. They aren't allowed (lack of time and resources) to upgrade the whole project 1.x to 3.0. They could face a big pain point trying to find a 1.x sample from repo history or hitting up random blogs from the era to help them.

But I took your point well on the tutorial comment: I totally get that. NO point in showing a 1.1 sample in a tutorial in the 2.0 or 3.0 era! lol

Stand-by for a sec before merging this. I'll have an update here shortly ... need to just touch it a hair for this. Will ping u soon!

[guardrex]

ok. The "1.1" could have stayed over going to "1.x", except that would make this topic inconsistent with the next three I plan to tackle. In the topic, there's already a note about this feature's first arrival at 1.1. I add a similar note to the 1.x samples. Wherever the reader lands in folders or samples (looking at README files), it should be super-clear what they're seeing.

[guardrex]

The line on dependencies really doesn't work well after all ...

The provider depends on .NET Framework 4.5.1 (ASP.NET Core 1.1), .NET Framework 4.6.1 (ASP.NET Core 2.x), or .NET Standard 1.5 or higher.

• The deps for 1.x are netfx 4.5.1+ or netstd 1.5+; for 2.x just netstd 2.0+ (which implicitly results in netfx 4.6.1+).
• In addition to making the sentence (or list or table) hairy to display/grok, this is going to get out of control as new deps appear with future releases.

... the dev should follow the link and use nuget.org to get the deps ... it's just "a thing" in the new world order.

[Rick-Anderson]

@guardrex what do we need to finish this?

[guardrex]

If he's available, I was hoping @anurse would TAL.

[Rick-Anderson]

@guardrex can you provide a TLDR; executive overview of what should be reviewed?

[guardrex]

@Rick-Anderson There's really one important thing: The new 2.0 sample. It works, but it could benefit from an [@]anurse or other dev team review. We already know that [@]blowdart is good with dropping the "environment" prefix approach of the sample and going with prefixes for the app version (#3525 (comment); however, their sample still needs work imo aspnet/Configuration#708).

Flipping over to the diff view and searching the page with key-name-prefix-sample/2.x will show the files of the 2.0 sample at the bottom of the diff.

I feel good with @scottaddie's review on the rest of it.

[guardrex]

@Rick-Anderson Samples updated here. 👍

[Rick-Anderson]

@guardrex ready to merge?

[guardrex]

@Rick-Anderson Yes, ready to 🎸!