Installation & Setup

This guide covers setting up your development environment to build, test, and contribute to Intent Architect modules.

Prerequisites

Before you begin, ensure you have the following installed:

Intent Architect

Version 4.6.0 or laterDownload from intentarchitect.com

.NET SDK

Version 8.0 or laterDownload from dotnet.microsoft.com

IDE

Visual Studio 2022, VS Code, or RiderAny C# IDE with .NET 8 support

Git

Latest stable versionFor cloning the repository

Version Requirements

Intent Architect: 4.6.0-a to 5.0.0-a (as specified in module manifests)
.NET SDK: 8.0 (modules target net8.0)
C# Language Version: 12.0 (with nullable reference types enabled)

Cloning the Repository

Clone the Intent.Modules repository

git clone https://github.com/IntentSoftware/Intent.Modules.git
cd Intent.Modules

Understand the repository structure

The repository is organized as follows:

Intent.Modules/
├── Modules/              # Source code for all modules
│   ├── Intent.Modules.Common/
│   ├── Intent.Modules.ModuleBuilder/
│   ├── Intent.Modules.Common.CSharp/
│   └── ...
├── Modules.Archived/     # Deprecated modules
├── Tests/                # Test applications
│   ├── ModuleBuilders/   # Module builder test apps
│   └── Accelerators/     # Accelerator test apps
├── DesignerMacros/       # Designer macro scripts
├── PipelineScripts/      # Azure DevOps pipeline scripts
├── Directory.Build.props # Shared MSBuild properties
└── README.md

Restore NuGet packages

dotnet restore

This will restore all dependencies for the modules.

Building the Modules

Build All Modules

Build the entire solution:

dotnet build

This builds all modules in the Modules/ directory. Build artifacts are placed in:

Modules/Intent.Modules.*/bin/Debug/net8.0/

Build a Specific Module

Build just one module:

cd Modules/Intent.Modules.Common
dotnet build

The built .imodspec package will be in:

bin/Debug/Intent.Common.imodspec

Build Configuration

All modules share common build properties via Directory.Build.props:

Directory.Build.props

<Project>
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
  </PropertyGroup>
</Project>

Key properties:

GeneratePackageOnBuild: Automatically creates .imodspec on build
CopyLocalLockFileAssemblies: Includes dependencies in the output

Understanding Module Structure

A typical module project has this structure:

Intent.Modules.Common/
├── Intent.Modules.Common.csproj
├── Intent.Common.imodspec          # Module manifest
├── Templates/                       # Template implementations
│   ├── IntentTemplateBase.cs
│   ├── DecoratorBase.cs
│   └── ...
├── Plugins/                         # Factory extensions
│   └── FactoryExtensionBase.cs
├── Registrations/                   # Template registrations
├── Api/                            # Metadata API models
└── Intent.Metadata/                # Designer definitions

Key Files Explained

.csproj File

Standard .NET project file with module metadata:

Intent.Modules.Common.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Version>3.10.0</Version>
    <Description>Base classes and helpers for building modules</Description>
    <GenerateDocumentationFile>True</GenerateDocumentationFile>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Intent.SoftwareFactory.SDK" Version="3.13.0-pre.2" />
  </ItemGroup>
</Project>

.imodspec File

Module manifest defining templates, dependencies, and metadata:

Intent.Common.imodspec

<?xml version="1.0" encoding="utf-8"?>
<package>
  <id>Intent.Common</id>
  <version>3.10.0</version>
  <supportedClientVersions>[4.6.0-a, 5.0.0-a)</supportedClientVersions>
  <summary>Base Implementation and Helper classes for modules.</summary>
  <templates />
  <factoryExtensions>
    <factoryExtension id="Intent.Common.DecoratorExecutionHooks" />
  </factoryExtensions>
  <files>
    <file src="$outDir$/$id$.dll" />
    <file src="$outDir$/$id$.pdb" />
  </files>
</package>

Running Tests

The repository includes test applications in the Tests/ directory:

Open a test application in Intent Architect

cd Tests/ModuleBuilders
# Open ModuleBuilders.application.config in Intent Architect

Install local module builds

To test your changes:

Build the module you modified
In Intent Architect, right-click Modules
Select Install Module from File
Browse to the built .imodspec file
Click Install

Run the Software Factory

Execute the Software Factory to test your changes:

Click the Software Factory Execution button
Review the generated output
Check for errors in the execution log

Verify the output

Compare the generated files against expected output:

# Generated files are in:
Tests/ModuleBuilders/bin/
Tests/ModuleBuilders/obj/

Development Workflow

Make changes to module code

Edit the template, factory extension, or other module components:

# Example: Edit a template
code Modules/Intent.Modules.Common/Templates/IntentTemplateBase.cs

Build the module

cd Modules/Intent.Modules.Common
dotnet build

Test in Intent Architect

