Distinguish case sensitivity for NuGet.Config keys

[donnie-msft]

"always" case sensitive is misleading, as it makes it sound like adding a new key with a different case should be acceptable.
My goal is to clarify that keys are referenced in a case-sensitive manner.
Adding "nuget.org" and "nuGet.org" though should be denied by NuGet tooling as they are not unique (case-insensitive).

[learn-build-service-prod]

Learn Build status updates of commit 7d73d00:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/consume-packages/configuring-nuget-behavior.md	✅Succeeded	View

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[nkolev92]

This sounds like a developer guide instead of a user facing doc.

I think you can tweak the phrasing to communicate the same thing in a slightly different way.

Suggested change

	- Keys are case sensitive when being referenced. New keys must be unique regardless of casing (case insensitive) .
	Keys are case sensitive, but they always unique regardless of casing.

You don't have to accept my suggestion, but just an idea that I found more in style with the rest of the doc.

[donnie-msft]

I don't find that more clear, so I'll let others chime in.

[nkolev92]

I think it's fair to question whether my proposal is good enough, but New keys must be unique regardless of casing (case insensitive) . currently is aimed the nuget devs since we're the only ones that can add new keys and we're not the audience for this doc.

[donnie-msft]

Who is the target audience for this document? I thought if a customer is consuming packages, that means they are modifying nuget.configs, which they need to know the 2 points:

1. that it matters what casing they use for their keys
2. once a casing is created, another casing for the same key cannot be used

[donnie-msft]

    <packageSources>
        <add key="Contoso Package Source" value="https://contoso.com/packages/" />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    </packageSources>

Here's a sample from the document. We need to say that this is invalid for a customer to add:
<add key="CONTOSO Package Source" value="https://contoso123.com/packages/" />

and that this is wrong given the above sample:

<disabledPackageSources>
        <add key="NUGET.org" value="true" />
 </disabledPackageSources>

and

 <packageSourceMapping>
    <clear />
    <packageSource key="nuGeT.OrG">
      <package pattern="Azure.Core" />
    </packageSource>

[nkolev92]

I think the doc you are changing is talking about the <config> section of the nuget.config file.

Keys such as globalPackagesFolder etc, not the sources.

[nkolev92]

Now that I read more of it, it never mentions keys such as sources/package source mapping, while it probably should, or at least link to a page that does.

[zivkan]

For what it's worth, I find it all a bit confusing, and I've been working on NuGet for years 😕

This PR's proposal "Keys are case sensitive when being referenced", I'm not really sure what "being refereced" is referring to. Does this mean if I have <add key="globalpackagesfolder" value="d:\nuget\packages" /> the setting will be silently ignored, because it must be globalPackagesFolder? If so, that sounds like a product bug that we should change, rather than document.

Same for dotnet push my.nupkg -s mysource. If the config file has it defined as MySource, are the docs telling me this will fail? Again, to me that sounds like a product bug we should fix, rather than document.

Donnie has a comment in this thread saying that customers adding new sources need to make the keys unique (case insensitive), which I can understand. What I don't understand are the scenarios when they are case sensitive, and whether it makes sense for our product to treat them as case sensitive or if it feel like a bug from a customer experience point of view.

[donnie-msft]

For "being referenced", I gave 2 examples here #3260 (comment)

As far as making product changes, that should be a NuGet/Home issue, not a docs issue. I'm just trying to make the docs point out what the product does now, not what makes sense to change (which would be another docs change once the product change is released).