Creating Modules

Complete end-to-end guide for creating Intent Architect modules from scratch

Intent Architect modules are packages that contain templates, decorators, factory extensions, and metadata that extend the Software Factory’s code generation capabilities.

Prerequisites

Before creating a module, ensure you have:

• Intent Architect 4.4.0 or later installed
• Visual Studio 2022 or later (for C# modules)
• The Intent.ModuleBuilder module installed in your application
• Basic understanding of C# and code generation concepts

Module Structure Overview

An Intent Architect module consists of:

• Templates: Generate output files from metadata
• Decorators: Modify existing template outputs
• Factory Extensions: Hook into the Software Factory lifecycle
• API Models: Strongly-typed access to designer metadata
• Designer Configuration: Custom designers and visual elements
• .imodspec file: Module specification and manifest

Creating Your First Module

1. Create a new Intent Architect Application
2. Create a new application specifically for module development:
3. # Using Intent CLI
   intent new "MyCompany.MyModule" --template module-builder
   

4. Or through the Intent Architect UI:
6. Install Required Modules
7. Ensure these modules are installed:
9. Create the Module Package
10. In the Module Builder designer:
12. Module naming conventions

    • Use reverse domain notation: CompanyName.ProductName.Feature
    • Be specific: MyCompany.AspNetCore.Controllers not MyCompany.WebApi
    • Avoid generic names that might conflict
    • Use consistent casing (PascalCase recommended)
13. Add Your First Template
14. Create a simple file template:
16. Configure Template Registration
17. Define how your template gets instantiated:
19. Run the Software Factory
20. Generate your module code:
22. Implement Template Logic
23. Edit the generated partial class:
24. using Intent.Engine;
    using Intent.Modules.Common.CSharp.Templates;
    using Intent.Templates;
    
    namespace MyCompany.MyModule.Templates.MyTemplate
    {
        partial class MyTemplateTemplate : CSharpTemplateBase<object>
        {
            public const string TemplateId = "MyCompany.MyModule.MyTemplate";
    
            public MyTemplateTemplate(IOutputTarget outputTarget, object model = null) 
                : base(TemplateId, outputTarget, model)
            {
            }
    
            protected override CSharpFileConfig DefineFileConfig()
            {
                return new CSharpFileConfig(
                    className: "GeneratedClass",
                    @namespace: $"{OutputTarget.GetNamespace()}",
                    relativeLocation: $"{OutputTarget.GetNamespace()}");
            }
    
            public override string TransformText()
            {
                return @$"
    namespace {Namespace}
    {{
        public class {ClassName}
        {{
            public void GeneratedMethod()
            {{
                // Generated code here
            }}
        }}
    }}";
            }
        }
    }
    

25. Build the Module
26. Compile your module:
27. # Build the module project
    dotnet build
    
    # Package the module
    intent package create
    

28. Or use Visual Studio:
30. Test the Module
31. Install and test your module:
33. Publish the Module
34. Share your module:
35. # Publish to local repository
    intent package publish --source ./local-repo
    
    # Publish to company repository
    intent package publish --source https://your-repo.com --api-key YOUR_KEY
    

Module Metadata (.imodspec)

The .imodspec file is the module’s manifest:

Intent.ModuleBuilder.imodspec

<?xml version="1.0" encoding="utf-8"?>
<package>
  <id>MyCompany.MyModule</id>
  <version>1.0.0</version>
  <supportedClientVersions>[4.4.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 or Company</authors>
  <projectUrl>https://docs.yourcompany.com</projectUrl>
  <tags>intent module custom</tags>
  <templates>
    <template id="MyCompany.MyModule.MyTemplate">
      <role>Distribution</role>
      <location>Templates</location>
    </template>
  </templates>
  <dependencies>
    <dependency id="Intent.Common" version="3.7.0" />
    <dependency id="Intent.Common.CSharp" version="3.8.0" />
  </dependencies>
</package>

.imodspec key elements

• id: Unique module identifier
• version: Semantic version (MAJOR.MINOR.PATCH)
• supportedClientVersions: Compatible Intent Architect versions
• templates: All templates provided by the module
• dependencies: Required modules
• factoryExtensions: Lifecycle hooks
• decorators: Template decorators
• designers: Custom designers included

Version ranges

Use semantic versioning ranges:

• [4.4.0-a, 5.0.0-a) - Versions 4.4.0 (inclusive) to 5.0.0 (exclusive)
• [4.5.0-a,) - Version 4.5.0 and later
• Check Intent Architect version: Help > About

Project Structure

A typical module project structure:

MyCompany.MyModule/
├── Api/                          # Metadata API models
│   ├── MyElementModel.cs
│   └── Extensions/
├── Templates/                    # Templates
│   ├── MyTemplate/
│   │   ├── MyTemplateTemplate.cs
│   │   ├── MyTemplateTemplatePartial.cs
│   │   └── MyTemplateTemplateRegistration.cs
│   └── AnotherTemplate/
├── Decorators/                   # Template decorators
│   └── MyDecorator.cs
├── FactoryExtensions/            # Lifecycle extensions
│   └── MyFactoryExtension.cs
├── modelers/                     # Designer configurations
│   └── MyDesigner.designer.config
├── MyCompany.MyModule.csproj    # Project file
└── Intent.ModuleBuilder.imodspec # Module manifest

Template Types

File Per Model

Generates one file for each metadata element. Best for entities, services, controllers.

Single File

Generates one file per output target. Best for startup files, configuration.

Single File List Model

Generates one file processing multiple elements. Best for registrations, indexes.

Custom Registration

Full control over template instantiation. Best for complex scenarios.

Best Practices

Naming Conventions

• Templates: End with Template suffix (e.g., EntityTemplat)
• Decorators: End with Decorator suffix
• API Models: End with Model suffix
• Extensions: End with Extensions suffix

Code Organization

• Keep template logic in partial classes
• Use API models for metadata access
• Separate concerns: generation vs. business logic
• Use helper methods for complex transformations

Testing

• Create test applications for each major feature
• Test with various metadata configurations
• Verify edge cases (empty models, special characters)
• Test upgrade scenarios

Documentation

• Add XML comments to public APIs
• Document template settings and their effects
• Provide usage examples
• Include migration guides for breaking changes

Common Patterns

Accessing Application Settings

public string GetConnectionString()
{
    return ExecutionContext.Settings.GetSetting("ConnectionString", "DefaultValue");
}

Querying Metadata

public IEnumerable<ClassModel> GetEntities()
{
    return ExecutionContext.MetadataManager
        .Domain(ExecutionContext.GetApplicationConfig().Id)
        .GetClassModels()
        .Where(x => x.HasStereotype("Entity"));
}

Cross-Template Dependencies

public string GetRepositoryName(ClassModel entity)
{
    var template = ExecutionContext.FindTemplateInstance<IClassProvider>(
        TemplateDependency.OnModel("Repository.Template", entity));
    return template?.ClassName ?? $"{entity.Name}Repository";
}

Troubleshooting

Module not appearing in repository

• Verify .imodspec version is incremented
• Check supportedClientVersions includes your Intent version
• Rebuild and repackage the module
• Clear module cache: intent cache clear

Template not generating output

• Check template registration GetModels() returns elements
• Verify template ID matches between template and registration
• Ensure output target is configured correctly
• Check for exceptions in Software Factory output

Build errors in generated code

• Verify all dependencies are installed
• Check NuGet package references in .csproj
• Ensure using statements are correct
• Review template output in Software Factory logs

Next Steps

Module Builder Details

Learn about the Module Builder module and its features

Creating Templates

Deep dive into template development

Creating Decorators

Learn how to modify existing template outputs

Factory Extensions

Hook into Software Factory lifecycle events