Creating Modules

This guide walks you through creating a custom Intent Architect module, from initial setup to packaging and distribution.

What is a Module?

A module is a packaged collection of:

Templates - Code generation templates that produce files
Decorators - Components that modify existing templates
Factory Extensions - Extensions that hook into the Software Factory lifecycle
Metadata - Designer configurations and stereotypes
Module Settings - Configurable options for your module

Prerequisites

Before creating a module, ensure you have:

Visual Studio 2022 or later
.NET 8.0 SDK or later
Intent Architect installed
Basic understanding of C# and T4 templates

Module Structure

A typical module project has the following structure:

Intent.Modules.YourModule/
├── FactoryExtensions/           # Factory extension implementations
├── Templates/                   # Template implementations
│   └── YourTemplate/
│       ├── YourTemplatePartial.cs
│       ├── YourTemplateRegistration.cs
│       └── YourTemplateDecorator.cs (optional)
├── Decorators/                  # Decorator implementations (optional)
├── Intent.Metadata/             # Designer metadata and configurations
├── Intent.Modules.YourModule.csproj
└── Intent.Modules.YourModule.imodspec

Step 1: Create the Module Project

Using Intent Architect Module Builder

The recommended approach is to use Intent Architect’s Module Builder:

Create a new Intent Architect application
Install the Module Builder module
Use the Module Builder designer to:
- Define your module metadata
- Create template definitions
- Configure decorators and extensions
Run the Software Factory to generate the module scaffolding

Manual Project Creation

Alternatively, create a .NET Class Library project:

dotnet new classlib -n Intent.Modules.YourModule -f net8.0
cd Intent.Modules.YourModule

Step 2: Create the Module Specification

Create an .imodspec file to define your module’s metadata:

Intent.Modules.YourModule.imodspec

<?xml version="1.0" encoding="utf-8"?>
<package>
  <id>Intent.YourModule</id>
  <version>1.0.0</version>
  <supportedClientVersions>[4.5.0-a, 5.0.0-a)</supportedClientVersions>
  <summary>Brief description of your module</summary>
  <description>Detailed description of what your module does</description>
  <authors>Your Name</authors>
  <tags>csharp dotnet</tags>
  <projectUrl>https://docs.intentarchitect.com/</projectUrl>
  <templates>
    <!-- Template definitions go here -->
  </templates>
  <dependencies>
    <dependency id="Intent.Common" version="3.8.0" />
    <dependency id="Intent.Common.CSharp" version="3.9.4" />
  </dependencies>
  <files>
    <file src="$outDir$/$id$.dll" />
    <file src="$outDir$/$id$.pdb" />
  </files>
</package>

Step 3: Add Templates

Templates are the core of your module. See the Template Development guide for detailed information on creating templates.

Step 4: Register Templates

Create a template registration class:

YourTemplateRegistration.cs

using Intent.Engine;
using Intent.Modules.Common.Registrations;
using Intent.RoslynWeaver.Attributes;
using Intent.Templates;

[assembly: DefaultIntentManaged(Mode.Fully)]

namespace Intent.Modules.YourModule.Templates.YourTemplate
{
    [IntentManaged(Mode.Merge, Body = Mode.Merge, Signature = Mode.Fully)]
    public class YourTemplateRegistration : FilePerModelTemplateRegistration<YourModel>
    {
        private readonly IMetadataManager _metadataManager;

        public YourTemplateRegistration(IMetadataManager metadataManager)
        {
            _metadataManager = metadataManager;
        }

        public override string TemplateId => YourTemplate.TemplateId;

        public override ITemplate CreateTemplateInstance(
            IOutputTarget outputTarget, 
            YourModel model)
        {
            return new YourTemplate(outputTarget, model);
        }

        public override IEnumerable<YourModel> GetModels(IApplication application)
        {
            return _metadataManager.YourDesigner(application).GetYourModels();
        }
    }
}

Step 5: Update the Module Specification

Add your template to the .imodspec file:

<templates>
  <template id="Intent.YourModule.YourTemplate" 
            externalReference="unique-guid-here">
    <config>
      <add key="ClassName" 
           description="Class name formula override" />
      <add key="Namespace" 
           description="Class namespace formula override" />
    </config>
    <role>Application.YourRole</role>
    <location>YourFolder</location>
  </template>
</templates>

Step 6: Build and Package

Build your module project:

dotnet build

This generates an .imod package file in the output directory that can be installed in Intent Architect.

Step 7: Testing Your Module

Create a test application

Create a new Intent Architect application for testing your module.

Install your module

In Intent Architect, go to Module Manager and install your module from the local build output.

Configure the designer

Add the necessary metadata elements in your designer that your templates expect.

Run the Software Factory

Execute the Software Factory and verify the generated code.

Module Versioning

Follow Semantic Versioning:

MAJOR: Incompatible API changes
MINOR: Backwards-compatible functionality additions
PATCH: Backwards-compatible bug fixes

