Docs
Free trial

Getting started

There are two ways to use the Octopus Client library:

  1. The Octopus.Server.Client package is a standard NuGet package useful for normal applications.
  2. The Octopus.Client package is a NuGet package containing an ILMerged single Octopus.Client.dll comprising Octopus.Server.Client.dll (above) and all of its dependencies. This is useful for scripting where importing a single .NET assembly is preferable.

Usage guidance

  • Unless you have a specific need to use the ILMerged Octopus.Client, we recommend using the Octopus.Server.Client package. In both cases, the calling conventions are identical - the former is just an ILMerged version of the latter.
  • If you’re intending to use the contract DTO classes from the library with your own serialization mechanism, you’ll definitely want to use Octopus.Server.Client. The ILMerged client also merges in Newtonsoft.Json so your own serializer won’t recognize any of the serialization attributes.

Using Octopus.Client from installation folder

Octopus Server and Tentacle both ship with a version of Octopus.Client.dll in the installation directory. Avoid using this in your scripts as this is considered an implementation detail of those products. As such it is subject to change at any time, and not guaranteed to work with your version of Octopus Server.

Getting started with the Octopus Client in a .NET application

Package installation

To use from C#, first install the package via the NuGet Package Manager:

Package Management Console
Install-Package Octopus.Server.Client
.NET CLI
dotnet add package Octopus.Server.Client

Creating and using the client (Synchronous API)

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

var server = "https://your-octopus-url";
var apiKey = "API-YOUR-KEY";             // Get this from your 'profile' page in the Octopus Web Portal
var endpoint = new OctopusServerEndpoint(server, apiKey);
var repository = new OctopusRepository(endpoint);

API key authentication is recommended, but you can use username/password for authentication with the SignIn() method instead:

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

Creating and using the client (Asynchronous API)

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

var server = "https://your-octopus-url";
var apiKey = "API-YOUR-KEY";             // 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" });

Getting started with the Octopus Client package in a PowerShell script

Package installation

To get started with the Octopus Client library from PowerShell, use the Install-Package command from the Microsoft PackageManagement module:

Windows PowerShell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
Install-Package Octopus.Client -source https://www.nuget.org/api/v2 -SkipDependencies
$path = Join-Path (Get-Item ((Get-Package Octopus.Client).source)).Directory.FullName "lib/net462/Octopus.Client.dll"
Add-Type -Path $path
PowerShell Core
Install-Package Octopus.Client -source https://www.nuget.org/api/v2 -SkipDependencies
$path = Join-Path (Get-Item ((Get-Package Octopus.Client).source)).Directory.FullName "lib/netstandard2.0/Octopus.Client.dll"
Add-Type -Path $path

Note: The PowerShell Core example above needs the path to be slightly different than the one for Windows PowerShell.

If you’re referencing an older version of the .NET Standard version of Octopus.Client, you may find you also need to add a reference to NewtonSoft.Json.dll and Octodiff:

# Using `Install-Package`
$path = Join-Path (Get-Item ((Get-Package NewtonSoft.Json).source)).Directory.FullName "lib/netstandard2.0/NewtonSoft.Json.dll"
Add-Type -Path $path

$path = Join-Path (Get-Item ((Get-Package Octodiff).source)).Directory.FullName "lib/netstandard2.0/Octodiff.dll"
Add-Type -Path $path

Creating an instance of the client

Add-Type -Path 'C:\PathTo\Octopus.Client.dll'
$server = "https://your-octopus-url"
$apiKey = "API-YOUR-KEY";              # Get this from your 'profile' page in the Octopus Web Portal
$endpoint = New-Object Octopus.Client.OctopusServerEndpoint($server, $apiKey)
$repository = New-Object Octopus.Client.OctopusRepository($endpoint)

Using the synchronous API

$loginCreds = New-Object Octopus.Client.Model.LoginCommand
$loginCreds.Username = "me"
$loginCreds.Password = "secret"
$repository.Users.SignIn($loginCreds)

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Tuesday, June 25, 2024

Edit on GitHub