This documentation is for Octopus Deploy Version 3.11. View the latest version.

Octopus.Client

Last updated

Octopus.Client is an open source .NET library that makes it easy to write C# programs that manipulate the Octopus Deploy REST API.

Because the Octopus Deploy application itself is built entirely on the API, C# programs using the API can do anything that could be done by a user of the application itself.

The NuGet package contains both a .NET Framework build as well as a .NET Standard build. The .NET Framework build targets 4.5 or later and contains both the synchronous and asynchronous API. The .NET Standard build is compatible with a variety of runtimes, including .NET Core 1.0 and only contains the asynchronous API.

Getting started

The complete details for the API itself - where to find it, how to authenticate, the available resources and so-on - are available at the API documentation site.

To use the C# client, first install the package via NuGet:

Install-Package Octopus.Client

Synchronous API

The easiest way to use the client is via the OctopusRepository helper:

var server = "http://myoctopusserver/";   
var apiKey = "API-XXXXXXXX";             // Get this from your 'profile' page in the Octopus web portal
var endpoint = new OctopusServerEndpoint(server, apiKey);
var repository = new OctopusRepository(endpoint);

If you don't want to provide an API key for authentication, you can leave it out and authenticate with the SignIn() method instead:

repository.Users.SignIn(new LoginCommand { Username = "me", Password = "secret" });

Asynchronous API (Octopus.Client 4.0+)

The easiest way to use the client is via the OctopusAsyncClient:

var server = "http://myoctopusserver/";   
var apiKey = "API-XXXXXXXX";             // Get this from your 'profile' page in the Octopus web portal
var endpoint = new OctopusServerEndpoint(server, apiKey);
using (var client = await OctopusAsyncClient.Create(endpoint))
{
}

If you don't want to provide an API key for authentication, you can leave it out and authenticate with the SignIn() method instead:

await client.Repository.Users.SignIn(new LoginCommand { Username = "me", Password = "secret" });

Powershell

Add-Type -Path 'C:\PathTo\Octopus.Client.dll'
$endpoint = New-Object Octopus.Client.OctopusServerEndpoint("http://localhost",$ApiKey)
$repository = New-Object Octopus.Client.OctopusRepository($endpoint)

OctoPosh
Also see the OctoPosh project, which provides PowerShell commandlet wrappers around Octopus.Client

Working with resources

Resources can be loaded and saved with code like the following:

// Sync
var machine = repository.Machines.Get("machines-1");
machine.Name = "Test Server 1";
repository.Machines.Modify(machine);
 
// Async
var machine = await repository.Machines.Get("machines-1");
machine.Name = "Test Server 1";
await repository.Machines.Modify(machine);

The repository methods all make direct HTTP requests, there's no "session" abstraction or transaction support.

Working directly with the client

For some operations not available through repositories it will be necessary to use the IOctopusClient type:

// Sync
var connection = repository.Client.Get(machine.Links["Connection"]);
 
// Async
var connection = await client.Get(machine.Links["Connection"]);

The entire API is accessible by traversing links - each resource carries a collection of links, like the "Connection" link on MachineResource shown above.

To start traversing links, IOctopusClient.RootDocument is provided:

// Sync
var me = repository.Client.Get<UserResource>(repository.Client.RootDocument.Links["CurrentUser"]);
 
// Async
var me = await client.Get<UserResource>(client.RootDocument.Links["CurrentUser"])

(This example is superfluous as repository.Users.GetCurrent() wraps this common operation.)

Loading in an Octopus step

You can use Octopus.Client from inside Octopus (for example in a script step, a package install script, or the script console) by loading it from the server or Tentacle application directory. The credentials would still need to be supplied to establish the connection. For example:

PowerShell

Add-Type -Path 'C:\Program Files\Octopus Deploy\Octopus\Octopus.Client.dll'

C# Script

#r "C:\\Program Files\\Octopus Deploy\\Octopus\\Octopus.Client.dll"
using Octopus.Client;
using Octopus.Client.Model;

Tip
The variable Octopus.Tentacle.Agent.ProgramDirectoryPath was added in server version 3.7.12, which can be used to obtain the directory that contains the Octopus.Client assembly. For prior versions of the server, the variable Octopus.Tentacle.Agent.ProgramDirectoryPath can be used, but that will not work for steps that run on the Octopus server or cloud regions.

Documentation and samples

Documentation and samples for the Octopus Deploy REST API are available on the Octopus REST API GitHub site, along with Octopus.Client samples.