Ways to Register a Module

• Jun 01, 2022
• 4 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 the ways you can follow to register a module in your applications.

Use the Solution Wizard

You can add modules to your application when you create a new XAF solution using the Solution Wizard. To do this, select modules in the Choose Extra Modules step.

Note

The Solution Wizard allows you to add XAF modules from the predefined list. To add a custom module, use other approaches described in this topic.

Add a Module in Code

This section lists several ways you can follow to add a module in code. Suitable for .NET Framework and .NET 5 projects.

The general requirement is that the code that registers a module must be executed before the XafApplication.Setup method is called. In XAF, adding modules is not supported when the Setup method is already executed.

Register the Additional Module in the Module Project

In an existing module project, you can register an extra module that will be loaded with the current module.

1. Add a reference to the additional module assembly. For the .NET 5 projects, install a NuGet package with the additional module.

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.

   C#

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

   VB.NET

   Public NotInheritable Class MySolutionModule
         Inherits ModuleBase
      '...
      Public Sub New()
         InitializeComponent()
         Me.RequiredModuleTypes.Add(GetType(MyCustomModule.CustomModule))
      End Sub
   End Class
   

Register the Additional Module in the Application Project

In the application project, you can register the additional module as follows.

1. Add a reference to the additional module assembly. For the .NET 5 projects, install a NuGet package with the additional module.

2. Add an instance of the additional module to the XafApplication.Modules list. For example, you can do it in the WinApplication/WebApplication descendant constructor.

   C#

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

   VB.NET

   Public Sub New()
         InitializeComponent()
         Me.Modules.Add(New MyCustomModule.CustomModule())
   End Sub
   

Register a Dynamically Loaded Module

You can register additional modules that will be loaded dynamically by their names when required.

To register a dynamically loaded module, pass the additional 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. Refer to the Add a Module to the Application Configuration File section to see the example.

Add a Module to the Application Configuration File

This approach allows third-parties to plug-in their own modules without recompiling your application. Please note that third-party modules may contain insecure code that overrides security restrictions, modifies your business logic, etc. That is why adding modules from the configuration file is disabled by default. Enable it in the trusted environment only.

In a WinForms application, edit the Program.cs (Program.vb) file.

C#

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

VB.NET

Friend Class Program
   Private Sub New()
   End Sub
   Shared Sub Main()
      '...
      Dim winApplication As MySolutionWindowsFormsApplication = _
      New MySolutionWindowsFormsApplication()
      '...
      winApplication.Setup("MySolution", winApplication.ConnectionString, _
      ConfigurationManager.AppSettings("Modules").Split(";"c))
      winApplication.Start()
      '...
   End Sub
   '...
End Class

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

C#

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();
   }
   //...
}

VB.NET

Public Class [Global]
      Inherits System.Web.HttpApplication
   Protected Sub Session_Start(ByVal sender As Object, ByVal e As EventArgs)
      WebApplication.SetInstance(Session, New MySolutionWebApplication())
      '...
      WebApplication.Instance.Setup("MySolution", WebApplication.Instance.ConnectionString, _
      ConfigurationManager.AppSettings("Modules").Split(";"c))
      WebApplication.Instance.Start()
   End Sub
   '...
End Class

You can now add a module assembly name to the modules list in the application configuration file (App.config and/or Web.config).

XML

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

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

Note

If the module to be added includes the Entity Framework DbContext, register the EFObjectSpace provider for it at the module level. Then, override the ModuleBase.Setup method and handle the XafApplication.CreateCustomObjectSpaceProvider event.

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

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

Modules Shipped With XAF are available in the DX.21.2: XAF Modules tab of the Toolbox.

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