ORYX.Contracts 0.2.0

ORYX.Contracts

Shared execution contracts for the ORYX component ecosystem. This library defines the interfaces and types used by components and the node runtime so that components can be developed and hosted in a consistent way across the platform.

Repository: https://github.com/Baltigo/oryx-contracts

Prerequisites

• .NET 8.0 SDK or later

Package

API Overview

Public types live in ORYX.Contracts.Execution and ORYX.Contracts.Execution.Results.

Execution contracts

Step execution result (JSON)

Step results are written by ComponentHost/Runner as versioned, machine-readable JSON. These types live in ORYX.Contracts.Execution.Results:

WorkloadContext

public sealed record WorkloadContext(
    Guid TenantId,
    Guid WorkloadId,
    Guid AttemptId,
    IReadOnlyDictionary<string, string> Inputs,
    IWorkloadLogger Logger);

The node provides this context when invoking a component. Use Inputs for parameters and Logger for structured output.

ComponentResult

public sealed record ComponentResult(
    bool Success,
    int ExitCode,
    string? Message = null);

Return this from ExecuteAsync to report success/failure, exit code, and an optional message.

Step result format: legacy vs new

• Legacy: Step results were sometimes written as plain text (e.g. result.txt) with key=value or similar formats.
• Current: Step results are written as result.json (not result.txt) using StepExecutionResultDto. Path: <ExecutionRoot>/Steps/<StepIndex>/result.json. Serialization uses System.Text.Json with camelCase property names, enums as strings (JsonStringEnumConverter), and DateTimeOffset in ISO8601 with Z when UTC.

Example payload (successful step with optional output):

{
  "schemaVersion": 1,
  "executionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "stepExecutionId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "stepIndex": 0,
  "status": "Succeeded",
  "timing": {
    "startedAtUtc": "2025-02-26T10:00:00Z",
    "finishedAtUtc": "2025-02-26T10:00:05Z",
    "durationMs": 5000
  },
  "component": {
    "componentPackageId": "d4e5f6a7-b8c9-0123-def0-234567890123",
    "packageName": "oryx-component-example",
    "componentKey": "example.run",
    "componentVersion": "1.0.0"
  },
  "output": { "filesCreated": 3, "path": "/out" },
  "error": null
}

For a failed step, status is "Failed" and error is populated, e.g. { "code": "ERR_RUNTIME", "message": "Operation failed", "details": "..." }.

Example: implementing a component

using ORYX.Contracts.Execution;

namespace MyComponent;

public record MyOptions(string RepoUrl, string Branch) : IComponentOptions;

public class MyComponent : ComponentBase<MyOptions>
{
    public override string Id => "my.git-clone";
    public override string Version => "1.0.0";

    public override async Task<ComponentResult> ExecuteAsync(
        WorkloadContext context,
        MyOptions options,
        CancellationToken cancellationToken)
    {
        context.Logger.LogInformation("Cloning {RepoUrl} @ {Branch}", options.RepoUrl, options.Branch);
        // ... perform work ...
        return new ComponentResult(Success: true, ExitCode: 0, Message: "Done");
    }
}

Building

From the repository root:

dotnet build

Consuming

All projects must reference ORYX.Contracts via NuGet only. Do not add a ProjectReference to the oryx-contracts project.

The package is published to NuGet.org. To add it to your component or host project:

.NET CLI

dotnet add package ORYX.Contracts

To pin a specific version (e.g. 0.2.0):

dotnet add package ORYX.Contracts --version 0.2.0

Package Manager Console (Visual Studio)

Install-Package ORYX.Contracts

PackageReference (in your .csproj)

<PackageReference Include="ORYX.Contracts" Version="0.2.0" />

Central Package Management (Directory.Packages.props)

In Directory.Packages.props:

<PackageVersion Include="ORYX.Contracts" Version="0.2.0" />

In your project file:

<PackageReference Include="ORYX.Contracts" />

Related

• oryx-componentagent — Runtime entry point that authenticates to ORYX Core and runs components; references this library.
• oryx-node — Node runtime that executes workloads and provides WorkloadContext to components.

License

MIT