Octopus Deploy Documentation

Getting started

Last updated

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

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/net452/Octopus.Client.dll"
Add-Type -Path $path
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 that for the PowerShell Core example above, the path needs to be slightly different than the one for PowerShell.

If you're referencing the netstandard 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

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

PM> Install-Package Octopus.Client

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.

Synchronous API

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

Add-Type -Path 'C:\PathTo\Octopus.Client.dll'
$server = "https://myoctopus.example.com"
$apiKey = "API-YOURKEY";              # 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)
var server = "https://myoctopus.example.com/";
var apiKey = "API-YOURKEY";             // 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:

$loginCreds = New-Object Octopus.Client.Model.LoginCommand
$loginCreds.Username = "me"
$loginCreds.Password = "secret"
$repository.Users.SignIn($loginCreds)
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 = "https://myoctopus.example.com/";
var apiKey = "API-YOURKEY";             // 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" });

Need support? We're here to help.