Skip to content
Last update: February 28, 2024

Create New Module from Scratch

This guide explores how to create a new module from scratch using Visual Studio, following the example of the Dummy module.

Create Solution and Projects

  1. Create an empty solution named DummyModule using Visual Studio.
  2. Add src and tests Solution Folders using Visual Studio.
    1. In the src folder, add the following projects:
      • DummyModule.Core: Class library (.NET Core).
      • DummyModule.Data: Class library (.NET Core).
      • DummyModule.Web: ASP.NET Core Web Application (Empty template).
    2. Delete the auto-generated Class1.cs from all projects.
    3. In the tests folder, add a project:
      • DummyModule.Tests: xUnit Test Project (.NET Core).
  3. Set Target framework to .NET Core 3.1 for all projects.
  4. Set project references and NuGet package references as outlined in the guide:
    1. References to Projects:
      • DummyModule.Data: Reference DummyModule.Core.
      • DummyModule.Web: References DummyModule.Core and DummyModule.Data.
      • DummyModule.Tests: Reference DummyModule.Core, DummyModule.Data, and DummyModule.Web projects to facilitate comprehensive testing and integration.
    2. References to NuGet Packages:
      • DummyModule.Core: Add a reference to the latest version of the VirtoCommerce.Platform.Core package to leverage core functionalities.
      • DummyModule.Data: Add a reference to the latest version of the VirtoCommerce.Platform.Data package for data management capabilities.
    3. Compile the Solution: Ensure successful build completion without any warnings or errors.

Fill DummyModule.Core Project

To populate the DummyModule.Core project with essential components:

  1. Add ModuleConstants.cs for Module Constants:

  2. Create a class named ModuleConstants.cs to store module constants such as security permissions and settings.

  3. In the ModuleConstants class, define sub-classes for Security and Permissions. These classes contain constants representing various permissions within the module, structured as follows:

    ```csharp
public static class Security
{
    public static class Permissions
    {
        public const string Access = "dummy:access";
        public const string Read =   "dummy:read";
        public const string Create = "dummy:create";
        public const string Update = "dummy:update";
        public const string Delete = "dummy:delete";

        public static string[] AllPermissions = { Access, Read, Create, Update, Delete };
    }
}
```

  4. In the ModuleConstants class, add sub-classes such as Settings and General. These sub-classes contain settings definitions of type SettingDescriptor, facilitating the management of module settings:

    public static SettingDescriptor DummyInteger = new SettingDescriptor
{
    Name = "Dummy.Integer",
    GroupName = "Dummy|General",
    ValueType = SettingValueType.Integer,
    DefaultValue = 50
};

    Note

    Refer to sample ModuleConstants.cs for complete code examples.

  5. Add additional components if necessary:

  6. If your module includes domain models, create a Models folder and define all domain models in it.

  7. For search functionality, include a Search subfolder containing SearchCriteria and SearchResult classes.
  8. Utilize the Services folder to create interfaces for required services, often including CRUD and search operations.
  9. Model-related events can be added to the Events folder, derived from the base GenericChangedEntryEvent class.
  10. Define new types of Notifications in the Notifications folder, each inheriting from EmailNotification/SmsNotification or a custom class based on Notification.

These steps ensure the DummyModule.Core project contains essential components for module functionality and management.

Fill DummyModule.Data Project

To populate the DummyModule.Data project with necessary components:

  1. Add Models Folder for Persisted Data.

  2. If your module involves persisting domain data, create a Models folder.

  3. All models related to persistence should be defined within this folder.
  4. Ensure that each class under this folder corresponds to a class in DummyModule.Core/Models.

  5. These classes should define the database table structure and any restrictions, along with the ability to convert to/from corresponding Core model classes.

  6. Include Repositories folder:

  7. Within DummyModule.Data, add a Repositories folder.

  8. In the Repositories folder:

    1. Add a class named DummyDbContext, deriving from DbContextWithTriggers. Check and copy the contents of the class from a sample DummyDbContext.cs.
    2. Add a class named DesignTimeDbContextFactory. Check and copy the contents of the class from a sample DesignTimeDbContextFactory.cs. Ensure that the connection to your development SQL server is accurate.
    3. Introduce a data repository abstraction (interface) that derives from IRepository for the defined persistence model.
    4. Implement the repository with a class that derives from DbContextRepositoryBase.

  9. Generate code-first migration as follows:

    1. Set the DummyModule.Data project as the startup project in Solution Explorer.
    2. Open the NuGet Package Manager Console.
    3. Set the Default project to src\DummyModule.Data.
    4. Run the command:
    Add-Migration Initial -Verbose

    A new EF migration will be generated, facilitating the extension of an existing module's model.

  10. Include Additional folders if necessary:

  11. Caching folder: If data caching is required, add a folder for cache region classes. Typically, each model should have its own region. Derive the cache region from the generic CancellableCacheRegion class.

  12. Services folder: Implement interfaces defined in the .Core project within this folder.
  13. ExportImport folder: Add a class for data export/import, which should be called from Module.cs and contain the implementation for module data export and import.
  14. Handlers folder: Include handlers for domain events defined under .Core/Events. These handlers facilitate reacting to and managing domain events within the module.

Fill DummyModule.Web Project

  1. Add the required folders and files such as Controllers/Api, Localizations, Scripts, and module.manifest.
  2. Implement the module manifest, controllers for API endpoints, JavaScript files, stylesheets, and localizations.
  3. Configure webpack for JavaScript and stylesheet bundling.
  4. If required, add unit tests and integration tests.

Filling DummyModule.Tests Project

  1. Add unit tests and integration tests as needed.
  2. Ensure integration tests are marked appropriately with the Trait attribute.

Creating Module Package

Create the module package following this article.

By following these steps, you can create a new module in a structured and organized manner, ensuring compatibility with the VirtoCommerce platform.