Class Plugin

Namespace

Extism.Sdk

Assembly

Extism.Sdk.dll

Represents a WASM Extism plugin.

public class Plugin : IDisposable

Inheritance

object

Plugin

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

Plugin(Manifest, HostFunction[], PluginIntializationOptions)

Initialize a plugin from a Manifest.

public Plugin(Manifest manifest, HostFunction[] functions, PluginIntializationOptions options)

Parameters

manifest Manifest

functions HostFunction[]

options PluginIntializationOptions

Plugin(Manifest, HostFunction[], bool)

Create a plugin from a Manifest.

public Plugin(Manifest manifest, HostFunction[] functions, bool withWasi)

Parameters

manifest Manifest

functions HostFunction[]

withWasi bool

Plugin(ReadOnlySpan<byte>, HostFunction[], bool)

Create and load a plugin from a byte array.

public Plugin(ReadOnlySpan<byte> wasm, HostFunction[] functions, bool withWasi)

Parameters

wasm ReadOnlySpan<byte>

A WASM module (wat or wasm) or a JSON encoded manifest.

functions HostFunction[]

List of host functions expected by the plugin.

withWasi bool

Enable/Disable WASI.

Properties

Id

Get the plugin's ID.

public Guid Id { get; }

Property Value

Guid

Methods

AllowHttpResponseHeaders()

Enable HTTP response headers in plugins using extism:host/env::http_request

public void AllowHttpResponseHeaders()

Call(string, ReadOnlySpan<byte>, CancellationToken?)

Calls a function in the current plugin and returns the output as a byte buffer.

public ReadOnlySpan<byte> Call(string functionName, ReadOnlySpan<byte> input, CancellationToken? cancellationToken = null)

Parameters

functionName string

Name of the function in the plugin to invoke.

input ReadOnlySpan<byte>

A buffer to provide as input to the function.

cancellationToken CancellationToken?

CancellationToken used for cancelling the Extism call.

Returns

ReadOnlySpan<byte>

The output of the function call

Exceptions

ExtismException

Call(string, string, CancellationToken?)

Calls a function in the current plugin and returns the output as a UTF8 encoded string.

public string Call(string functionName, string input, CancellationToken? cancellationToken = null)

Parameters

functionName string

Name of the function in the plugin to invoke.

input string

A string that will be UTF8 encoded and passed to the plugin.

cancellationToken CancellationToken?

CancellationToken used for cancelling the Extism call.

Returns

string

The output of the function as a UTF8 encoded string

CallWithHostContext<T>(string, ReadOnlySpan<byte>, T, CancellationToken?)

Calls a function in the current plugin and returns the output as a byte buffer.

public ReadOnlySpan<byte> CallWithHostContext<T>(string functionName, ReadOnlySpan<byte> input, T hostContext, CancellationToken? cancellationToken = null)

Parameters

functionName string

Name of the function in the plugin to invoke.

input ReadOnlySpan<byte>

A buffer to provide as input to the function.

hostContext T

An object that will be passed back to HostFunctions

cancellationToken CancellationToken?

CancellationToken used for cancelling the Extism call.

Returns

ReadOnlySpan<byte>

The output of the function call

Type Parameters

T

Exceptions

ExtismException

Call<TOutput>(string, string, JsonSerializerOptions?, CancellationToken?)

Calls a function on the plugin and deserializes the output as UTF8 encoded JSON.

public TOutput? Call<TOutput>(string functionName, string input, JsonSerializerOptions? serializerOptions = null, CancellationToken? cancellationToken = null)

Parameters

functionName string

Name of the function in the plugin to invoke.

input string

Function input.

serializerOptions JsonSerializerOptions

JSON serialization options used for serialization/derserialization.

cancellationToken CancellationToken?

CancellationToken used for cancelling the Extism call.

Returns

TOutput

Type Parameters

TOutput

Type of the output payload returned by the function.

Call<TOutput>(string, string, JsonTypeInfo<TOutput?>, CancellationToken?)

Calls a function on the plugin with a payload. The payload is serialized into JSON and encoded in UTF8.

public TOutput? Call<TOutput>(string functionName, string input, JsonTypeInfo<TOutput?> outputJsonInfo, CancellationToken? cancellationToken = null)

