Assembly scanning

Component: NServiceBus
NuGet Package NServiceBus (5.x)

By default all assemblies in the endpoint bin directory are scanned to find types implementing its interfaces so that it 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.
Extensions (for example NServiceBus.RavenDB.dll) are not considered a core assembly and will need to be included when customizing assembly scanning.

Nested Directories

Assemblies in nested directories are scanned.

Assemblies to scan

An "Include a list" approach is used. This proved to be problematic. Many extensions rely on assembly scanning, for example transports and persistences in external NuGet packages. If, at endpoint configuration time, a list of assemblies was generated, and that list did not include extension assemblies, the endpoint would fail at runtime with some unexpected and 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