Update the version in both:

.csproj file (<Version> element)
.imodspec file (<version> element)

Module Dependencies

Declare dependencies on other modules in your .imodspec:

<dependencies>
  <dependency id="Intent.Common" version="3.8.0" />
  <dependency id="Intent.Common.CSharp" version="3.9.4" />
  <dependency id="Intent.OutputManager.RoslynWeaver" version="4.9.10" />
</dependencies>

Always specify minimum required versions for dependencies to ensure compatibility.

Module Settings

Add configurable settings to your module:

<moduleSettings>
  <group id="unique-guid" title="Your Settings" externalReference="unique-guid">
    <settings>
      <setting id="unique-guid" 
               title="Enable Feature X" 
               type="switch">
        <hint>Description of what this setting does</hint>
      </setting>
      <setting id="unique-guid" 
               title="Output Format" 
               type="select">
        <hint>Choose the output format</hint>
        <options>
          <option value="json" description="JSON format" />
          <option value="xml" description="XML format" />
        </options>
      </setting>
    </settings>
  </group>
</moduleSettings>

Interoperability

Define module interoperability rules:

<interoperability>
  <detect id="Intent.SomeOtherModule">
    <install>
      <package id="Intent.YourModule.Integration" version="1.0.0" />
    </install>
  </detect>
</interoperability>

This automatically suggests installing integration modules when related modules are detected.

Best Practices

Use RoslynWeaver attributes

Use [IntentManaged] attributes to control code management:

[IntentManaged(Mode.Fully)] // Fully managed by Intent
[IntentManaged(Mode.Merge)] // Merge user changes
[IntentManaged(Mode.Ignore)] // Ignore this code

Follow naming conventions

Module ID: Intent.YourDomain.YourModule
Template ID: Intent.YourDomain.YourModule.YourTemplate
Namespace: Intent.Modules.YourDomain.YourModule

Provide comprehensive documentation

Include:

README.md with usage instructions
release-notes.md for version history
XML doc comments in code
Hints in module settings

Write automated tests

Create test applications in the Tests directory to verify:

Template output correctness
Decorator behavior
Factory extension functionality
Integration with other modules

Distribution

To distribute your module:

Local: Place the .imod file in a shared directory
Private Repository: Set up a private NuGet feed
Public: Submit to the Intent Architect Module Repository

Next Steps

Template Development

Learn how to create powerful code generation templates

Decorators

Extend existing templates with decorators

Factory Extensions

Hook into the Software Factory lifecycle

Testing

Write comprehensive tests for your modules

Example: Complete Module

Here’s a minimal working example from the codebase:

Intent.Modules.Application.MediatR/
├── Templates/
│   ├── CommandHandler/
│   │   ├── CommandHandlerTemplatePartial.cs
│   │   ├── CommandHandlerTemplateRegistration.cs
│   │   └── CommandHandlerDecorator.cs
│   └── QueryHandler/
│       ├── QueryHandlerTemplatePartial.cs
│       └── QueryHandlerTemplateRegistration.cs
├── Intent.Modules.Application.MediatR.csproj
└── Intent.Application.MediatR.imodspec

Review the Intent.Modules.Application.MediatR source code for a complete, real-world example.

Getting Started

Core Concepts

Architecture Patterns

Module Development

Contributing

What is a Module?

Prerequisites

Module Structure

Step 1: Create the Module Project

Using Intent Architect Module Builder

Manual Project Creation

Step 2: Create the Module Specification

Step 3: Add Templates

Step 4: Register Templates

Step 5: Update the Module Specification

Step 6: Build and Package

Step 7: Testing Your Module

Module Versioning

Module Dependencies

Module Settings

Interoperability

Best Practices

Distribution

Next Steps

Template Development

Decorators

Factory Extensions

Testing

Example: Complete Module

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Architecture Patterns

Module Development

Contributing

Documentation Index

​What is a Module?

​Prerequisites

​Module Structure

​Step 1: Create the Module Project

​Using Intent Architect Module Builder

​Manual Project Creation

​Step 2: Create the Module Specification

​Step 3: Add Templates

​Step 4: Register Templates

​Step 5: Update the Module Specification

​Step 6: Build and Package

​Step 7: Testing Your Module

​Module Versioning

​Module Dependencies

​Module Settings

​Interoperability

​Best Practices

​Distribution

​Next Steps

Template Development

Decorators

Factory Extensions

Testing

​Example: Complete Module

Build docs developers (and LLMs) love

What is a Module?

Prerequisites

Module Structure

Step 1: Create the Module Project

Using Intent Architect Module Builder

Manual Project Creation

Step 2: Create the Module Specification

Step 3: Add Templates

Step 4: Register Templates

Step 5: Update the Module Specification

Step 6: Build and Package

Step 7: Testing Your Module

Module Versioning

Module Dependencies

Module Settings

Interoperability

Best Practices

Distribution

Next Steps

Example: Complete Module