| | | 1 | | using NexusLabs.Needlr.Generators; |
| | | 2 | | using NexusLabs.Needlr.Injection.Reflection; |
| | | 3 | | using NexusLabs.Needlr.Injection.SourceGen; |
| | | 4 | | |
| | | 5 | | using System.Diagnostics.CodeAnalysis; |
| | | 6 | | |
| | | 7 | | namespace NexusLabs.Needlr.Injection.Bundle; |
| | | 8 | | |
| | | 9 | | /// <summary> |
| | | 10 | | /// Extension methods that provide automatic fallback between source-generated and reflection-based components. |
| | | 11 | | /// </summary> |
| | | 12 | | /// <remarks> |
| | | 13 | | /// <para> |
| | | 14 | | /// When using the Bundle package, Needlr will automatically: |
| | | 15 | | /// <list type="number"> |
| | | 16 | | /// <item>Try to use source-generated components if available (via NeedlrSourceGenBootstrap)</item> |
| | | 17 | | /// <item>Fall back to reflection-based components if source generation is not configured</item> |
| | | 18 | | /// </list> |
| | | 19 | | /// </para> |
| | | 20 | | /// <para> |
| | | 21 | | /// Use <see cref="WithFallbackBehavior"/> to configure the fallback behavior, or |
| | | 22 | | /// <see cref="WithFastFailOnReflection"/> to throw if reflection is used. |
| | | 23 | | /// </para> |
| | | 24 | | /// </remarks> |
| | | 25 | | public static class SyringeBundleExtensions |
| | | 26 | | { |
| | | 27 | | /// <summary> |
| | | 28 | | /// Configures the syringe with automatic fallback from source-gen to reflection. |
| | | 29 | | /// </summary> |
| | | 30 | | /// <remarks> |
| | | 31 | | /// <para> |
| | | 32 | | /// This method automatically detects whether source generation is available |
| | | 33 | | /// and configures the appropriate components. If source-generated providers |
| | | 34 | | /// are registered via NeedlrSourceGenBootstrap, they will be used. Otherwise, |
| | | 35 | | /// reflection-based components are used as fallback. |
| | | 36 | | /// </para> |
| | | 37 | | /// </remarks> |
| | | 38 | | /// <param name="syringe">The syringe to configure.</param> |
| | | 39 | | /// <returns>A configured syringe ready for further configuration and building.</returns> |
| | | 40 | | [UnconditionalSuppressMessage("Trimming", "IL2026:RequiresUnreferencedCode", |
| | | 41 | | Justification = "Reflection components are only used when source-gen is not available.")] |
| | | 42 | | public static ConfiguredSyringe UsingAutoConfiguration(this Syringe syringe) |
| | | 43 | | { |
| | 4 | 44 | | ArgumentNullException.ThrowIfNull(syringe); |
| | | 45 | | |
| | 3 | 46 | | if (NeedlrSourceGenBootstrap.TryGetProviders( |
| | 3 | 47 | | out var injectableTypeProvider, |
| | 3 | 48 | | out var pluginTypeProvider, |
| | 3 | 49 | | out var registryParticipantTypes)) |
| | | 50 | | { |
| | 2 | 51 | | var configured = new ConfiguredSyringe(syringe) with |
| | 2 | 52 | | { |
| | 2 | 53 | | ServiceProviderBuilderFactory = (populator, assemblyProvider, additionalAssemblies) => |
| | 0 | 54 | | new ServiceProviderBuilder(populator, assemblyProvider, additionalAssemblies) |
| | 2 | 55 | | }; |
| | 2 | 56 | | return configured.UsingGeneratedComponents( |
| | 2 | 57 | | injectableTypeProvider, |
| | 2 | 58 | | pluginTypeProvider, |
| | 2 | 59 | | registryParticipantTypes); |
| | | 60 | | } |
| | | 61 | | |
| | | 62 | | // Fallback to reflection |
| | 1 | 63 | | var reflectionSyringe = syringe.UsingReflection(); |
| | 1 | 64 | | return reflectionSyringe with |
| | 1 | 65 | | { |
| | 1 | 66 | | ServiceProviderBuilderFactory = (populator, assemblyProvider, additionalAssemblies) => |
| | 0 | 67 | | new ServiceProviderBuilder(populator, assemblyProvider, additionalAssemblies) |
| | 1 | 68 | | }; |
| | | 69 | | } |
| | | 70 | | |
| | | 71 | | /// <summary> |
| | | 72 | | /// Configures the syringe with automatic fallback and a custom fallback handler. |
| | | 73 | | /// </summary> |
| | | 74 | | /// <param name="syringe">The syringe to configure.</param> |
| | | 75 | | /// <param name="onFallback">Called when reflection fallback occurs. Can be used for logging or to throw.</param> |
| | | 76 | | /// <returns>A configured syringe ready for further configuration and building.</returns> |
| | | 77 | | [UnconditionalSuppressMessage("Trimming", "IL2026:RequiresUnreferencedCode", |
| | | 78 | | Justification = "Reflection components are only used when source-gen is not available.")] |
| | | 79 | | public static ConfiguredSyringe WithFallbackBehavior( |
| | | 80 | | this Syringe syringe, |
| | | 81 | | Action<ReflectionFallbackContext>? onFallback) |
| | | 82 | | { |
| | 5 | 83 | | ArgumentNullException.ThrowIfNull(syringe); |
| | | 84 | | |
| | 4 | 85 | | if (NeedlrSourceGenBootstrap.TryGetProviders( |
| | 4 | 86 | | out var injectableTypeProvider, |
| | 4 | 87 | | out var pluginTypeProvider, |
| | 4 | 88 | | out var registryParticipantTypes)) |
| | | 89 | | { |
| | 3 | 90 | | var configured = new ConfiguredSyringe(syringe) with |
| | 3 | 91 | | { |
| | 3 | 92 | | ServiceProviderBuilderFactory = (populator, assemblyProvider, additionalAssemblies) => |
| | 0 | 93 | | new ServiceProviderBuilder(populator, assemblyProvider, additionalAssemblies) |
| | 3 | 94 | | }; |
| | 3 | 95 | | return configured.UsingGeneratedComponents( |
| | 3 | 96 | | injectableTypeProvider, |
| | 3 | 97 | | pluginTypeProvider, |
| | 3 | 98 | | registryParticipantTypes); |
| | | 99 | | } |
| | | 100 | | |
| | | 101 | | // Invoke fallback handler if provided |
| | 1 | 102 | | if (onFallback is not null) |
| | | 103 | | { |
| | 1 | 104 | | onFallback(ReflectionFallbackHandlers.CreateTypeRegistrarContext()); |
| | | 105 | | } |
| | | 106 | | |
| | 1 | 107 | | var reflectionSyringe = syringe.UsingReflection(); |
| | 1 | 108 | | return reflectionSyringe with |
| | 1 | 109 | | { |
| | 1 | 110 | | ServiceProviderBuilderFactory = (populator, assemblyProvider, additionalAssemblies) => |
| | 0 | 111 | | new ServiceProviderBuilder(populator, assemblyProvider, additionalAssemblies) |
| | 1 | 112 | | }; |
| | | 113 | | } |
| | | 114 | | |
| | | 115 | | /// <summary> |
| | | 116 | | /// Configures the syringe to throw an exception if reflection fallback would occur. |
| | | 117 | | /// </summary> |
| | | 118 | | /// <remarks> |
| | | 119 | | /// Use this in AOT/trimming scenarios to ensure that source-generated components are always used. |
| | | 120 | | /// If no source-generated providers are registered, an <see cref="InvalidOperationException"/> is thrown. |
| | | 121 | | /// </remarks> |
| | | 122 | | /// <param name="syringe">The syringe to configure.</param> |
| | | 123 | | /// <returns>A configured syringe ready for further configuration and building.</returns> |
| | | 124 | | public static ConfiguredSyringe WithFastFailOnReflection(this Syringe syringe) |
| | | 125 | | { |
| | 2 | 126 | | ArgumentNullException.ThrowIfNull(syringe); |
| | | 127 | | |
| | 1 | 128 | | return syringe.WithFallbackBehavior(ReflectionFallbackHandlers.ThrowException); |
| | | 129 | | } |
| | | 130 | | |
| | | 131 | | /// <summary> |
| | | 132 | | /// Configures the syringe to log warnings when reflection fallback occurs. |
| | | 133 | | /// </summary> |
| | | 134 | | /// <param name="syringe">The syringe to configure.</param> |
| | | 135 | | /// <returns>A configured syringe ready for further configuration and building.</returns> |
| | | 136 | | [UnconditionalSuppressMessage("Trimming", "IL2026:RequiresUnreferencedCode", |
| | | 137 | | Justification = "Reflection components are only used when source-gen is not available.")] |
| | | 138 | | public static ConfiguredSyringe WithFallbackLogging(this Syringe syringe) |
| | | 139 | | { |
| | 2 | 140 | | ArgumentNullException.ThrowIfNull(syringe); |
| | | 141 | | |
| | 1 | 142 | | return syringe.WithFallbackBehavior(ReflectionFallbackHandlers.LogWarning); |
| | | 143 | | } |
| | | 144 | | } |