PlanSolve 0.34.0

PlanSolve for .NET

Official .NET client for the PlanSolve optimization API. One typed client covers three solvers (field service routing, professional-services task assignment, and shift scheduling) with async/await, built-in polling, and clean error messages.

Installation

dotnet add package PlanSolve

Targets .NET 10.

Quick start

using PlanSolve;
using PlanSolve.FieldService;

using var client = new PlanSolveClient("YOUR_API_KEY");

var request = new FieldServiceStartRequest
{
    Vehicles =
    {
        new Vehicle
        {
            Id = "tech1",
            Location = [40.7128, -74.0060],
            Skills = ["repair"],
            Shifts = [new Shift("morning", DateTime.Parse("2026-04-02T08:00:00"), DateTime.Parse("2026-04-02T17:00:00"))],
        },
    },
    Visits =
    {
        new Visit
        {
            Id = "visit1",
            Name = "AC Repair - Downtown Office",
            Location = [40.7589, -73.9851],
            ServiceDuration = Duration.FromMinutes(60),
            Priority = "HIGH",
            RequiredSkills = ["repair"],
        },
    },
};

// Submit and await the optimized plan in a single call
var result = await client.FieldService.StartAndWaitForCompletionAsync(request);

foreach (var vehicle in result.Vehicles)
    Console.WriteLine($"Vehicle {vehicle.Id}: {vehicle.Visits.Count} visits");

Every vehicle shift needs an Id. Priority on a visit or task is optional: leave it null and the solver plans the item as MEDIUM.

Solvers

One client, three solvers. All share the same submit, poll, result workflow:

Every accessor exposes the same methods:

GetStatusAsync, GetResultAsync, StopAsync and GetAnalysisAsync also have an overload that takes a CancellationToken.

// Stop a long-running solve early and keep the best plan found so far
try
{
    var best = await client.FieldService.StopAsync(jobId);
}
catch (JobCancelledException e)
{
    // The job was still waiting in the queue: it is cancelled, no plan exists and nothing is billed.
    Console.WriteLine($"{e.JobId}: {e.Message}");
}

// Explain the score: which constraints were broken, and by what
var analysis = await client.FieldService.GetAnalysisAsync(jobId);

Score

Score is a struct with Hard, Medium and Soft levels (long). A solution is feasible when Hard >= 0. Parse it from the canonical "Xhard/Ymedium/Zsoft" string with Score.Parse/TryParse, or rely on the implicit conversions to and from string.

Score fields on the result and status responses are Score?: null while a job is still solving, and also for a job the solver has not scored yet.

var result = await client.FieldService.GetResultAsync(jobId);
if (result.Score is { } score)
    Console.WriteLine($"{score} (feasible: {score.Hard >= 0})");

AnalysisResponse.Score, ConstraintAnalysis.Weight, ConstraintAnalysis.Score and ConstraintMatch.Score are also Score?: a missing or unparseable score on one constraint or match yields null for that field rather than failing the whole analysis, since analysis is a diagnostic surface where partial data still has value.

scoreString no longer exists on the Shift and Professional Services result responses — use the typed Score instead.

Shift results

ShiftResultResponse.AssignedShifts and UnassignedShifts are lists of shift names (a shift with Value > 1 is listed once per position, as "{name}#1", "{name}#2"...). The shifts themselves, with the employee the solver chose in AssignedEmployee, are in Shifts:

var result = await client.Shift.GetResultAsync(jobId);
foreach (var shift in result.Shifts ?? [])
    Console.WriteLine($"{shift.Name}: {shift.From} -> {shift.To} ({shift.AssignedEmployee ?? "unassigned"})");

Jobs

client.Jobs lists and reads job records. JobDto.Status is a JobStatus (Pending, Succeeded, Failed, Lost, Cancelled); JobDto.SolverType is a number you can compare with SolverTypes.FieldService (0), SolverTypes.Shift (1) and SolverTypes.ProfessionalServices (2).

Polling

WaitForCompletionAsync and StartAndWaitForCompletionAsync poll the status endpoint every pollIntervalMs milliseconds, up to maxAttempts times. The defaults are 5000 ms x 150 attempts (12.5 minutes), which covers the server's 10 minute solve cap with headroom. Passing a value of 0 or less uses the default.

A job is complete when the status reports Solving == false and SolverStatus == NOT_SOLVING. The result is then fetched with GetResultAsync. Status polls during the wait, and result fetches, are retried on transient failures only (a network error, or a 408, 429 or 5xx answer), up to 3 times with 2, 4 and 8 second backoff, before the error is thrown. Any other error, such as 401, 404 or 422, is thrown on the first response. StopAsync is not retried. The library never writes to the console.

Configuration

Pass your API key to the constructor: new PlanSolveClient("...") (an overload accepts a custom HttpClient). It is sent as the X-API-KEY header on every request. PlanSolveClient is IDisposable, so wrap it in using.

Error handling

try
{
    var result = await client.FieldService.StartAndWaitForCompletionAsync(request);
}
catch (HttpRequestException e)
{
    Console.WriteLine($"API error {(int?)e.StatusCode}: {e.Message}");
}
catch (TimeoutException e)
{
    Console.WriteLine(e.Message);
}

Documentation

Full guides, per-solver data models, and parameter reference live on the docs site:

• Field Service: https://getplansolve.com/docs/fieldservice/sdk/dotnet
• Professional Services: https://getplansolve.com/docs/professionalservices/sdk/dotnet
• Shift: https://getplansolve.com/docs/shiftsolver/sdk/dotnet

Package: NuGet

License

Apache-2.0