Current dotnet/extensions API Surface

[geeknoid]

Please review to make sure you're happy with:

• Package names
• Namespace names
• Type names
• Method names

Last chance to speak up before November is upon us.

Microsoft Reviewers: Open in CodeFlow

[RussKie]

Gone through the NoDocs

[geeknoid]

@danmoseley Please don't push commits to this PR. This is all auto-generated stuff, so any edits will be lost.

[danmoseley]

@geeknoid is all feedback addressed -- or more to the point, this API dump is now out of date with changes you've made?

maybe we should close this now?

edit: oh, Jose pointed out that you're keeping this up to date.

[sebastienros]

Is it missing public static IServiceCollection AddFakeRedaction(this IServiceCollection services, IConfigurationSection section);

[JamesNK]

I'm not a fan of the shape of CounterAttribute and friends. I could imagine someone entering [Counter("my.cool.counter.name")] and expecting a counter with that name but instead accidentally calling the CounterAttribute(params string[] tagNames) ctor and getting a counter with an inferred name and tag named my.cool.counter.name instead. Feels like pit of failure.

The most significant piece of information for a counter is its name. It should be in the constructor. Also, it should always be required. Infering it from a return type doesn't feel good. Thought should be put into the name.

Also, the Type property name isn't descriptive. TagsType is still a little confusing because tags can have a type but I can't think of a better name.

Suggested change

	public sealed class CounterAttribute : Attribute
	{
	public string? Name { get; set; }
	public string[]? TagNames { get; }
	public Type? Type { get; }
	public CounterAttribute(params string[] tagNames);
	public CounterAttribute(Type type);
	}
	public sealed class CounterAttribute : Attribute
	{
	public string? Name { get; }
	public string[]? TagNames { get; set; }
	public Type? TagsType { get; set; }
	public CounterAttribute(string name);
	}

Usage:

[Counter("my.cool.counter.name", TagNames = [ "one", "two", "etc" ])]

If someone sets TagNames and TagType then throw an error.

[xakep139]

@geeknoid @dariusclay @iliar-turdushev folks, any thoughts here?
Personally I see the point of the suggested change, but @JamesNK please bear in mind that by default the source-gen will take a type's name as an instrument name, that's why its API was made that way.

[iliar-turdushev]

I'm good with the suggestion, but it will be a breaking change for existing customers, and complicate their migration to dotnet/extensions. Is it OK?

The only change I'd make to the suggestion is mark name argument as optional:

public CounterAttribute(string? name = null);

If name is null then we infer the name of a counter from the return type of a method.

[geeknoid]

This comment could have been addressed a few weeks back, but now it's too late. We can no longer do breaking changes in dotnet/extensions. So let's improve this incrementally when possible, without breaking things.

[Tratcher]

These extensions should be in the same namespace as their extended types, IWebHostBuilder and IHost (even if it means splitting the class). I'll take care of that.