Ways to Register a Module

• Mar 13, 2021
• 5 minutes to read

In an XAF application, you can use modules declared in the current solution, as well as modules provided by external assemblies. This topic lists the ways you can follow to register a module in your applications.

• Use the Solution Wizard
• Use the Module Designer or Application Designer

• Add a Module in Code

  • Register the Module Type Using the ModuleBase.RequiredModuleTypes Property
  • Add the Module Instance to the XafApplication.Modules List
  • Pass the Module Assembly Name to the XafApplication.Setup Method
• Add a Module to the Application Configuration File

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.

Use the Module Designer or Application Designer

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 that are shipped with XAF (Extra Modules) are available in the DX.19.1: XAF Modules tab of the Toolbox. If the module is custom and is declared in an external assembly, register this module in the Toolbox, so that you can drag it to the Application or Module Designer when required. For details, refer to the How to: Add Items to the Toolbox topic in MSDN.

Add a Module in Code

This section lists several ways you can follow to add a module in code. The general restriction is that the code should be executed before the XafApplication.Setup method is called. In XAF, adding modules is not supported when the Setup method is already executed. You can register modules dynamically depending on a certain condition. For example, you can show a custom form when the application is started and register certain modules depending on a user input.

• Register the Module Type Using the ModuleBase.RequiredModuleTypes Property

  In an existing module project, you can register an extra module that will be loaded with the current module. In the module constructor (which is declared in the Module.cs (Module.vb) file by default), add the required 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
  

• Add the Module Instance to the XafApplication.Modules List

  In the application project, you can instantiate the required module and add the module object to the XafApplication.Modules list. For instance, 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
  

• Pass the Module Assembly Name to the XafApplication.Setup Method

  The advantage of this approach is that you do not have to explicitly reference the required module assembly. The assembly will be loaded dynamically by its name when required. There is an overload of the XafApplication.Setup method taking the moduleAssemblies parameter - a string array specifying module assembly names to be loaded. For instance, you can use this method to load modules listed in the application configuration file. Proceed to the next 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 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.