Assembly scanning

Component: NServiceBus
Standard support for version 5.x of NServiceBus has expired. For more information see our Support Policy.

NServiceBus scans assemblies at endpoint startup to automatically detect and load message types, message handlers, features, and installers.

There are some cases where finer control over which assemblies are loaded is required:

  • To limit the number of assemblies being scanned and hence provide improvements to startup time.
  • If hosting multiple endpoints out of the same directory each endpoint may require a subset of assemblies to be loaded.
NServiceBus extensions such as NServiceBus.RavenDB.dll are not considered a core assembly but still must be included when customizing the assembly scanning.

Assembly files

By default all assemblies in the endpoint's bin directory are scanned in search of related interfaces so that the endpoint can configure them automatically.

Nested directories

Assemblies in nested directories are scanned.

Assemblies to scan

Further control of scanned assemblies can be configured using an "include list" approach.

Since many extensions such as transports and persisters in external NuGet packages rely on assembly scanning, accidental exclusion of these assemblies can lead to runtime errors and hard-to-diagnose behaviors.

Including assemblies

busConfiguration.AssembliesToScan(myListOfAssemblies);
// or
busConfiguration.AssembliesToScan(assembly1, assembly2);

Controlling the exact types that NServiceBus uses

busConfiguration.TypesToScan(myTypes);

Specifying the directory to scan

busConfiguration.ScanAssembliesInDirectory(@"c:\my-custom-dir");

Including assemblies using pattern matching

var includesBuilder = AllAssemblies
    .Matching("NServiceBus")
    .And("MyCompany.")
    .And("SomethingElse");
busConfiguration.AssembliesToScan(includesBuilder);

The AllAssemblies helper class can be used to create a list of assemblies by creating: a) a deny list using the method Except, b) an allow list by using Matching, or c) a combination of both.

The Except, Matching and And methods behave like string.StartsWith(string).

Mixing includes and excludes

var excludesBuilder = AllAssemblies
    .Matching("NServiceBus")
    .And("MyCompany.")
    .Except("BadAssembly.dll");
busConfiguration.AssembliesToScan(excludesBuilder);

Exclude specific assemblies by name

var excludesBuilder = AllAssemblies
    .Except("MyAssembly1.dll")
    .And("MyAssembly2.dll");
busConfiguration.AssembliesToScan(excludesBuilder);

Exclude specific types

var allTypes = from a in AllAssemblies.Except("Dummy")
               from t in a.GetTypes()
               select t;

var allowedTypesToScan = allTypes
    .Where(t => t != badType)
    .ToList();

busConfiguration.TypesToScan(allowedTypesToScan);

Last modified