Upgrade Guide: Features, Installers, IWant (#7969)

* Features in upgrade guide

* Installers too

* Non-upgrade-guide docs for features and installers

* IWantToRunBeforeConfigurationIsFinalized

* Fix link

* Update nservicebus/upgrades/9to10/index.md

---------

Co-authored-by: Daniel Marbach <daniel.marbach@openplace.net>

Author: DavidBoike

Snippets/Core/Core_10/InstallSomething.cs

@@ -1,13 +1,15 @@
-namespace Core;
+using NServiceBus;
+using NServiceBus.Features;
+
+namespace Core;
 
 using System.Threading;
 using System.Threading.Tasks;
 using NServiceBus.Installation;
 
 #region InstallSomething
 
-public class MyInstaller :
-    INeedToInstallSomething
+public class MyInstaller : INeedToInstallSomething
 {
     public Task Install(string identity, CancellationToken cancellationToken)
     {
@@ -17,4 +19,26 @@ public Task Install(string identity, CancellationToken cancellationToken)
     }
 }
 
+#endregion
+
+class ShowInstallation
+{
+    public void Snippet(EndpointConfiguration endpointConfiguration)
+    {
+#region AddInstallerFromConfig
+        endpointConfiguration.AddInstaller<MyInstaller>();
+#endregion
+    }
+}
+
+#region AddInstallerFromFeature
+
+public class MyFeature : Feature
+{
+    protected override void Setup(FeatureConfigurationContext context)
+    {
+        context.AddInstaller<MyInstaller>();
+    }
+}
+
 #endregion

nservicebus/lifecycle/iwanttorunbeforeconfigurationisfinalized.md

@@ -7,6 +7,9 @@ related:
  - samples/startup-shutdown-sequence
 ---
 
+> [!CAUTION]
+> `IWantToRunBeforeConfigurationIsFinalized` is deprecated starting in NServiceBus version 10. Refer to the [NServiceBus 10 upgrade guide](/nservicebus/upgrades/9to10/#deprecated-iwanttorunbeforeconfigurationisfinalized).
+
 During endpoint creation the configuration object used to construct the endpoint becomes frozen and locked. Classes that implement `IWantToRunBeforeConfigurationIsFinalized` are instantiated and called just before this happens. Use `IWantToRunBeforeConfigurationIsFinalized` for any last minute alterations to the configuration that may rely on other configuration settings.
 
 Instances are:

nservicebus/operations/installers.md

@@ -50,4 +50,6 @@ Implement the `INeedToInstallSomething` interface to create a custom installer:
 
 snippet: InstallSomething
 
-Assemblies in the runtime directory are scanned for installers so no code is needed to register them.
+### Installer registration
+
+partial: registration

nservicebus/operations/installers_registration_core_[,10).partial.md

@@ -0,0 +1,4 @@
+Assemblies in the runtime directory are scanned for installers so no code is needed to register them.
+
+> [!WARNING]
+> In a future version of NServiceBus, [installers will not be scanned and must be registered manually](/nservicebus/upgrades/9to10/#extensibility-installers).

nservicebus/operations/installers_registration_core_[10,).partial.md

@@ -0,0 +1,7 @@
+Installers can be added directly to the `EndpointConfiguration`:
+
+snippet: AddInstallerFromConfig
+
+Or from a `Feature` class that requires them:
+
+snippet: AddInstallerFromFeature

nservicebus/pipeline/features.md

@@ -96,7 +96,7 @@ For a feature to be activated it needs to satisfy the following criteria:
 snippet: FeatureSetup
 
 > [!NOTE]
-> Features are automatically detected and registered by NServiceBus when the assembly is scanned.
+> In NServiceBus version 10 and below, features are automatically detected and registered by NServiceBus when the assembly is scanned. In a future version of NServiceBus [features will not be automatically detected during assembly scanning](/nservicebus/upgrades/9to10/#extensibility-features).
 
 
 ## Feature settings

nservicebus/upgrades/9to10/index.md

@@ -60,6 +60,11 @@ Not having a finder configured for a given message will result in:
 - **When the message is allowed to start the saga** - Compile time analyzer error [NSB0006](/nservicebus/sagas/analyzers.md#message-that-starts-the-saga-does-not-have-a-message-mapping)
 - **When the message is not allowed to start the saga** - `Exception` when processing the message: `Message type CompletePaymentTransaction is handled by saga OrderSaga, but the saga does not contain a property mapping or custom saga finder to map the message to saga data. Consider adding a mapping in the saga's ConfigureHowToFindSaga method`
 
+## Deprecated `IWantToRunBeforeConfigurationIsFinalized`
+
+The extension point [`IWantToRunBeforeConfigurationIsFinalized`](/nservicebus/lifecycle/iwanttorunbeforeconfigurationisfinalized.md) is deprecated with a warning in NServiceBus version 10 and will be removed in NServiceBus version 11.
+
+Final adjustments to settings before configuration is finalized should be applied via an explicit last configuration step on the endpoint configuration, instead of via implementations of this interface discovered by scanning.
 
 ## Extensibility
 
@@ -69,6 +74,55 @@ This section describes changes to advanced extensibility APIs.
 
 As part of adding nullability annotations, the `ContextBag` class no longer allows storing `null` as a value. This also applies to all types derived from `ContextBag`, including all behavior context classes and `TransportTransaction`.
 
+### Features
+
+In a future version of NServiceBus, [`Feature` classes](/nservicebus/pipeline/features.md) will not be automatically discovered by runtime assembly scanning. Instead, each feature should be explicitly enabled for an endpoint.
+
+The preferred method of distributing a feature is to create an extension method on `EndpointConfiguration`, and enable the feature within that extension method:
+
+```csharp
+public static class MyFeatureConfigurationExtensions
+{
+    public static void EnableMyFeature(this EndpointConfiguration config)
+    {
+        config.EnableFeature<MyFeature>();
+    }
+}
+```
+
+The `EnableByDefault()` method is only used to signal that a Feature identified through assembly scanning should turn itself on by default, so this method is deprecated with a warning in NServiceBus version 10 to give advance notice of this change, and will be removed in version 11.
+
+In addition, APIs that work with features using a `Type` have been deprecated, and instead the generic-typed variants should be used. For example:
+
+```csharp
+// Instead of:
+endpointConfiguration.EnableFeature(typeof(MyFeature));
+endpointConfiguration.DisableFeature(typeof(MyFeature));
+// Use instead:
+endpointConfiguration.EnableFeature<MyFeature>();
+endpointConfiguration.DisableFeature<MyFeature>();
+```
+
+Lastly, any `Feature` classes must now have a paramaterless constructor.
+
+### Installers
+
+Like features, [installer classes](/nservicebus/operations/installers.md) which implement `INeedToInstallSomething` will not be automatically discovered by runtime assembly scanning in a future version of NServiceBus.
+
+Instead, installers should be explicitly registered either from an `EndpointConfiguration` or inside a feature's `Setup` method:
+
+```csharp
+endpointConfiguration.AddInstaller<CreateMyInfrastructure>();
+
+public class MyFeature : Feature
+{
+	protected override void Setup(FeatureConfigurationContext context)
+	{
+		context.AddInstaller<CreateMyInfrastructure>();
+	}
+}
+```
+
 ### StartupDiagnosticEntry has required properties
 
 As part of adding nullability annotations, the `Data` and `Name` properties of the `StartupDiagnosticEntry` class have been marked as `required`.
@@ -109,7 +163,7 @@ The `Supports<TStorageType>(…)` no longer accepts an action that gets access t
 public class CustomPersistence : PersistenceDefinition
 {
     internal CustomPersistence()
-    { 
+    {
         Supports<StorageType.Sagas>(s => s.EnableFeatureByDefault<SagaStorage>());
         Supports<StorageType.Subscriptions>(s => s.EnableFeatureByDefault<SubscrptionStorage>());
         Supports<StorageType.Outbox>(s => s.EnableFeatureByDefault<OutboxStorage>());
@@ -123,7 +177,7 @@ must be changed to `Supports<TStorageType, TFeatureType>()` like this:
 public class CustomPersistence : PersistenceDefinition
 {
     internal CustomPersistence()
-    { 
+    {
         Supports<StorageType.Sagas, SagaStorage>();
         Supports<StorageType.Subscriptions, SubscrptionStorage>();
         Supports<StorageType.Outbox, OutboxStorage>();