Parameters

functionName string

Name of the function in the plugin to invoke.

input string

Function input.

outputJsonInfo JsonTypeInfo<TOutput>

Metadata about output type.

cancellationToken CancellationToken?

CancellationToken used for cancelling the Extism call.

Returns

TOutput

Type Parameters

TOutput

Type of the output payload returned by the function.

Call<TInput, TOutput>(string, TInput, JsonSerializerOptions?, CancellationToken?)

Calls a function on the plugin with a payload. The payload is serialized into JSON and encoded in UTF8.

public TOutput? Call<TInput, TOutput>(string functionName, TInput input, JsonSerializerOptions? serializerOptions = null, CancellationToken? cancellationToken = null)

Parameters

functionName string

Name of the function in the plugin to invoke.

input TInput

An object that will be serialized into JSON and passed into the function as a UTF8 encoded string.

serializerOptions JsonSerializerOptions

JSON serialization options used for serialization/derserialization

cancellationToken CancellationToken?

CancellationToken used for cancelling the Extism call.

Returns

TOutput

Type Parameters

TInput

Type of the input payload.

TOutput

Type of the output payload returned by the function.

Call<TInput, TOutput>(string, TInput, JsonTypeInfo<TInput>, JsonTypeInfo<TOutput?>, CancellationToken?)

Calls a function on the plugin with a payload. The payload is serialized into JSON and encoded in UTF8.

public TOutput? Call<TInput, TOutput>(string functionName, TInput input, JsonTypeInfo<TInput> inputJsonInfo, JsonTypeInfo<TOutput?> outputJsonInfo, CancellationToken? cancellationToken = null)

Parameters

functionName string

Name of the function in the plugin to invoke.

input TInput

An object that will be serialized into JSON and passed into the function as a UTF8 encoded string.

inputJsonInfo JsonTypeInfo<TInput>

Metadata about input type.

outputJsonInfo JsonTypeInfo<TOutput>

Metadata about output type.

cancellationToken CancellationToken?

CancellationToken used for cancelling the Extism call.

Returns

TOutput

Type Parameters

TInput

Type of the input payload.

TOutput

Type of the output payload returned by the function.

CheckNotDisposed()

Throw an appropriate exception if the plugin has been disposed.

protected void CheckNotDisposed()

Exceptions

ObjectDisposedException

ConfigureCustomLogging(LogLevel)

Enable a custom log handler, this will buffer logs until DrainCustomLogs(LoggingSink) is called.

public static void ConfigureCustomLogging(LogLevel level)

Parameters

level LogLevel

ConfigureFileLogging(string, LogLevel)

Set log file and level

public static void ConfigureFileLogging(string path, LogLevel level)

Parameters

path string

Log file path

level LogLevel

Minimum log level

Dispose()

Frees all resources held by this Plugin.

public void Dispose()

Dispose(bool)

Frees all resources held by this Plugin.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

DrainCustomLogs(LoggingSink)

Calls the provided callback function for each buffered log line. This only needed when ConfigureCustomLogging(LogLevel) is used.

public static void DrainCustomLogs(LoggingSink callback)

Parameters

callback LoggingSink

ExtismVersion()

Get Extism Runtime version.

public static string ExtismVersion()

Returns

string

~Plugin()

Destructs the current Plugin and frees all resources used by it.

protected ~Plugin()

FunctionExists(string)

Checks if a specific function exists in the current plugin.

public bool FunctionExists(string name)

Parameters

name string

Returns

bool

Reset()

Reset the Extism runtime, this will invalidate all allocated memory

public bool Reset()

Returns

bool

UpdateConfig(Dictionary<string, string>, JsonSerializerOptions)

Update plugin config values, this will merge with the existing values.

public bool UpdateConfig(Dictionary<string, string> value, JsonSerializerOptions serializerOptions)

Parameters

value Dictionary<string, string>

serializerOptions JsonSerializerOptions

Returns

bool

UpdateConfig(ReadOnlySpan<byte>)

Update plugin config values, this will merge with the existing values.

public bool UpdateConfig(ReadOnlySpan<byte> json)

Parameters

json ReadOnlySpan<byte>

The configuration JSON encoded in UTF8.

Returns

bool