Skip to main content

Factory and packaging

XyzProviderFactory.cs is the smallest file in a provider project — but it's the one discovery actually looks for. It, plus the assembly metadata described here, is what turns a class library into a loadable SmartHopper provider.

The factory​

ProviderManager reflects over each SmartHopper.Providers.*.dll for a public IAIProviderFactory implementation. It has exactly two methods:

public class XyzProviderFactory : IAIProviderFactory
{
// Providers are singletons — return the shared instance.
public IAIProvider CreateProvider() => XyzProvider.Instance;

// Settings are per-instantiation (the dialog binds to one).
public IAIProviderSettings CreateProviderSettings() => new XyzProviderSettings(XyzProvider.Instance);
}

That's it. No registration call, no manifest — the assembly name pattern and the factory type are the whole contract.

Assembly metadata​

Community providers declare compatibility via attributes in SmartHopper.ProviderSdk.Metadata:

using SmartHopper.ProviderSdk.Metadata;

[assembly: SmartHopperProviderId("xyz")] // optional stable id (e.g. "openai")
[assembly: BuiltAgainstSdk("1.0.0")] // SDK version you compiled against — REQUIRED
[assembly: MinHostSdk("1.0.0")] // optional minimum host SDK
AttributeRequired?Checked
BuiltAgainstSdkYes (for the compat model)Its major version must equal the host SDK major — otherwise SdkCompatibility.Check rejects the assembly before any of its code runs. Omit it and the check reports MissingMetadata.
MinHostSdkNoIf present, host SDK must be ≥ this version (HostTooOld otherwise).
SmartHopperProviderIdNoA stable provider id independent of assembly name, used for conflict resolution and classification. Not a security boundary — trust still comes from signature/hash checks.

The version check is BuiltAgainstSdk.MAJOR == HostSdk.MAJOR && HostSdk >= MinHostSdk. Official in-repo providers get these attributes injected by build tooling; community providers declare them explicitly.

Declare them anyway

SdkCompatibility.Check currently exists but is not called by the load path — the attributes are unenforced today. Declare them regardless: the check is the intended gate, and declaring costs nothing while making the provider forward-compatible.

Project file​

A provider project is a minimal class library targeting both frameworks, referencing only the SDK:

<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<!-- Output must be named SmartHopper.Providers.<Name>.dll -->
<TargetFrameworks>net7.0-windows;net7.0</TargetFrameworks>
<EnableDynamicLoading>true</EnableDynamicLoading>
<EnableWindowsTargeting>true</EnableWindowsTargeting>
<UseWindowsForms Condition="$(TargetFramework.Contains('-windows'))">true</UseWindowsForms>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\SmartHopper.ProviderSdk\SmartHopper.ProviderSdk.csproj" />
<!-- or the SmartHopper.ProviderSdk NuGet package for out-of-repo providers -->
</ItemGroup>
</Project>

Critical details:

  • Assembly name is the contract. Output must be SmartHopper.Providers.<Name>.dll — ProviderManager discovers by that glob, so name your project SmartHopper.Providers.<Name>.
  • EnableDynamicLoading — required so the assembly resolves its dependencies inside its isolated AssemblyLoadContext.
  • Reference only SmartHopper.ProviderSdk (project reference in-repo, NuGet package out-of-repo). Referencing SmartHopper.Infrastructure/other host assemblies both bloats the plugin and breaks the SDK boundary.

Deploying​

Drop the built SmartHopper.Providers.<Name>.dll into the app-local folder — the directory containing SmartHopper.Infrastructure.dll. That is the only location ProviderManager.DiscoverProvidersAsync scans today (glob SmartHopper.Providers.*.dll).

The ProviderSdk README also describes a user-local dir

SmartHopper.ProviderSdk/README.md mentions %AppData%\SmartHopper\Providers\ / ~/.config/SmartHopper/Providers\ as a drop-in location — that path is not implemented in the current loader. Only the app-local folder is discovered.

On next load the pipeline is:

  1. Authenticode + strong-name check (Windows only; skipped on macOS) — the provider must be signed with the same certificate and strong-name key as the host, or it is rejected outright. This means unsigned/self-built community providers cannot load on Windows today; the community path effectively only works on macOS and DEBUG builds.
  2. SHA-256 hash verification against the official hash repository → Match / Mismatch / Unavailable / NotFound, gated by ProviderIntegrityCheckMode (Strict/Hard block; Soft warns and allows; DEBUG forces Soft).
  3. Trust prompt — unknown assemblies ask "A new AI provider was detected — enable it?" and the answer is stored in TrustedProviders.
  4. Instantiate — Assembly.LoadFrom, reflect for IAIProviderFactory, call CreateProvider()/CreateProviderSettings(), RegisterProvider.

Note that the isolated AssemblyLoadContext (ProviderLoadContext), the SdkCompatibility check on BuiltAgainstSdk/MinHostSdk, and the four-way ProviderClassifier (Official/OfficialTampered/Community/Invalid) all exist as code but are not wired into the load path — they're groundwork for the stricter model, not current behavior.

Community providers run with full privileges

There is no provider sandbox — a loaded provider executes arbitrary .NET in the SmartHopper process (in the default load context today). Write providers assuming they share the process; deploy them assuming users will (rightly) be cautious.

Full-project checklist​

  • XyzProviderFactory : IAIProviderFactory — public, parameterless-constructible.
  • [assembly: BuiltAgainstSdk("…")] matches the SDK major you build against.
  • Output name SmartHopper.Providers.<Name>.dll, <EnableDynamicLoading>.
  • Only SmartHopper.ProviderSdk referenced.
  • XyzProvider sets this.Models = new XyzProviderModels(this) in its constructor.