Ways to Register a Module

• Dec 22, 2023
• 5 minutes to read

In an XAF application, you can use modules declared in the current solution and modules provided by external assemblies. This topic lists all available techniques to register a module in your applications.

Use the Solution Wizard

You can add modules to your application when you use the Solution Wizard to create a new XAF solution. Select modules in the Choose Additional Modules step.

Note

In the Solution Wizard, you can only add XAF modules from the predefined list. To add a custom module, use other techniques described in this topic.

Add a Module in Code

This section lists several techniques you can use to add a module to your .NET 6+ and .NET Framework projects in code.

Your application must execute the code that registers a module before it calls the XafApplication.Setup method. In XAF, you cannot add a module after the Setup method call.

Register a Module in the Application Project

In the application project, you can use the application builder to register an additional module:

1. In a .NET 6+ project, install the NuGet package with the additional module. In a .NET Framework project, add the reference to the additional module assembly instead.

2. Navigate to the MyApplication.Blazor.Server\Startup.cs file (ASP.NET Core Blazor) or the MyApplication.Win\Startup.cs file (Windows Forms) and add the module to your application with the help of the application builder.

   ASP.NET Core Blazor

   public class Startup {
      // ...
      public void ConfigureServices(IServiceCollection services) {
            // ...
            services.AddXaf(Configuration, builder => {
               // ...
               builder.Modules
                  .AddReports(/*...*/)
                  .AddDashboards(/*...*/)
                  .Add<MyCustomModule>();
               // ...
            });
            // ...
      }
      // ...
   }
   

   Windows Forms

   //...
   public class ApplicationBuilder : IDesignTimeApplicationFactory {
      public static WinApplication BuildApplication(string connectionString) {
            // ...
            builder.Modules
               .AddReports(/*...*/)
               .AddDashboards(/*...*/)
               .Add<MyCustomModule>();
            // ...
      }
      // ...
   }
   

   If your application does not have an application builder, add an instance of the module to the XafApplication.Modules list in the WinApplication/WebApplication descendant’s constructor:

   public MySolutionWinApplication() {
         InitializeComponent();
         this.Modules.Add(new MyCustomModule.CustomModule());
   }
   

This technique may require additional setup for certain modules. You can find relevant information in module-specific help topics.

Register a Module in the Module Project

In an existing module project, you can register an additional module to be loaded with the current module.

1. In a .NET 6+ project, install the NuGet package with the additional module. In a .NET Framework project, add the reference to the additional module assembly instead.

2. In the module project’s constructor declared in the Module.cs (Module.vb) file by default, add the additional module to the ModuleBase.RequiredModuleTypes list.

   public sealed class MySolutionModule : ModuleBase {
      //...
      public MySolutionModule() {
         InitializeComponent();
         this.RequiredModuleTypes.Add(typeof(MyCustomModule.CustomModule));
      }
   }
   

With this technique, some modules may require additional setup. You can find the relevant information in module-specific help topics.

Register a Dynamically Loaded Module

You can register additional modules that XAF loads dynamically by their names when required.

To register a dynamically loaded module, pass the module’s name to the XafApplication.Setup method. The Setup method has overloads that take the moduleAssemblies parameter - a string array that specifies module assembly names to be loaded.

For instance, you can use this method to load modules listed in the application configuration file. For an example, refer to the Add a Module to the Application Configuration File section of this topic.

This technique is not suitable for .NET 6+ XAF applications. To add a module to a .NET 6+ XAF application dynamically, navigate to the MyApplication.Blazor.Server\Startup.cs file (ASP.NET Core Blazor) or the MyApplication.Win\Startup.cs file (Windows Forms) and use the Add<TModule>(Func<TModule>) method:

IEnumerable<Type> modulesTypesToAdd = /* ... */
foreach (Type moduleType in moduleTypesToAdd) {
   builder.Modules.Add(() => (DevExpress.ExpressApp.ModuleBase)Activator.CreateInstance(moduleType));
}

Add a Module to the Application Configuration File

You can use configuration files in this manner only in .NET Framework applications. In .NET 6+ application, use the Add<TModule>(Func<TModule>) method as described above.

Tip

If you use this technique, third parties may plug in their own modules without recompiling your application.

Third-party modules may contain insecure code that overrides security restrictions or modifies your business logic. For this reason, the functionality that allows you to add modules from the configuration file is disabled by default. Enable it in trusted environments only.

1. In a Windows Forms application, edit the Program.cs (Program.vb) file.

   static class Program {
      static void Main() {
         //...
         MySolutionWindowsFormsApplication winApplication = new MySolutionWindowsFormsApplication();
         //...
         winApplication.Setup("MySolution", winApplication.ConnectionString, 
            ConfigurationManager.AppSettings["Modules"].Split(';'));
         winApplication.Start();
         //...
      }
      //...
   }
   

   In an ASP.NET Web Forms application, edit the Global.asax.cs (Global.asax.vb) file.

   public class Global : System.Web.HttpApplication {
      protected void Session_Start(object sender, EventArgs e) {
         WebApplication.SetInstance(Session, new MySolutionWebApplication());
         //...
         WebApplication.Instance.Setup("MySolution", WebApplication.Instance.ConnectionString, 
            ConfigurationManager.AppSettings["Modules"].Split(';'));
         WebApplication.Instance.Start();
      }
      //...
   }
   

2. Add the module assembly name to the modules list in the application configuration file (App.config for Windows Forms or Web.config for ASP.NET Web Forms).

   <configuration>
      <appSettings>
         <add key="Modules" value="MySolution.MyCustomModule" />
      </appSettings>
   </configuration>
   

Here, MySolution.MyCustomModule is a custom module assembly name.

Note

If the module includes the Entity Framework Core’s DbContext, register its EFCoreObjectSpace provider at the module level. Then, override the ModuleBase.Setup method and handle the XafApplication.CreateCustomObjectSpaceProvider event.

Use the Module Designer or Application Designer (.NET Framework)

In an existing XAF solution, invoke the Application Designer or Module Designer. Drag the module from the Toolbox to the Designer’s Required Modules / Modules section.

The modules shipped with XAF are available in the DX.23.2: XAF Modules tab of the Toolbox.

You can register a custom module declared in an external library in the Toolbox. Drag a registered module to the Application or Module Designer. For details, refer to the following topic: How to: Add Items to the Toolbox.