Skip to content

getting-started.md

Latest commit

 

History

History
286 lines (203 loc) · 8.05 KB

getting-started.md

File metadata and controls

286 lines (203 loc) · 8.05 KB

Getting Started with Modulus

This guide will walk you through setting up your development environment, creating your first module, and running it in the Modulus host.

Prerequisites

  • .NET 10 SDK or later
  • IDE: Visual Studio 2022, JetBrains Rider, or VS Code
  • Git (optional, for cloning the repository)

Installation

Option 1: Install CLI from NuGet (Recommended)

# Install the Modulus CLI globally
dotnet tool install -g Agibuild.Modulus.Cli

# Verify installation
modulus --help

Option 2: Install Project Templates

# Install module project templates
dotnet new install Agibuild.Modulus.Templates

# Verify templates are installed
dotnet new list modulus

You should see:

Template Name                Short Name        Language  Tags
---------------------------  ----------------  --------  --------------------------------
Modulus Module (Avalonia)    modulus-avalonia  [C#]      Modulus/Module/Plugin/Avalonia
Modulus Module (Blazor)      modulus-blazor    [C#]      Modulus/Module/Plugin/Blazor

Option 3: Build from Source

# Clone the repository
git clone https://github.com/AGIBuild/Modulus.git
cd Modulus

# Build the solution
dotnet build

# Run the Avalonia host
dotnet run --project src/Hosts/Modulus.Host.Avalonia

Quick Start: Create Your First Module

Step 1: Create a New Module

Using the CLI:

modulus new -n MyFirstModule
cd MyFirstModule

Or using dotnet new:

dotnet new modulus-avalonia -n MyFirstModule
cd MyFirstModule

This creates a module with the following structure:

MyFirstModule/
├── MyFirstModule.sln              # Solution file
├── .gitignore
├── Directory.Build.props          # Generated to reference Modulus assemblies from the CLI installation
├── extension.vsixmanifest         # Module manifest
├── MyFirstModule.Core/            # Core logic (host-agnostic)
│   ├── MyFirstModule.Core.csproj
│   ├── MyFirstModuleModule.cs     # Module entry point
│   └── ViewModels/
│       └── MainViewModel.cs       # Main ViewModel
└── MyFirstModule.UI.Avalonia/     # Avalonia UI
    ├── MyFirstModule.UI.Avalonia.csproj
    ├── MyFirstModuleAvaloniaModule.cs
    ├── MainView.axaml             # UI definition
    └── MainView.axaml.cs

Step 2: Build the Module

modulus build

Or:

dotnet build

Step 3: Package for Distribution

modulus pack

This creates a .modpkg file in the ./output/ directory.

Step 4: Install the Module

modulus install ./output/MyFirstModule-1.0.0.modpkg

Step 5: Run the Host

# If you have the Modulus host installed
modulus-host

# Or run from the Modulus source
dotnet run --project path/to/Modulus/src/Hosts/Modulus.Host.Avalonia

Your module will appear in the sidebar!

Module Development Workflow

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Create    │────▶│    Build    │────▶│    Pack     │
│ modulus new │     │modulus build│     │ modulus pack│
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    Run      │◀────│   Install   │◀────│   Output    │
│  Host App   │     │modulus inst.│     │  .modpkg    │
└─────────────┘     └─────────────┘     └─────────────┘

Understanding the Module Structure

Core Project (*.Core)

Contains the business logic, ViewModels, and services. This code is host-agnostic and runs on both Avalonia and Blazor hosts.

Key files:

  • *Module.cs: The module entry point, extends ModulusPackage
  • ViewModels/: MVVM ViewModels for your module
  • Services/: Business logic services (you add these)

UI Projects (*.UI.Avalonia / *.UI.Blazor)

Contains the UI implementation for each host platform.

  • Avalonia: Uses .axaml files for XAML-based UI
  • Blazor: Uses .razor files for component-based UI

Module Manifest (extension.vsixmanifest)

The manifest file is automatically generated by the template and contains:

<PackageManifest Version="2.0.0">
  <Metadata>
    <Identity Id="unique-guid" Version="1.0.0" Publisher="YourName" />
    <DisplayName>MyFirstModule</DisplayName>
    <Description>Module description</Description>
  </Metadata>
  <Assets>
    <!-- Module assemblies -->
    <Asset Type="Modulus.Package" Path="MyFirstModule.Core.dll" />

    <!-- Host-specific UI packages -->
    <Asset Type="Modulus.Package" Path="MyFirstModule.UI.Avalonia.dll" TargetHost="Modulus.Host.Avalonia" />
    <Asset Type="Modulus.Package" Path="MyFirstModule.UI.Blazor.dll" TargetHost="Modulus.Host.Blazor" />
    
    <!-- Menu declarations are NOT in the manifest anymore.
         Menus are declared via [AvaloniaMenu]/[BlazorMenu] on the host-specific module entry type
         and projected to the database at install/update time. -->
  </Assets>
</PackageManifest>

CLI Command Reference

Command Description
modulus new Create a new project (module or host app)
modulus build Build the module in current directory
modulus pack Build and package as .modpkg
modulus install <source> Install a module from .modpkg or directory
modulus uninstall <name> Uninstall a module
modulus list List installed modules

Create a Host App (plugin-based application)

# Avalonia desktop host app
modulus new avaloniaapp -n MyApp

# Blazor Hybrid (MAUI) host app
modulus new blazorapp -n MyApp

Notes:

  • blazorapp is a MAUI host template and typically requires Windows to build.

modulus build

modulus build [options]

Options:
  -p, --path <path>               Path to module project
  -c, --configuration <config>    Build configuration (default: Release)
  -v, --verbose                   Show detailed output

modulus pack

modulus pack [options]

Options:
  -p, --path <path>               Path to module project
  -o, --output <path>             Output directory (default: ./output)
  -c, --configuration <config>    Build configuration (default: Release)
  --no-build                      Skip build, use existing output
  -v, --verbose                   Show detailed output

modulus install

modulus install <source> [options]

Arguments:
  <source>    Path to .modpkg file or module directory

Options:
  -f, --force    Overwrite existing installation
  -v, --verbose  Show detailed output

Next Steps

Troubleshooting

"Module not found" after installation

Restart the Modulus host application. Modules are loaded at startup.

Build errors with NuGet packages

Ensure you have the latest Modulus SDK packages:

dotnet restore

Module not appearing in menu

Check that your host-specific module entry type declares a menu attribute:

  • Avalonia: [AvaloniaMenu("key", "Display", typeof(MainViewModel), ...)]
  • Blazor: [BlazorMenu("key", "Display", "/route", ...)]

Menus are read from the database at render time. If you upgraded from an older build, delete the host database file and restart.

Getting Help