Expose dependency injection on the transport seam (#7570)

* Expose the service provider on the transport seam

* Move up and improve documentation

* Remove using

* Improve service collection and dependency injection access (#7571)

* Improve service collection and dependency injection access

* IsRawMode

---------

Co-authored-by: Daniel Marbach <[email protected]>

* Remove no longer needed assert

---------

Co-authored-by: Daniel Marbach <[email protected]>
Co-authored-by: Daniel Marbach <[email protected]>

Author: andreasohlund

src/NServiceBus.AcceptanceTesting/AcceptanceTestingTransport/AcceptanceTestingTransport.cs

@@ -42,4 +42,4 @@ public string? StorageLocation
             field = value;
         }
     }
-}
+}

src/NServiceBus.AcceptanceTests/Core/TransportSeam/When_transport_provides_feature.cs

@@ -0,0 +1,46 @@
+namespace NServiceBus.AcceptanceTests.Core.TransportSeam;
+
+using System.Threading.Tasks;
+using AcceptanceTesting;
+using EndpointTemplates;
+using Features;
+using NUnit.Framework;
+using Transport;
+
+public class When_transport_provides_feature : NServiceBusAcceptanceTest
+{
+    [Test]
+    public async Task Should_setup_feature()
+    {
+        var context = await Scenario.Define<Context>()
+            .WithEndpoint<EndpointWithFeature>()
+            .Done(c => c.EndpointsStarted)
+            .Run();
+
+        Assert.That(context.TransportFeatureRan, Is.True);
+    }
+
+    class Context : ScenarioContext
+    {
+        public bool TransportFeatureRan { get; set; }
+    }
+
+    class EndpointWithFeature : EndpointConfigurationBuilder
+    {
+        public EndpointWithFeature() => EndpointSetup<DefaultServer>(c => c.UseTransport(new CustomAcceptanceTestingTransport()));
+    }
+
+    class CustomAcceptanceTestingTransport : AcceptanceTestingTransport
+    {
+        public CustomAcceptanceTestingTransport() => EnableEndpointFeature<FeatureAccessingInfrastructure>();
+
+        class FeatureAccessingInfrastructure : Feature
+        {
+            protected override void Setup(FeatureConfigurationContext context)
+            {
+                var testContext = (Context)context.Settings.Get<ScenarioContext>();
+                testContext.TransportFeatureRan = true;
+            }
+        }
+    }
+}

src/NServiceBus.AcceptanceTests/Core/TransportSeam/When_transports_needs_access_to_di.cs

@@ -0,0 +1,51 @@
+namespace NServiceBus.AcceptanceTests.Core.TransportSeam;
+
+using System.Threading;
+using System.Threading.Tasks;
+using AcceptanceTesting;
+using EndpointTemplates;
+using Microsoft.Extensions.DependencyInjection;
+using NUnit.Framework;
+using Transport;
+
+public class When_transport_needs_access_to_di : NServiceBusAcceptanceTest
+{
+    [Test]
+    public async Task Should_be_able_to_resolve_dependencies()
+    {
+        var context = await Scenario.Define<Context>()
+            .WithEndpoint<EndpointWithFeature>()
+            .Done(c => c.EndpointsStarted)
+            .Run();
+
+        Assert.That(context.TransportDependencyResolved, Is.True);
+    }
+
+    class Context : ScenarioContext
+    {
+        public bool TransportDependencyResolved { get; set; }
+    }
+
+    class EndpointWithFeature : EndpointConfigurationBuilder
+    {
+        public EndpointWithFeature() => EndpointSetup<DefaultServer>(c => c.UseTransport(new CustomAcceptanceTestingTransport()));
+    }
+
+    class CustomAcceptanceTestingTransport : AcceptanceTestingTransport
+    {
+        protected override void ConfigureServicesCore(IServiceCollection services) => services.AddSingleton<TransportService>();
+
+        public override Task<TransportInfrastructure> Initialize(HostSettings hostSettings, ReceiveSettings[] receivers, string[] sendingAddresses, CancellationToken cancellationToken = default)
+        {
+            if (hostSettings.SupportsDependencyInjection)
+            {
+                var serviceProvider = hostSettings.ServiceProvider;
+                var context = serviceProvider.GetRequiredService<Context>();
+                context.TransportDependencyResolved = serviceProvider.GetService<TransportService>() is not null;
+            }
+            return base.Initialize(hostSettings, receivers, sendingAddresses, cancellationToken);
+        }
+
+        class TransportService;
+    }
+}

