Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: Update README and API based on review #49

Merged
merged 2 commits into from
Dec 4, 2023
Merged

fix: Update README and API based on review #49

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
efb6a49
fix: Use IDctionary and IList in manifest for F# users
mhmd-azeez Dec 4, 2023
d22f7fa
fix: update README based on review
mhmd-azeez Dec 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 29 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,13 @@ This repo houses the .NET SDK for integrating with the [Extism](https://extism.o
This library depends on the native Extism runtime, we provide [native runtime packages](https://www.nuget.org/packages/Extism.runtime.all) for all supported operating systems. You can install with:
<img src="https://img.shields.io/nuget/vpre/Extism.runtime.all" />
```
dotnet add package Extism.runtime.win-64 --prerelease
dotnet add package Extism.runtime.all --prerelease
```

Then, add the [Extism.Sdk NuGet package](https://www.nuget.org/packages/Extism.Sdk) to your project:
<img src="https://img.shields.io/nuget/vpre/Extism.Sdk" />
```
dotnet add package Extism.Sdk
dotnet add package Extism.Sdk --prerelease
```

## Getting Started
Expand All @@ -29,15 +29,13 @@ C#:
using System;

using Extism.Sdk;
using Extism.Sdk.Native;
```

F#:
```fsharp
open System

open Extism.Sdk
open Extism.Sdk.Native
```

## Creating A Plug-in
Expand All @@ -58,8 +56,7 @@ F#:
let uri = Uri("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm")
let manifest = Manifest(new UrlWasmSource(uri))

use plugin =
Plugin(manifest, Array.Empty<HostFunction>(), withWasi = true)
let plugin = new Plugin(manifest, Array.Empty<HostFunction>(), withWasi = true)
```

> **Note**: The schema for this manifest can be found here: https://extism.org/docs/concepts/manifest/
Expand All @@ -71,14 +68,13 @@ This plug-in was written in Rust and it does one thing, it counts vowels in a st
C#:
```csharp
var output = plugin.Call("count_vowels", "Hello, World!");

Console.WriteLine(output);
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
```

F#:
```fsharp
let output = plugin.Call("count_vowels", "Hello, World!")

// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
```

Expand All @@ -91,9 +87,11 @@ Plug-ins may be stateful or stateless. Plug-ins can maintain state b/w calls by
C#:
```csharp
var output = plugin.Call("count_vowels", "Hello, World!");
Console.WriteLine(output);
// => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}

output = plugin.Call("count_vowels", "Hello, World!");
Console.WriteLine(output);
// => {"count": 3, "total": 9, "vowels": "aeiouAEIOU"}
```

Expand All @@ -114,45 +112,51 @@ Plug-ins may optionally take a configuration object. This is a static way to con

C#:
```csharp
var manifest = new Manifest(new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"));
var manifest = new Manifest(new UrlWasmSource("<https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm>"));

using var plugin = new Plugin(manifest, new HostFunction[] { }, withWasi: true);

var output = plugin.Call("count_vowels", "Yellow, World!");
Console.WriteLine(output);
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

var manifest = new Manifest(new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"))
manifest = new Manifest(new UrlWasmSource("<https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm>"))
{
Config = new Dictionary<string, string>
{
{ "vowels", "aeiouyAEIOUY" }
},
};

using var plugin = new Plugin(manifest, new HostFunction[] { }, withWasi: true);
using var plugin2 = new Plugin(manifest, new HostFunction[] { }, withWasi: true);

var output = plugin.Call("count_vowels", "Yellow, World!");
var output2 = plugin2.Call("count_vowels", "Yellow, World!");
Console.WriteLine(output2);
// => {"count": 4, "total": 4, "vowels": "aeiouAEIOUY"}
```

F#:
```fsharp
let uri = Uri("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm")
let manifest = Manifest(new UrlWasmSource(uri))
manifest.Config.Add("vowels", "aeiouyAEIOUY")
manifest.Config <- dict [("vowels", "aeiouAEIOU")]

use plugin = Plugin(manifest, Array.empty<HostFunction>(), withWasi = true)
let plugin = new Plugin(manifest, Array.Empty<HostFunction>(), withWasi = true)

let output = plugin.Call("count_vowels", "Yellow, World!")
Console.WriteLine(output)
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

let manifest =
Manifest(new UrlWasmSource(Uri("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm")),
Config = Dictionary<string, string>([("vowels", "aeiouyAEIOUY")]))
let manifest2 =
Manifest(new UrlWasmSource(Uri("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm")))
manifest2.Config <- dict [("vowels", "aeiouyAEIOUY")]

use plugin =
Plugin(manifest, Array.empty<HostFunction>(), withWasi = true)
let plugin2 =
new Plugin(manifest2, Array.Empty<HostFunction>(), withWasi = true)

let output = plugin.Call("count_vowels", "Yellow, World!")
let output2 = plugin2.Call("count_vowels", "Yellow, World!")
Console.WriteLine(output2)
// => {"count": 4, "total": 4, "vowels": "aeiouAEIOUY"}
```

### Host Functions
Expand Down Expand Up @@ -249,31 +253,31 @@ using var plugin = new Plugin(manifest, functions, withWasi: true);
var output = plugin.Call("count_vowels", "Hello World!");

Console.WriteLine(output);
// => Read from key=count-vowels"
// => Read 0 from key=count-vowels"
// => Writing value=3 from key=count-vowels"
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

output = plugin.Call("count_vowels", "Hello World!");

Console.WriteLine(output);
// => Read from key=count-vowels"
// => Read 3 from key=count-vowels"
// => Writing value=6 from key=count-vowels"
// => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}
```

F#:
```fsharp
use plugin = Plugin(manifest, functions, withWasi = true)
let plugin = new Plugin(manifest, functions, withWasi = true)

let output = plugin.Call("count_vowels", "Hello World!")
printfn "%s" output
// => Read from key=count-vowels
// => Read 0 from key=count-vowels
// => Writing value=3 from key=count-vowels
// => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}

let output2 = plugin.Call("count_vowels", "Hello World!")
printfn "%s" output2
// => Read from key=count-vowels
// => Read 3 from key=count-vowels
// => Writing value=6 from key=count-vowels
// => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}
```
13 changes: 8 additions & 5 deletions src/Extism.Sdk/Manifest.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,14 +23,17 @@ public Manifest()
/// <param name="sources"></param>
public Manifest(params WasmSource[] sources)
{
Sources.AddRange(sources);
foreach (var source in sources)
{
Sources.Add(source);
}
}

/// <summary>
/// List of Wasm sources. See <see cref="PathWasmSource"/> and <see cref="ByteArrayWasmSource"/>.
/// </summary>
[JsonPropertyName("wasm")]
public List<WasmSource> Sources { get; set; } = new();
public IList<WasmSource> Sources { get; set; } = new List<WasmSource>();

/// <summary>
/// Configures memory for the Wasm runtime.
Expand All @@ -50,7 +53,7 @@ public Manifest(params WasmSource[] sources)
/// </code>
/// </summary>
[JsonPropertyName("allowed_hosts")]
public List<string> AllowedHosts { get; set; } = new();
public IList<string> AllowedHosts { get; set; } = new List<string>();

/// <summary>
/// List of directories that can be accessed by the plugins. Examples:
Expand All @@ -63,7 +66,7 @@ public Manifest(params WasmSource[] sources)
/// </code>
/// </summary>
[JsonPropertyName("allowed_paths")]
public Dictionary<string, string> AllowedPaths { get; set; } = new();
public IDictionary<string, string> AllowedPaths { get; set; } = new Dictionary<string, string>();

/// <summary>
/// Configurations available to the plugins. Examples:
Expand All @@ -76,7 +79,7 @@ public Manifest(params WasmSource[] sources)
/// </code>
/// </summary>
[JsonPropertyName("config")]
public Dictionary<string, string> Config { get; set; } = new();
public IDictionary<string, string> Config { get; set; } = new Dictionary<string, string>();

/// <summary>
/// Plugin call timeout.
Expand Down
Loading