Install the built module in a test application and run the Software Factory.

Iterate

Repeat the cycle: edit, build, test until your changes work correctly.

Running Pre-commit Checks

Before committing changes, run validation checks:

.\run-pre-commit-checks.ps1

This script runs:

Code formatting checks
Build validation
Basic smoke tests

Always run pre-commit checks before submitting pull requests. Failing checks will block CI builds.

Debugging Modules

Attach to Intent Architect Process

To debug module code during Software Factory execution:

Start Intent Architect
In your IDE, attach to the Intent Architect process:
- Visual Studio: Debug → Attach to Process → IntentArchitect.exe
- Rider: Run → Attach to Process → IntentArchitect.exe
Set breakpoints in your module code
Run the Software Factory in Intent Architect
Your IDE will hit the breakpoints

Enable Detailed Logging

Add logging to your templates:

public class MyTemplate : CSharpTemplateBase<object>
{
    public MyTemplate(IOutputTarget outputTarget) : base(TemplateId, outputTarget)
    {
        ExecutionContext.EventDispatcher.Publish(new InfoEvent($"MyTemplate created for {outputTarget.Name}"));
    }
}

View logs in Intent Architect:

Software Factory Execution window
Output tab

Inspect Generated Code

Generated code is written to:

<application-folder>/bin/
<application-folder>/obj/

Review these files to verify your template output.

IDE Setup Recommendations

Visual Studio 2022

Recommended extensions:

ReSharper (optional) - Enhanced C# editing
.NET Compiler Platform SDK - For working with Roslyn

Recommended settings:

{
  "editor.formatOnSave": true,
  "omnisharp.enableEditorConfigSupport": true
}

Visual Studio Code

Required extensions:

C# Dev Kit - C# language support
NuGet Package Manager - Manage dependencies

Recommended settings:

{
  "editor.formatOnSave": true,
  "omnisharp.enableEditorConfigSupport": true,
  "files.exclude": {
    "**/bin": true,
    "**/obj": true
  }
}

JetBrains Rider

Rider works out-of-the-box with excellent C# support.Recommended settings:

Enable EditorConfig support
Enable Code Cleanup on Save
Set Solution-wide analysis to On

Contribution Guidelines

When contributing to the repository:

Update module version

Follow Semantic Versioning in both:

.csproj file
.imodspec file

<Version>3.10.1</Version>

Ensure module compiles

dotnet build

Add test cases

Add tests to the Tests/ solution if applicable.

Run validation checks

.\run-pre-commit-checks.ps1

Submit pull request

Create a PR on GitHub with:

Clear description of changes
Reference to any related issues
Confirmation that all checks pass

See the repository README for detailed contribution guidelines.

Troubleshooting

Build fails with 'SDK not found'

Ensure .NET 8.0 SDK is installed:

dotnet --version
# Should output 8.0.x or later

If not installed, download from dotnet.microsoft.com

Module won't load in Intent Architect

Check:

supportedClientVersions in .imodspec matches your Intent Architect version
All required dependencies are included in the module package
No conflicting module IDs with existing modules
Build output contains the .imodspec file

Changes not reflected after rebuild

Uninstall the old module version from Intent Architect
Rebuild the module
Reinstall the new .imodspec file
Restart Intent Architect if issues persist

NuGet package restore fails

Clear NuGet cache and retry:

dotnet nuget locals all --clear
dotnet restore

Next Steps

Quick Start

Build your first module in under 10 minutes

Architecture

Understand the module system architecture

Creating Templates

Learn how to build templates

Support

Get help from the community

Getting Started

Core Concepts

Module Development

Module Categories

Language Support

Visual Modelers

Prerequisites

Intent Architect

.NET SDK

IDE

Git

Version Requirements

Cloning the Repository

Building the Modules

Understanding Module Structure

.csproj File

.imodspec File

Running Tests

Development Workflow

Running Pre-commit Checks

Debugging Modules

IDE Setup Recommendations

Contribution Guidelines

Troubleshooting

Next Steps

Quick Start

Architecture

Creating Templates

Support

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Module Development

Module Categories

Language Support

Visual Modelers

​Prerequisites

Intent Architect

.NET SDK

IDE

Git

​Version Requirements

​Cloning the Repository

​Building the Modules

​Understanding Module Structure

.csproj File

.imodspec File

​Running Tests

​Development Workflow

​Running Pre-commit Checks

​Debugging Modules

​IDE Setup Recommendations

​Contribution Guidelines

​Troubleshooting

​Next Steps

Quick Start

Architecture

Creating Templates

Support

Build docs developers (and LLMs) love

Prerequisites

Version Requirements

Cloning the Repository

Building the Modules

Understanding Module Structure

Running Tests

Development Workflow

Running Pre-commit Checks

Debugging Modules

IDE Setup Recommendations

Contribution Guidelines

Troubleshooting

Next Steps