managedcode-communication

name	managedcode-communication
description	Use ManagedCode.Communication when a .NET application needs explicit result objects, structured errors, and predictable service or API boundaries instead of exception-driven control flow. USE FOR: integrating ManagedCode.Communication into services or APIs; replacing exception-driven result handling with explicit results; reviewing service boundaries that return. DO NOT USE FOR: unrelated stacks; generic tasks that do not need this specific guidance. INVOKES: inspect the repository context, edit targeted files, and run relevant build, test, lint, or validation commands when changes are made.
compatibility	Requires a .NET application, service layer, or API boundary that integrates ManagedCode.Communication.

ManagedCode.Communication

Trigger On

• integrating ManagedCode.Communication into services or APIs
• replacing exception-driven result handling with explicit results
• reviewing service boundaries that return success or failure payloads
• documenting result-pattern usage across ASP.NET Core or application services
• mapping application errors to RFC 7807 problem details, Minimal API results, SignalR filters, or Orleans call filters

Install

Use the package that matches the boundary. Current upstream release reviewed: v10.2.2.

dotnet add package ManagedCode.Communication
dotnet add package ManagedCode.Communication.AspNetCore
dotnet add package ManagedCode.Communication.Extensions
dotnet add package ManagedCode.Communication.Orleans

For pinned project files:

<PackageReference Include="ManagedCode.Communication" Version="10.2.2" />
<PackageReference Include="ManagedCode.Communication.AspNetCore" Version="10.2.2" />
<PackageReference Include="ManagedCode.Communication.Extensions" Version="10.2.2" />
<PackageReference Include="ManagedCode.Communication.Orleans" Version="10.2.2" />

Workflow

1. Confirm the boundary where the library belongs:
   • service result contracts
   • application manager boundaries
   • API endpoints that translate results into HTTP responses
2. Keep result creation and error mapping explicit instead of mixing exceptions, nulls, and ad-hoc tuples.
3. Pattern-match result objects at the boundary that converts them into user-facing responses.
4. Do not hide domain failures behind generic success wrappers.
5. Configure framework integration only where it removes manual translation:
   • ConfigureCommunication() for ASP.NET Core logging and converters
   • WithCommunicationResults() for Minimal API endpoint or group conversion
   • Orleans or SignalR packages only when those runtime filters are actually in use
6. Validate positive, negative, and error-path handling after integration.

flowchart LR
  A["Domain or service operation"] --> B["ManagedCode.Communication result"]
  B --> C["Application or API boundary"]
  C --> D["HTTP response or caller-visible contract"]

Practical Usage

Read path with explicit failures

public sealed class OrderService(IOrderRepository orders)
{
    public async Task<Result<OrderDto>> GetAsync(Guid id, CancellationToken ct)
    {
        var order = await orders.FindAsync(id, ct);

        return order is null
            ? Result<OrderDto>.FailNotFound($"Order {id} was not found.")
            : Result<OrderDto>.Succeed(OrderDto.From(order));
    }
}

Use this shape when absence, validation, authorization, or domain rejection is an expected outcome. Reserve exceptions for unexpected infrastructure faults.

Write path through Minimal APIs

var builder = WebApplication.CreateBuilder(args);

builder.Services.ConfigureCommunication();

var app = builder.Build();

app.MapGroup("/orders")
   .WithCommunicationResults()
   .MapPost(string.Empty, async (CreateOrder command, OrderService orders, CancellationToken ct) =>
        await orders.CreateAsync(command, ct));

Handlers can return Result or Result<T> and let the extension package map failures to HTTP results and problem details at the API boundary.

Compose validation and domain steps

public async Task<Result<OrderReceipt>> CreateAsync(CreateOrder command, CancellationToken ct)
{
    var validation = Validate(command);
    if (validation.IsFailed)
    {
        return Result<OrderReceipt>.Fail(validation.Problem!);
    }

    return await Result<Order>.From(() => BuildOrder(command))
        .ThenAsync(order => SaveAsync(order, ct))
        .Then(order => Result<OrderReceipt>.Succeed(new OrderReceipt(order.Id, order.CreatedAt)));
}

Use railway-style composition when each step can return a result and the caller should stop at the first real failure.

Options And Constraints

• Result, Result<T>, CollectionResult<T>, and Problem are the core surfaces. Keep them at service/API boundaries rather than leaking framework-specific HTTP results into domain code.
• CollectionResult<T> plus PaginationRequest / PaginationOptions should own paged API metadata instead of ad-hoc (items, total) tuples.
• Minimal APIs can use WithCommunicationResults() on one endpoint or an entire group. Prefer the group form only when every child endpoint follows the same result contract.
• ManagedCode.Communication.Orleans is for grain-call integration and serialization boundaries; use it with the Orleans skill when reviewing grain APIs.
• v10.2.2 adds native ICommandExecutor reliability: bounded retry/backoff and jitter, whole-sequence timeouts, circuit breaking, rate limiting, idempotency, OpenTelemetry signals, and an IHttpClientFactory resilience handler. Keep one retry owner, honor Retry-After, and require idempotent side effects before enabling retries.
• Task and ValueTask result and railway paths are now symmetric, and primitive failures have dedicated coverage. Use ValueTask only for operations that frequently complete synchronously and are consumed once; test both success and failure shapes after upgrading.
• Orleans command execution can use distributed rate limiting and durable idempotency, but it requires the documented commandStore grain storage and explicit UseOrleansCommandExecution() configuration. Do not silently replace application-owned operation identity or retry policy.

Deliver

• guidance on where explicit result objects improve clarity
• usage boundaries for translating results into API or caller responses
• validation expectations for success and failure flows
• package and integration choices for the actual runtime boundary

Validate

• result handling is consistent across the boundary that uses the library
• callers do not fall back to exception-only logic for normal failure cases
• negative and error scenarios are documented and tested
• Minimal API endpoints return expected success and RFC 7807 failure shapes
• pagination metadata is stable when CollectionResult<T> is used
• Orleans or SignalR integration is covered by runtime-level tests when those packages are installed