ForEach.Infrastructure.External.Octopus 0.1.0

dotnet add package ForEach.Infrastructure.External.Octopus --version 0.1.0
                    
NuGet\Install-Package ForEach.Infrastructure.External.Octopus -Version 0.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ForEach.Infrastructure.External.Octopus" Version="0.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="ForEach.Infrastructure.External.Octopus" Version="0.1.0" />
                    
Directory.Packages.props
<PackageReference Include="ForEach.Infrastructure.External.Octopus" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add ForEach.Infrastructure.External.Octopus --version 0.1.0
                    
#r "nuget: ForEach.Infrastructure.External.Octopus, 0.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package ForEach.Infrastructure.External.Octopus@0.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=ForEach.Infrastructure.External.Octopus&version=0.1.0
                    
Install as a Cake Addin
#tool nuget:?package=ForEach.Infrastructure.External.Octopus&version=0.1.0
                    
Install as a Cake Tool

ForEach.Infrastructure.External.Octopus

Typed clients for the four web services of Octopus (the Belgian accounting package by Inaras, not Octopus Deploy): the Rest, Management, file sync and file import APIs. The Refit interfaces are generated from the OpenAPI documents Octopus publishes; the package adds the token flow, the authentication handler, error parsing and DI registration. It is a plain client: it knows nothing about the application that uses it (no site or dossier mapping, no accounting logic).

// The token provider needs a TimeProvider (TimeProvider.System in production).
services.AddSingleton(TimeProvider.System);

services.AddOctopusClients(
    options =>
    {
        options.IsEnabled = true;
        options.SoftwareHouseUuid = "<issued by Octopus>";
        options.User = "<web-service user>";
        options.Password = "<secret>";
    },
    configureBuilder: (builder, clientName, isTokenClient) =>
        builder.AddStandardResilienceHandler());   // optional: resilience per HttpClient

// ...
var bookyears = await restApi.GetBookyears(dossierId, cancellationToken);

Bind the options from configuration with options => configuration.GetSection("Octopus").Bind(options).

Member What it does
AddOctopusClients Registers the validated OctopusOptions, the singleton IOctopusTokenProvider, and one Refit client per API (IOctopusRestApi, IOctopusManagementApi, IOctopusFileSyncApi, IOctopusFileImportApi), each behind OctopusAuthenticationHandler. configureBuilder is called once for the token client and once per API client so the host can add resilience.
OctopusOptions Section Octopus: IsEnabled (default false), the four base URLs (default: the Inaras production hosts), SoftwareHouseUuid, User, Password, Locale, TokenLifetime, TokenExpiryBuffer. Validated on start: credentials are required when enabled and the URLs must be absolute http(s).
IOctopusTokenProvider One authentication token per API and one dossier token per (API, dossier), cached and refreshed before expiry.
OctopusAuthenticationHandler Attaches the right credential to every call by route (dossierToken for /dossiers/{id}/..., bearer token for the Management API, ...), re-acquires and resends once on a 401. A forward-only stream body is never resent.
OctopusApiError Describe, Parse, IsNotFound, IsUnauthorized, IsForbidden, IsDisabled: turns Refit's ApiException into the reason Octopus gave, in either documented error-body shape.
OctopusIntegrationDisabledException Thrown (wrapped by Refit) before any traffic while IsEnabled is false.

Credentials are global to the client (one Software House ID and one web-service user); the dossier is a parameter of each call, so a host that serves several dossiers keeps that mapping itself.

Octopus enforces daily call caps per operation (for example 150 dossier tokens a day, 48 */modified reads, 400 relation or booking writes); tokens are therefore acquired lazily and cached. Retry only idempotent calls (GET, PUT, DELETE): a POST inserts a booking or, on the Management API, can cost money.

The three application/octet-stream uploads (UploadInvoiceAttachment, ImportSoda, LoadDocumentByMailAddress) are hand-written with [Body] Stream (*.Streams.cs); Refitter emits them as StreamPart, which Refit accepts only under [Multipart].

Regenerating the clients

src/ForEach.Infrastructure.External.Octopus/Codegen/ holds the OpenAPI documents (specs/, as published, unmodified), one Refitter settings file per API (*.refitter) and the script:

pwsh packages/Octopus/src/ForEach.Infrastructure.External.Octopus/Codegen/Generate-OctopusClients.ps1 [-Download]

Refitter is pinned in packages/Octopus/.config/dotnet-tools.json (2.0.0, the version the committed code was generated with; running the script with it reproduces Generated/ byte for byte). -Download first refreshes the specs from https://service.inaras.be/<api>/v1/openapi.json; review that diff before regenerating. The auth headers (Token, dossierToken, softwareHouseUuid) are left out of the generated signatures (ignoredOperationHeaders) because the handler attaches them, so a spec that adds a header parameter or a route also needs Auth/OctopusRequestAuthorization.cs updated.

Relation to ForEach.Connectors.Octopus

The old, unrelated ForEach.Connectors.Octopus (7.0.9) is superseded by this package. It is not a predecessor of this code base and nothing here depends on it; new code should use ForEach.Infrastructure.External.Octopus.

Targets net8.0 and net10.0. Dependencies: Refit, Refit.HttpClientFactory and Microsoft.Extensions.Http. Source and release notes: https://github.com/foreach-rs/nuget-releases/tree/main/packages/Octopus

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0 55 11/19/2026