Installation & Setup

Set up your development environment for Intent Architect module development

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 later

Download from intentarchitect.com

.NET SDK

Version 8.0 or later

Download from dotnet.microsoft.com

IDE

Visual Studio 2022, VS Code, or Rider

Any C# IDE with .NET 8 support

Git

Latest stable version

For 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

1. Clone the Intent.Modules repository

   git clone https://github.com/IntentSoftware/Intent.Modules.git
   cd Intent.Modules
   
2. 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
   
3. 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:

1. Open a test application in Intent Architect

   cd Tests/ModuleBuilders
   # Open ModuleBuilders.application.config in Intent Architect
   
2. Install local module builds

   To test your changes:

   1. Build the module you modified
   2. In Intent Architect, right-click Modules
   3. Select Install Module from File
   4. Browse to the built .imodspec file
   5. Click Install
3. Run the Software Factory

   Execute the Software Factory to test your changes:

   1. Click the Software Factory Execution button
   2. Review the generated output
   3. Check for errors in the execution log
4. Verify the output

   Compare the generated files against expected output:

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

Development Workflow

1. 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
   
2. Build the module

   cd Modules/Intent.Modules.Common
   dotnet build
   
3. Test in Intent Architect

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

4. 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:

1. Start Intent Architect
2. In your IDE, attach to the Intent Architect process:
   • Visual Studio: Debug → Attach to Process → IntentArchitect.exe
   • Rider: Run → Attach to Process → IntentArchitect.exe
3. Set breakpoints in your module code
4. Run the Software Factory in Intent Architect
5. 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:

1. Update module version

   Follow Semantic Versioning in both:

   • .csproj file
   • .imodspec file

   <Version>3.10.1</Version>
   
2. Ensure module compiles

   dotnet build
   
3. Add test cases

   Add tests to the Tests/ solution if applicable.

4. Run validation checks

   .\run-pre-commit-checks.ps1
   
5. 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:

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

Changes not reflected after rebuild

1. Uninstall the old module version from Intent Architect
2. Rebuild the module
3. Reinstall the new .imodspec file
4. 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