Tical.SDK 0.8.1

Tical.SDK

Build context plugins for Tical — integrations, custom UI and settings sections that plug into the Tical time tracker.

A context is a switchable mode shown at the top of the main window ("Personal", "Jira", …). It decides which time entries are visible, what new entries get stamped with, and — optionally — contributes its own views, entry editor, settings section and lifecycle hooks.

This package layers the Avalonia-based plugin API on top of Tical.SDK.Core. If you are writing a UI-free exporter rather than a context, you only need Tical.SDK.Core.

Installing

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFramework>net10.0</TargetFramework>
        <Nullable>enable</Nullable>
    </PropertyGroup>
    <ItemGroup>
        <PackageReference Include="Tical.SDK" Version="0.8.1" ExcludeAssets="runtime" />
        <PackageReference Include="Tical.SDK.Core" Version="0.8.1" ExcludeAssets="runtime" />
        <PackageReference Include="Avalonia" Version="12.0.2" ExcludeAssets="runtime" />
        <PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.1" ExcludeAssets="runtime" />
    </ItemGroup>
</Project>

ExcludeAssets="runtime" is not optional, on every one of those four lines. Tical loads Tical.SDK.dll, Tical.SDK.Core.dll and Avalonia from the host application. If your plugin folder ships its own copies, the CLR loads a second set of the same types and every cast across the plugin boundary fails at runtime — your context simply will not appear.

ExcludeAssets="runtime" is the setting that keeps an assembly out of your build output while still compiling against it. PrivateAssets="all" is a different knob and will not do this — it governs what flows on to consumers of your package, and leaves the DLL sitting in your plugin folder.

A minimal context

using Tical.Contexts;
using Tical.Plugins;

public sealed class HelloContext : AppContextBase
{
    public override string Id => "hello";
    public override string Name => "Hello";
}

public sealed class HelloPlugin : ITicalPlugin
{
    public string Name => "Hello";

    public IEnumerable<IAppContext> CreateContexts(IContextHost host) => [new HelloContext()];
}

Build, then drop the resulting DLL into Plugins\Hello\ next to your Tical installation.

A context can also propose a global hotkey that switches to it, though none of the bundled ones does — DefaultShortcut returns null by default, so every context ships unbound and the user assigns shortcuts themselves in Tical's settings:

public override ContextShortcut? DefaultShortcut => new(Modifiers: 3, Key: 0x4A); // Ctrl+Alt+J

It is only a suggestion. The host seeds the user's setting from it the first time it sees the context, and after that whatever the user configured wins — including clearing it.

Version compatibility

The SDK version you compile against must be less than or equal to the version bundled with the Tical host your users run. The host supplies the assembly at load time, so compiling against a newer SDK than the host ships means binding against members that are not there.

The SDK versions independently of the app, and follows Semantic Versioning against the plugin ABI: a major bump means plugins built against the previous major stop loading.

Documentation

Full plugin guide, capability interfaces and worked examples: see docs/PLUGINS.md in the Tical repository.

Licence

Proprietary — see LICENSE-SDK.md in this package. Free to use for building and distributing Tical plugins, including commercially; redistributing the SDK assemblies themselves is not permitted.