src/NServiceBus.Core.Tests/ApprovalFiles/APIApprovals.ApproveNServiceBus.approved.txt

@@ -2317,9 +2317,16 @@ namespace NServiceBus.Transport
         public NServiceBus.Settings.IReadOnlySettings? CoreSettings { get; }
         public System.Action<string, System.Exception, System.Threading.CancellationToken> CriticalErrorAction { get; }
         public string HostDisplayName { get; }
+        [System.Diagnostics.CodeAnalysis.MemberNotNullWhen(false, "CoreSettings")]
+        [get: System.Diagnostics.CodeAnalysis.MemberNotNullWhen(false, "CoreSettings")]
+        public bool IsRawMode { get; }
         public string Name { get; }
+        public System.IServiceProvider? ServiceProvider { get; set; }
         public bool SetupInfrastructure { get; }
         public NServiceBus.StartupDiagnosticEntries StartupDiagnostic { get; }
+        [System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "ServiceProvider")]
+        [get: System.Diagnostics.CodeAnalysis.MemberNotNullWhen(true, "ServiceProvider")]
+        public bool SupportsDependencyInjection { get; }
     }
     public interface IMessageDispatcher
     {
@@ -2429,6 +2436,8 @@ namespace NServiceBus.Transport
         public bool SupportsPublishSubscribe { get; }
         public bool SupportsTTBR { get; }
         public virtual NServiceBus.TransportTransactionMode TransportTransactionMode { get; set; }
+        public void ConfigureServices(Microsoft.Extensions.DependencyInjection.IServiceCollection services) { }
+        protected virtual void ConfigureServicesCore(Microsoft.Extensions.DependencyInjection.IServiceCollection services) { }
         protected void EnableEndpointFeature<T>()
             where T : NServiceBus.Features.Feature, new () { }
         public abstract System.Collections.Generic.IReadOnlyCollection<NServiceBus.TransportTransactionMode> GetSupportedTransactionModes();

src/NServiceBus.Core/EndpointCreator.cs

@@ -169,7 +169,7 @@ void ConfigureMessageTypes(IEnumerable<Type> messageTypesHandled)
         });
     }
 
