Add support for exposing decorated services

Author: adamjones2

src/Scrutor/DecoratedService.cs

@@ -0,0 +1,26 @@
+using System;
+using System.Collections.Generic;
+
+namespace Scrutor;
+
+/// <summary>
+/// A handle to a decorated service. This can be used to resolve decorated services from an <see cref="IServiceProvider"/>
+/// using <see cref="ServiceProviderExtensions.GetRequiredDecoratedService{TService}(IServiceProvider, DecoratedService{TService})"/>.
+/// </summary>
+/// <typeparam name="TService">The type of services which were decorated.</typeparam>
+public sealed class DecoratedService<TService>
+{
+    internal DecoratedService(Type serviceType, IReadOnlyList<string> serviceKeys)
+    {
+        if (!typeof(TService).IsAssignableFrom(serviceType))
+            throw new ArgumentException($"The type {serviceType} is not assignable to the service type {typeof(TService)}");
+
+        ServiceType = serviceType;
+        ServiceKeys = serviceKeys;
+    }
+
+    internal Type ServiceType { get; }
+    internal IReadOnlyList<string> ServiceKeys { get; } // In descending order of precedence
+
+    internal DecoratedService<TService2> Downcast<TService2>() => new(ServiceType, ServiceKeys);
+}

src/Scrutor/MaybeNullWhenAttribute.cs

@@ -0,0 +1,19 @@
+#if NETFRAMEWORK
+
+using System;
+
+/// <summary>Specifies that when a method returns <see cref="ReturnValue"/>, the parameter will not be null even if the corresponding type allows it.</summary>
+[AttributeUsage(AttributeTargets.Parameter, Inherited = false)]
+internal sealed class NotNullWhenAttribute : Attribute
+{
+    /// <summary>Initializes the attribute with the specified return value condition.</summary>
+    /// <param name="returnValue">
+    /// The return value condition. If the method returns this value, the associated parameter will not be null.
+    /// </param>
+    public NotNullWhenAttribute(bool returnValue) => ReturnValue = returnValue;
+
+    /// <summary>Gets the return value condition.</summary>
+    public bool ReturnValue { get; }
+}
+
+#endif