Development Setup

Set up your development environment for Intent Architect Modules

Prerequisites

Before you begin developing Intent Architect Modules, ensure you have the following tools installed on your development machine.

Required Software

1. Install .NET SDK

   Install the latest versions of .NET SDK. The project currently requires:

   • .NET 8 SDK - Primary development framework
   • .NET 9 SDK - Required for Software Factory CLI
   • .NET 10 SDK - Latest runtime support

   Download from dotnet.microsoft.com

   Verify installation:

   dotnet --list-sdks
   
2. Install Node.js and TypeScript

   TypeScript is required for compiling Designer Macro files.

   1. Install Node.js from nodejs.org
   2. Install TypeScript globally:

   npm install -g typescript
   

   Verify TypeScript installation:

   tsc --version
   
3. Install Git

   Git is required for version control and cloning the repository.

   Configure Git to handle long paths (required for this repository):

   git config --global core.longpaths true
   
4. Install PowerShell (cross-platform)

   PowerShell 7+ is required for running build and validation scripts.

   Download from github.com/PowerShell/PowerShell

Recommended Tools

Visual Studio

Visual Studio 2022 or later with .NET workload installed. Provides excellent C# development experience.

Visual Studio Code

Lightweight alternative with C# and PowerShell extensions for cross-platform development.

JetBrains Rider

Full-featured .NET IDE with excellent refactoring and testing capabilities.

ReSharper

Visual Studio extension for enhanced code quality and productivity.

Repository Setup

1. Clone the repository

   Clone the Intent.Modules repository to your local machine:

   git clone https://github.com/IntentSoftware/Intent.Modules.git
   cd Intent.Modules
   
2. Restore NuGet packages

   Restore all required NuGet packages:

   dotnet restore
   
3. Build the solution

   Build all projects to verify your setup:

   dotnet build
   

   Or use the PowerShell build script:

   ./PipelineScripts/build-all.ps1 -Folder "Modules"
   
4. Run validation checks

   Verify your environment is correctly configured:

   ./PipelineScripts/pre-build-validations.ps1 -ModulesFolder "Modules" -TestsFolder "Tests"
   

Repository Structure

Understanding the repository layout will help you navigate and contribute effectively:

Intent.Modules/
├── Modules/              # All module source code
├── Tests/                # Test projects and Intent Architect test solutions
│   ├── Intent.Modules.Tests.isln
│   ├── Accelerators/     # Sample accelerator projects
│   └── ModuleBuilders/   # Module builder projects
├── DesignerMacros/       # TypeScript-based designer macros
│   └── src/
├── PipelineScripts/      # Build and validation scripts
├── Modules.Archived/     # Deprecated modules
└── azure-pipelines.yml   # CI/CD configuration

Key Directories

• Modules/ - Contains all active module projects. Each module is a separate C# project.
• Tests/ - Contains the Intent Architect test solution (Intent.Modules.Tests.isln) and test projects.
• PipelineScripts/ - PowerShell scripts for building, testing, and validating modules.
• DesignerMacros/ - TypeScript source for designer-level automation and macros.

Installing Intent Architect

To develop and test modules, you’ll need Intent Architect installed:

1. Download Intent Architect

   Download the latest version from intentarchitect.com

2. Install Software Factory CLI

   Install the Intent Software Factory CLI tool:

   dotnet tool install Intent.SoftwareFactory.CLI --global --prerelease
   

   For development/nightly builds:

   dotnet tool install Intent.SoftwareFactory.CLI.nightly --global --prerelease
   
3. Configure credentials

   Set up environment variables for CLI authentication:

   # Set environment variables
   export INTENT_USER="your-username"
   export INTENT_PASS="your-password"
   

   On Windows:

   $Env:INTENT_USER = "your-username"
   $Env:INTENT_PASS = "your-password"
   

Working with the Test Solution

The repository includes an Intent Architect test solution for validating modules:

# Open the test solution in Intent Architect
Tests/Intent.Modules.Tests.isln

This solution allows you to:

• Test module functionality in a real Intent Architect environment
• Validate template outputs
• Ensure modules integrate correctly with other modules

Pre-Commit Validation

Before committing changes, run the pre-commit checks to ensure everything passes:

./run-pre-commit-checks.ps1 -ModulesIsln "Modules/Intent.Modules.isln" -TestsIsln "Tests/Intent.Modules.Tests.isln"

This script performs:

1. Pre-build validations
2. Software Factory change checks
3. Full module build
4. Test solution verification
5. Test project build

The pre-commit script remembers successfully completed phases. Use -Reset to start from the beginning.

Common Issues

Long path errors on Windows

Windows has a 260-character path limit by default. Enable long paths:

git config --global core.longpaths true

Or enable it system-wide in Windows settings (requires admin).

NuGet restore failures

If package restore fails:

1. Clear NuGet caches:

dotnet nuget locals all --clear

2. Restore with force evaluation:

dotnet restore --force-evaluate

TypeScript compilation errors

Ensure TypeScript is installed globally:

npm install -g typescript

Then compile designer macros:

cd DesignerMacros/src
./compile-all.ps1

Build version mismatches

If you encounter version mismatches:

1. Update module versions according to semantic versioning
2. Update modules.config in test projects
3. Run validation script to check for discrepancies

Next Steps

Now that your environment is set up:

1. Review Coding Standards to understand our conventions
2. Learn about Testing to write effective tests
3. Check out the Pull Request Process when you’re ready to contribute

Start by exploring existing modules in the Modules/ directory to understand the codebase structure and patterns.