There are two ways to use the Octopus Client library:
- The
Octopus.Server.Client
package is a standard NuGet package useful for normal applications. - The
Octopus.Client
package is a NuGet package containing an ILMerged singleOctopus.Client.dll
comprisingOctopus.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 theOctopus.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 inNewtonsoft.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.
Page updated on Tuesday, June 25, 2024