RshipSdk 1.0.3

RshipSdk for .NET

RshipSdk is a high-level SDK for building real-time applications with the Rship platform. It provides instance management, action handling, emitter support, and seamless integration.

Features

• Instance Management: Create and manage application instances
• Action Handling: Define and handle incoming actions with type safety
• Emitter Support: Send real-time data with structured emitters
• Target Management: Organize functionality into logical targets
• JSON Schema Generation: Automatic schema generation for type safety
• Real-time WebSocket communication with the Rship platform
• Automatic reconnection and state management
• Async/await support throughout
• Comprehensive logging support via Microsoft.Extensions.Logging

Installation

dotnet add package RshipSdk

Or add to your .csproj file:

<PackageReference Include="RshipSdk" Version="0.1.15" />

Quick Start

using Microsoft.Extensions.Logging;
using RshipSdk;

// Define your data types
public class MyActionData
{
    public string Data { get; set; } = string.Empty;
}

public class MyEmitterType  
{
    public string Data { get; set; } = string.Empty;
}

// Setup logging (optional)
using var loggerFactory = LoggerFactory.Create(builder =>
    builder.AddConsole().SetMinimumLevel(LogLevel.Information));
var logger = loggerFactory.CreateLogger<SdkClient>();

// Create and configure the SDK client
var sdk = SdkClient.Init(logger);
await sdk.SetAddressAsync("ws://localhost:8080/myko");
await sdk.AwaitConnectionAsync();

// Create an instance
var instance = await sdk.AddInstanceAsync(new InstanceArgs
{
    Name = "My Application",
    ShortId = "my-app",
    Code = "my-app-code",
    ServiceId = "my-service",
    Color = "#FF0000",
    MachineId = "my-machine",
    Status = InstanceStatus.Available
});

// Create a target
var target = await instance.AddTargetAsync(new TargetArgs
{
    Name = "My Target",
    ShortId = "my-target", 
    Category = "automation"
});

// Add an action handler
await target.AddActionAsync(
    ActionArgs<MyActionData>.New("Process Data", "process-data"),
    async (action, data) =>
    {
        Console.WriteLine($"Processing: {data.Data}");
        // Your action logic here
    }
);

// Add an emitter
var emitter = await target.AddEmitterAsync(
    EmitterArgs<MyEmitterType>.New("Status Updates", "status")
);

// Send data via emitter
await emitter.PulseAsync(new MyEmitterType 
{ 
    Data = "Hello from C#!" 
});

Core Concepts

SdkClient

The main entry point for the SDK. Manages the WebSocket connection and provides methods to create instances.

Instance

Represents a service instance in the Rship ecosystem. Contains targets and manages their lifecycle.

Target

A logical grouping of actions and emitters. Represents a controllable entity in your application.

Actions

Incoming message handlers. Define what your application can do when triggered by the Rship platform.

Emitters

Outgoing message producers. Send data from your application to the Rship platform.

Environment Variables

• RSHIP_ADDRESS: The Rship server address (default: localhost)
• RSHIP_PORT: The Rship server port (default: 8080)

Advanced Usage

Custom Logging

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder
        .AddConsole()
        .AddDebug() 
        .SetMinimumLevel(LogLevel.Debug);
});

var sdk = SdkClient.Init(loggerFactory.CreateLogger<SdkClient>());

Error Handling

try 
{
    await emitter.PulseAsync(data);
}
catch (InvalidOperationException ex)
{
    // Handle connection issues
    Console.WriteLine($"Connection error: {ex.Message}");
}

Connection Status Monitoring

// The SDK automatically handles reconnection, but you can monitor status
await sdk.AwaitConnectionAsync(); // Blocks until connected

Building from Source

git clone https://github.com/rship/rship.git
cd rship/libs/sdk/csharp
dotnet build

Running Examples

cd Examples
dotenv restore
dotnet run

Dependencies

• .NET 8.0+
• System.Text.Json
• Microsoft.Extensions.Logging.Abstractions
• Websocket.Client
• NJsonSchema

License

AGPL-3.0-or-later

Contributing

Please see the main Rship repository for contribution guidelines.