Assembly scanning

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

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.

During the scanning process, the core assembly for NServiceBus (NServiceBus.Core.dll) is automatically included since it is required for endpoints to properly function.

Controlling the assemblies to scan

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 will still need to be included when customizing the assembly scanning.

Nested Directories

Assemblies in nested directories are scanned.

Assemblies to scan

An "Include a list" approach is used. Since many extensions such as transports and persisters in external NuGet packages relied on assembly scanning, this proved to be problematic. If the list of generated assemblies does include extension assemblies, the endpoint would fail at runtime with some unexpected, hard to diagnose behaviors.

Exclude a list approach

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 != typeof(GenericHandler))
    .ToList();

busConfiguration.TypesToScan(allowedTypesToScan);

Include a list approach

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);

AllAssemblies helper class can be used to create a list of assemblies either by creating a blacklist using the method Except or a whitelist by using Matching or 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);

Last modified