Skip to main content

C# SDK

Glixo.ExtensionSdk is a guest library for .NET code compiled into a WebAssembly component. It supplies typed HTTP requests, a disposable NDJSON reader and state, workspace, logging and provider-event contracts. The CLI includes its source in your project; there is no public NuGet SDK package to install yet.

Create and build a component

glxdev new --kind reference --reference workflow-text-stats --language csharp --package-id org.example.text-stats --name "Text statistics" --publisher org.example --output ./text-stats-csharp
cd text-stats-csharp
glxdev doctor
glxdev check
dotnet restore Glixo.Contribution.csproj --runtime wasi-wasm --locked-mode
dotnet build Glixo.Contribution.csproj --configuration Release --runtime wasi-wasm --no-restore
node scripts/copy-artifact.mjs bin/Release/net10.0/wasi-wasm/native/Glixo.Contribution.wasm dist/glixo-extension.component.wasm

The recipe pins .NET SDK 10.0.301, Componentize .NET 0.8.0-preview00011 and wit-bindgen-csharp 0.58.0. Keep the generated global.json, NuGet.Config, lockfile and project settings. Componentize .NET generates the bindings from the project's Wit item. Read the complete project file and build matrix.

The scaffold rewrites the SDK project reference to vendor/glixo-extension-sdk/Glixo.ExtensionSdk/Glixo.ExtensionSdk.csproj. You can also obtain that library from the SDK source download. Use ProjectReference to its extracted .csproj; keep it alongside your extension source. The public example's repository-relative project reference shows its source layout, while the CLI makes the project standalone.

Namespaces and APIs

Namespace Public contracts
Glixo.ExtensionSdk GuestEnvelope<TConfiguration>, GuestContext, EndpointGrant, GuestReply<TResponse>
.Http Header, BrokerRequest, IBroker, NdjsonStream
.State IScopedState.Get/Set/List/Delete
.Workspace IWorkspaceReader.Search/Read
.Logging IExtensionLogger.Log(level,message)
.Llm ToolCallDetails, Usage, ProviderEvent

See the guest types, HTTP implementation, state, workspace, logging and LLM records.

Implement these interfaces using generated WIT imports. For example, IScopedState.Get(string) returns a nullable string for a missing key; Set returns void; List returns IReadOnlyList<string>; Delete returns whether a key existed. Let host errors reach the entry-point result wrapper. The C# storage adapter demonstrates mapping imports without a native storage implementation.

Export and return errors

The contribution world generates a namespace for guest.invoke. Keep the generated namespace and implementation class expected by Componentize .NET. The Text Stats entry point uses:

namespace ContributionWorld.wit.Exports.glixo.contribution.v1_0_0;

public static class GuestExportsImpl
{
    public static string Invoke(string requestJson)
    {
        try { return Glixo.Reference.WorkflowTextStats.Handler.Invoke(requestJson); }
        catch (Exception error)
        {
            var code = error is InvalidOperationException
                && error.Message.Length is > 0 and <= 96
                && error.Message.All(c => char.IsAsciiLetterOrDigit(c) || c == '_')
                ? error.Message : "guest_request_invalid";
            throw new ContributionWorld.WitException<string>(code, 0);
        }
    }
}

This calls the scaffold's handler and converts a bounded error code into the WIT error arm. Read the export source and handler. An ordinary unhandled exception can trap the component. Keep errors free of credentials, filesystem details and full upstream bodies.

Use JsonDocument/JsonElement for dynamic request fields, validate kinds and ranges before reading, and dispose documents. Native AOT builds need serialization metadata for typed serialization; the sample uses explicit parsing and writing so it does not depend on reflection. The generic envelope record is a shape, not runtime validation.

HTTP lifetime and tests

IBroker exposes Start, Status, ResponseHeaders, Read, Cancel and Drop. Read returns null at EOF. Construct NdjsonStream with an imported broker and request; use using so its Dispose() drops the response. ReadLine() returns bytes or null at EOF. Cancel() cancels and disposes once. Defaults are 16 KiB per read and 1 MiB per line. See the HTTP guide.

For Text Stats, the scaffold includes a native test project under tests/. Run dotnet run --project tests/WorkflowTextStats.Tests.csproj from the project directory. Check the generated project's paths if you selected a different reference. Native tests validate your handler; they do not prove WebAssembly permissions or installed-app behavior. Finish with packaging and installation.