-    public StartableEndpoint CreateStartableEndpoint(IServiceProvider builder, bool serviceProviderIsExternallyManaged)
+    public StartableEndpoint CreateStartableEndpoint(IServiceProvider serviceProvider, bool serviceProviderIsExternallyManaged)
     {
         hostingConfiguration.AddStartupDiagnosticsSection("Container", new
         {
@@ -184,7 +184,7 @@ public StartableEndpoint CreateStartableEndpoint(IServiceProvider builder, bool
             recoverabilityComponent,
             hostingComponent,
             sendComponent,
-            builder,
+            serviceProvider,
             serviceProviderIsExternallyManaged);
     }
 

src/NServiceBus.Core/StartableEndpoint.cs

@@ -25,7 +25,7 @@ class StartableEndpoint(
 
     public async Task Setup(CancellationToken cancellationToken = default)
     {
-        transportInfrastructure = await transportSeam.CreateTransportInfrastructure(cancellationToken).ConfigureAwait(false);
+        transportInfrastructure = await transportSeam.CreateTransportInfrastructure(serviceProvider, cancellationToken).ConfigureAwait(false);
 
         var pipelineCache = pipelineComponent.BuildPipelineCache(serviceProvider);
         var messageOperations = sendComponent.CreateMessageOperations(serviceProvider, pipelineComponent);

src/NServiceBus.Core/Transports/HostSettings.cs

@@ -3,6 +3,7 @@
 namespace NServiceBus.Transport;
 
 using System;
+using System.Diagnostics.CodeAnalysis;
 using System.Threading;
 using Settings;
 
@@ -14,12 +15,38 @@ namespace NServiceBus.Transport;
 /// </remarks>
 public class HostSettings(string name, string hostDisplayName, StartupDiagnosticEntries startupDiagnostic, Action<string, Exception, CancellationToken> criticalErrorAction, bool setupInfrastructure, IReadOnlySettings? coreSettings = null)
 {
+    /// <summary>
+    /// Indicates whether the transport is running in the raw mode not hosted inside an NServiceBus endpoint.
+    /// </summary>
+    /// <remarks>
+    /// This property returns <c>true</c> if the transport is running in the raw mode not hosted inside an NServiceBus endpoint; otherwise, <c>false</c> indicating the transports is running inside an NServiceBus endpoint.</remarks>
+    [MemberNotNullWhen(false, nameof(CoreSettings))]
+    public bool IsRawMode => CoreSettings is null;
+
+    /// <summary>
+    /// Indicates whether the transport supports dependency injection.
+    /// </summary>
+    /// <remarks>
+    /// This property returns <c>true</c> if the associated service provider is initialized; otherwise, <c>false</c>. When the endpoint is running in an NServiceBus endpoint (<see cref="IsRawMode"/> set to <c>false</c>),
+    /// this property will always return <c>true</c>.
+    /// In raw mode (<see cref="IsRawMode"/> set to <c>true</c>), this property will return <c>false</c> unless the hosting infrastructure has initialized the service provider and assigned it to the <see cref="ServiceProvider"/> property before the transport definition is initialized.
+    /// Transport implementations can use this property to determine whether they can resolve dependencies from the service provider during initialization.
+    /// </remarks>
+    [MemberNotNullWhen(true, nameof(ServiceProvider))]
+    public bool SupportsDependencyInjection => ServiceProvider is not null;
+
     /// <summary>
     /// Settings available only when running hosted in an NServiceBus endpoint; Otherwise, <c>null</c>.
     /// Transports can use these settings to validate the hosting endpoint settings.
     /// </summary>
     public IReadOnlySettings? CoreSettings { get; } = coreSettings;
 
+    /// <summary>
+    /// Service provider available only when running hosted in an NServiceBus endpoint; Otherwise, <c>null</c>.
+    /// Transports can use the provider in hosted scenarios to resolve dependencies from the provider.
+    /// </summary>
+    public IServiceProvider? ServiceProvider { get; set; }
+
     /// <summary>
     /// A name that describes the host (e.g. the endpoint name).
     /// </summary>
@@ -44,4 +71,4 @@ public class HostSettings(string name, string hostDisplayName, StartupDiagnostic
     /// A flag that indicates whether the transport should automatically setup necessary infrastructure.
     /// </summary>
     public bool SetupInfrastructure { get; } = setupInfrastructure;
-}
+}

src/NServiceBus.Core/Transports/TransportDefinition.cs

@@ -8,6 +8,7 @@ namespace NServiceBus.Transport;
 using System.Threading;
 using System.Threading.Tasks;
 using Features;
+using Microsoft.Extensions.DependencyInjection;
 using Settings;
 
 /// <summary>
@@ -16,7 +17,7 @@ namespace NServiceBus.Transport;
 public abstract class TransportDefinition
 {
     TransportTransactionMode transportTransactionMode;
-    List<IEnabled>? featuresToEnable;
+    readonly List<IEnabled> featuresToEnable = [Enabled<TransportServiceCollectionProviderFeature>.Instance];
 
     /// <summary>
     /// Creates a new transport definition.
@@ -35,11 +36,7 @@ protected TransportDefinition(TransportTransactionMode defaultTransactionMode, b
     /// </summary>
     /// <remarks>This method needs to be called within the constructor(s) of the transport definition.</remarks>
     /// <typeparam name="T">The feature to enable.</typeparam>
-    protected void EnableEndpointFeature<T>() where T : Feature, new()
-    {
-        featuresToEnable ??= [];
-        featuresToEnable.Add(Enabled<T>.Instance);
-    }
+    protected void EnableEndpointFeature<T>() where T : Feature, new() => featuresToEnable.Add(Enabled<T>.Instance);
 
     /// <summary>
     /// Initializes transport factories and transport-specific behavior.
@@ -87,13 +84,31 @@ public virtual TransportTransactionMode TransportTransactionMode
     /// </summary>
     public bool SupportsTTBR { get; }
 
-    internal void Configure(SettingsHolder settings)
+    /// <summary>
+    /// Allows the transport to register required services into the service collection.
+    /// </summary>
+    /// <remarks>During hosted scenarios, this method is called by the hosting infrastructure to register transport-specific services
+    /// and the service provider containing the registered services is passed over the <see cref="HostSettings"/> into the <see cref="Initialize"/> method.
+    /// In raw transport scenarios it is the responsibility of the custom hosting infrastructure to call this method during service registration time
+    /// and <see cref="Initialize"/> when the service provider is available. Transports should be designed to work in both modes and only every attempt to resolve
+    /// dependencies when the corresponding service provider is available in the <see cref="HostSettings"/> indicated by <see cref="HostSettings.SupportsDependencyInjection"/>.</remarks>
+    /// <param name="services">The service collection to register services into.</param>
+    public void ConfigureServices(IServiceCollection services)
     {
-        if (featuresToEnable is null)
-        {
-            return;
-        }
+        ArgumentNullException.ThrowIfNull(services);
+        ConfigureServicesCore(services);
+    }
+
+    /// <summary>
+    /// Allows the transport to register required services into the service collection.
+    /// </summary>
+    /// <param name="services">The service collection to register services into.</param>
+    protected virtual void ConfigureServicesCore(IServiceCollection services)
+    {
+    }
 
+    internal void Configure(SettingsHolder settings)
+    {
         foreach (var featureToEnable in featuresToEnable)
         {
             featureToEnable.Apply(settings);
@@ -116,4 +131,9 @@ sealed class Enabled<TFeature> : IEnabled
 
         public void Apply(SettingsHolder settingsHolder) => settingsHolder.EnableFeature<TFeature>();
     }
+
+    sealed class TransportServiceCollectionProviderFeature : Feature
+    {
+        protected override void Setup(FeatureConfigurationContext context) => context.Settings.Get<TransportDefinition>().ConfigureServices(context.Services);
+    }
 }

src/NServiceBus.Core/Transports/TransportSeam.cs

@@ -15,13 +15,14 @@ class TransportSeam(TransportDefinition transportDefinition, HostSettings hostSe
     // The dependency in IServiceProvider ensures that the TransportInfrastructure can't be resolved too early.
     public TransportInfrastructure GetTransportInfrastructure(IServiceProvider _) => transportInfrastructure;
 
-    public async Task<TransportInfrastructure> CreateTransportInfrastructure(CancellationToken cancellationToken = default)
+    public async Task<TransportInfrastructure> CreateTransportInfrastructure(IServiceProvider serviceProvider, CancellationToken cancellationToken = default)
     {
         if (OperatingSystem.IsWindows() && TransportDefinition.TransportTransactionMode == TransportTransactionMode.TransactionScope)
         {
             TransactionManager.ImplicitDistributedTransactions = true;
         }
 
+        hostSettings.ServiceProvider = serviceProvider;
         transportInfrastructure = await TransportDefinition.Initialize(hostSettings, receiverSettings, [.. QueueBindings.SendingAddresses], cancellationToken)
             .ConfigureAwait(false);