Aspnetcore.docs: Missing a step

[rjamesnw]

Nothing was working until I found an example that added a required line to the startup constructor:

if (env.IsDevelopment())
{
    builder.AddUserSecrets();
}

You might want to add that vital piece of info. :/

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 9c99993c-c983-6fda-6c3a-ce4ec8c1d5db
• Version Independent ID: ba688ac2-e90e-fce5-f60d-40c2553c3efd
• Content: Safe storage of app secrets in development in ASP.NET Core
• Content Source: aspnetcore/security/app-secrets.md
• Service: unspecified
• Product: asp.net-core
• GitHub Login: @Rick-Anderson
• Microsoft Alias: scaddie

[guardrex]

This probably happened because it was assumed that CreateDefaultBuilder would be in use, which adds it auto-magically ...

https://github.com/aspnet/MetaPackages/blob/dev/src/Microsoft.AspNetCore/WebHost.cs#L165-L172

As you suggest @rjamesnw, that's not a good idea. I'll add a paragraph to cover it. Thanks for bringing this to our attention.

[guardrex]

I just discovered this was recently addressed by #6488. Thanks @rjamesnw for mentioning it. The new content should go live shortly.

[guardrex]

@rjamesnw We discussed it, and we're going add a hair more info to call out how CreateDefaultBuilder calls AddUserSecrets under-the-covers and that if CreateDefaultBuilder isn't called when building the host that the dev should then do as you suggest :point_up: on their own.

[rjamesnw]

Also you need to confirm if the secrets tool is really bundled. I have the latest SDK installed and it is NOT bundled by default for new projects (as your help site claims). I had to add DotNetCliToolReference to my project file else the command line wouldn’t work. Also tool version 2.0.2 is required with Core 2.0 so you need to add that also.

[guardrex]

It was covered here :point_right: https://docs.microsoft.com/aspnet/core/security/app-secrets?view=aspnetcore-2.0&tabs=windows#install-the-secret-manager-tool. The likely reason that 1.0.1 is shown and not a 2.0 approach is that we expect all devs to upgrade from 2.0 to 2.1, thus all devs will get global tool installs with 2.1. That's the plan AFAIK anyway. @scottaddie Do you have additional thoughts?

[rjamesnw]

You totally missed my point. I know it is there, I even alluded to it. I’m telling you I have 2.1 installed and the tool is NOT available anywhere until I “install” the Nugget package into my project. Is it stands, following the steps on the page for 2.1 like I did does not supply any tools at all.

[guardrex]

the latest SDK

Yes, I see what you mean now. The "latest (released) SDK" is 2.0 ... threw me off for a sec.

Idk if it will help, but they're working on the PR to cover global tools here :point_right: https://github.com/dotnet/docs/pull/5036 ... there might be some troubleshooting/gotcha info in their topic(s) on that PR. [EDIT] For example, feeds can be a problem to address with the pre-release bits.

Idk on the 2.1 SDK not installing the Secret Manager tool specifically. Scott will be along at some point and may be able to help.

[scottaddie]

@natemcmaster If using the .NET Core 2.1 SDK with an ASP.NET Core 2.0 app, I assume the <DotNetCliToolReference /> node is needed in the *.csproj file. Thoughts?

[natemcmaster]

Unfortunately, the "2.1 SDK" is a bit ambiguous¹. You will need the <DotNetCliToolReference /> if and only if dotnet --version < 2.1.300. The important bit is the third part of that version number. The latest stable SDK is 2.1.200, which does not have dotnet user-secrets bundled yet. We're expecting to ship 2.1.300 soon, but it's still only available as an RC.. Once you upgrade to 2.1.300 or newer, you will not need the <DotNetCliToolReference />.

Also, it's important to note that this is independent of the version of ASP.NET Core. You can use the 2.1.300 SDK for any version of ASP.NET, all the way back to 1.0.

¹Starting with the 2.1.300 SDK, we plan to make sure the major.minor version of the SDK matches the latest .NET Core runtime it bundles. See https://github.com/dotnet/designs/pull/29

[guardrex]

@scottaddie That covers most of the problem, but I'm concerned about this ...

For .NET Core SDK 2.0 and earlier, tool installation is necessary.

https://docs.microsoft.com/aspnet/core/security/app-secrets#install-the-secret-manager-tool

... leading right into an example with a 1.x era tool install.

We probably don't care too much about 2.0 because our general plan is to cover the latest 2.x release (i.e., 2.1). For that line to call out "SDK 2.0" given what @natemcmaster just said is of concern. We should consider either spelling out all of the caveats of the 2.0-era (_yuck!_ :sweat:) or make that line read ...

For .NET Core SDK 1.1 and earlier, tool installation is necessary.

The sentence immediately prior to that ...

The Secret Manager tool is bundled with the .NET Core CLI in .NET Core SDK 2.1.

... is good. :+1: We can leave it at that given that we want devs to choose 2.1 over 2.0.

Whatever we do, I think we should moniker-range the content coverage.

[rjamesnw]

That’s fine, but it would have saved me lots of time to see a note at least that “tool installation is necessary if you have 2.1.200 or earlier” since I DID have it, and many others in company environments may also have it and not able to update on the bleeding edge. ;)

[guardrex]

Yes, but 2.1 won't be bleeding edge on May 30. I defer to @scottaddie and @Rick-Anderson how much 2.0 coverage they want. I'm slammed for the next few weeks, and I only have time to make the updates I suggested above :point_up:. If they decide to do more, I request another author take on the task.

[scottaddie]

I think it's important that we specify the exact SDK version that includes the tool. I say this because the older SDKs are always available for download on the All Downloads page. I can take care of the updates on this one.

[guardrex]

Thanks @scottaddie ... I'm trying hard now to wrap things up.

[scottaddie]

@rjamesnw Thank you for your valuable feedback. The doc changes are live now.