Docs for members in DependencyInjection.Abstractions lack exception information.

[ericstj]

Description

I heard feedback that folks felt the docs for AddSingleton lacked good information about when it would fail and why.

I took a look and I agree. It seems that whenever we have a method with a corresponding Try method, we should be sure to include the exception docs. That will help folks if they need to use the Try method always, or if they would prefer to just use the non-try method for simpler code and treat the exception case as an invalid configuration.

Reproduction Steps

Have a look at docs https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.servicecollectionserviceextensions.addsingleton?view=net-8.0

Expected behavior

Information about meaningful thrown exceptions exists.

Actual behavior

No information exists

Regression?

No response

Known Workarounds

No response

Configuration

No response

Other information

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-dependencyinjection
See info in area-owners.md if you want to be subscribed.

[KalleOlaviNiemitalo]

The difference between AddSingleton and TryAddSingleton is not like the difference between Int32.Parse and Int32.TryParse.

TryAddSingleton is not a way to avoid exceptions that AddSingleton would throw. Rather, the difference is in what happens if an implementation has already been added for the service. In that case, TryAddSingleton returns false and does not add the new implementation. In contrast, AddSingleton adds the new implementation regardless, so the service will then have two implementations; GetService(typeof(TService)) will return the last one registered, but GetService(typeof(IEnumerable<TService>)) will return both.