Extension development
An extension is a package that adds endpoints, data, hooks and pages to a Solo instance. It does this without a change to Solo itself.
What an extension can add
An extension can combine these parts.
| Capability | What you write | Page |
|---|---|---|
| API endpoints | MVC controllers. Solo serves them below /api/ext/<id>/. |
Server half |
| Data | Your own DbContext, in your own PostgreSQL schema. |
Server half |
| Fields on core records | Values in a JSON field of a task, an epic or a board. | Server half |
| Hooks | Code that runs before a core write and can refuse or change it. | Hooks and events |
| Events | Code that runs after a core change. | Hooks and events |
| Live updates | Messages from your server code to your pages. | Hooks and events |
| Background work | Scheduled work that acts as a user who permitted it. | Hooks and events |
| Pages | Razor components with @page routes, and entries in the sidebar. |
Client half |
| Parts of core pages | Components that Solo draws in the sidebar, on cards, in the task drawer and in other places. | Client half |
The two halves
An extension has a server half, a client half, or the two.
| Half | Project type | Contract package | Runs in |
|---|---|---|---|
| Server | Class library (Microsoft.NET.Sdk) |
HunterAhlquist.Solo.Extensibility |
The Solo process |
| Client | Razor class library (Microsoft.NET.Sdk.Razor) |
HunterAhlquist.Solo.Shared |
The browser of each person |
The client half also references Microsoft.AspNetCore.Components.Web and MudBlazor, at the versions that the instance runs.
The client half cannot reference HunterAhlquist.Solo.Extensibility. That package depends on ASP.NET Core and EF Core, and they do not build for the browser.
The rule: change no core project
An extension is its own project. It references the contract packages and no other part of Solo.
If you edit Solo.Api, Solo.Data, Solo.Client, Solo.Shared or Solo.Extensions, you are changing Solo. You are not writing an extension.
The test is removal. When an administrator removes the package, the instance loses the feature of the extension and no other feature.
If the contract does not let you do what you need, the contract has a gap. Do not use the database or the core assemblies directly to get past it.
Trust
An extension is code that an administrator deploys. The server half runs in the Solo process and gets the database connection string. The client half runs in the same browser context as the session token. Solo has no sandbox. The manifest is a description, not a security boundary.
Write an extension with this in mind:
- Use
ISoloQueryto read core data. It applies the project access of the caller. - Write core data through the Solo API, not through the database. The API applies authorization, hooks, the audit log and live updates.
- Put no secret in the
content/folder. Solo serves that folder without sign-in.
The contract and its version
The two contract packages have one version: the contract version. This documentation describes contract 1.10.
- Compile against the newest package.
- In the manifest, declare the lowest contract version that your code needs. See Version ranges.
An instance refuses a package that needs a newer contract than it has, and gives the reason. Reference lists what each version added.
Get the contract packages
The packages are HunterAhlquist.Solo.Extensibility and HunterAhlquist.Solo.Shared.
nuget.org has them, so a PackageReference restores them with no other package source.
To compile against a contract version that nuget.org does not have yet, build the packages from the Solo repository:
git clone https://github.com/HunterAhlquist/Solo.git
cd Solo
build/pack-contract.sh
The script writes the packages to artifacts/nuget. Add that folder as a package source:
dotnet nuget add source "$PWD/artifacts/nuget" --name solo-contract
Examples to read
| Example | What it shows |
|---|---|
samples/HelloExtension |
The smallest extension with the two halves. Your first extension builds it. |
extensions/Mcp |
A full extension: its own schema and migrations, endpoints, an authentication scheme, a page, static content and an audit contributor. |
extensions/Roadmap |
An extension that uses most client contributions: sidebar sections, the task drawer, the task picker, menus, live updates and a settings panel. |
In this section
- Your first extension: build, package and install a small extension.
- Project template: create the projects from Visual Studio, Rider or
dotnet new. - Manifest: each field of
extension.json. - Server half: endpoints, access to core data, and your own data.
- Hooks and events: hooks, events, live updates and background work.
- Client half: pages, the API client, and contributions to core pages.
- Package and install: the package layout and the development loop.
- Reference: contract versions, operations, policies and limits.
- Troubleshooting: symptoms and their causes.