HetznerCloud 1.0.0

HetznerCloud .NET

A comprehensive, production-ready .NET client library for the Hetzner Cloud API, modeled after the official hcloud-go and hcloud-python libraries.

Features

• 18 Resource Clients — Full coverage of Hetzner Cloud API endpoints including Primary IPs, DNS Zones, and Storage Boxes
• Strongly-Typed Models — All request/response models with System.Text.Json serialization
• Async/Await — Fully asynchronous API with CancellationToken support
• Dependency Injection — Built-in services.AddHetznerCloud() registration
• Resilience — Automatic retry with exponential backoff, circuit breakers, and hedging via Polly
• Rate Limiting — Automatic detection and retry-after handling
• Pagination — Built-in support for all list operations with metadata
• Action Polling — WaitForAsync / WaitForAllAsync for long-running operations
• Error Handling — Typed exception hierarchy (NotFoundException, ValidationException, RateLimitExceededException, etc.)
• Fluent Builders — Type-safe builders for complex resource creation
• OpenTelemetry — Built-in metrics and distributed tracing
• Branded IDs — Compile-time safe ID types (ServerId, VolumeId, PrimaryIpId, etc.)

Installation

dotnet add package HetznerCloud

Quick Start

using HetznerCloud;
using HetznerCloud.Models;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddHetznerCloud("your-api-token");
var provider = services.BuildServiceProvider();

var client = provider.GetRequiredService<HetznerCloudClient>();

// List all servers
var servers = await client.Servers.GetAllAsync();
foreach (var server in servers.Servers)
    Console.WriteLine($"{server.Name} — {server.Status}");

// Create a server
var create = await client.Servers.CreateAsync(new ServerCreateRequest
{
    Name = "my-server",
    ServerType = "cpx22",
    Image = "ubuntu-24.04",
    Location = "fsn1",
    StartAfterCreate = true,
    Labels = new() { ["env"] = "production" }
});

await client.Servers.WaitForActionAsync(create.Action.Id);

Configuration

services.AddHetznerCloud(options =>
{
    options.ApiToken = Environment.GetEnvironmentVariable("HCLOUD_TOKEN")!;
    options.ApplicationName = "my-app";
    options.ApplicationVersion = "1.0.0";
    options.Timeout = TimeSpan.FromSeconds(100);
    options.MaxRetries = 3;
    options.RetryDelay = TimeSpan.FromSeconds(1);
    options.ThrowOnError = true; // throw exceptions on API errors (default: true)
});

API Reference

Servers

Primary IPs

DNS Zones

Storage Boxes

Load Balancers

HTTP Services support idle_timeout (30–300 seconds), sticky sessions, redirect, and certificate configuration.

Networks

Floating IPs

Firewalls

Other Resources

Waiting for Actions

// Single action
var action = await client.Actions.WaitForAsync(actionId);

// Multiple actions
await client.Actions.WaitForAllAsync(new[] { action1.Id, action2.Id, action3.Id });

// Via server client
await client.Servers.WaitForActionAsync(createResponse.Action.Id);

Pagination

var response = await client.Servers.GetAllAsync(new ServerListOptions
{
    Page = 1,
    PerPage = 50,
    Sort = "created:desc",
    LabelSelector = "env=production"
});

Console.WriteLine($"Page {response.Meta.Pagination.Page} / {response.Meta.Pagination.LastPage}");
Console.WriteLine($"Total: {response.Meta.Pagination.TotalEntries}");

Error Handling

try
{
    var server = await client.Servers.GetByIdAsync(999999);
}
catch (NotFoundException ex)
{
    Console.WriteLine($"Not found: {ex.Message}");
}
catch (UnauthorizedException)
{
    Console.WriteLine("Invalid API token");
}
catch (ValidationException ex)
{
    foreach (var error in ex.ValidationErrors)
        Console.WriteLine($"  {error.Field}: {error.Message}");
}
catch (RateLimitExceededException ex)
{
    Console.WriteLine($"Rate limited. Retry after: {ex.RetryAfter}");
}
catch (ConflictException ex)
{
    Console.WriteLine($"Conflict: {ex.Message}");
}
catch (HetznerCloudException ex)
{
    Console.WriteLine($"API error ({(int)ex.StatusCode}): {ex.Message}");
}

Fluent Builders

var request = ServerCreateBuilder.Create()
    .WithName("web-server")
    .WithServerType("cpx31")
    .WithImage("ubuntu-24.04")
    .WithLocation("fsn1")
    .WithLabels(b => b.Add("env", "production"))
    .Build();

OpenTelemetry

services.AddHetznerCloud("token");
services.AddOpenTelemetry()
    .WithTracing(b => b.AddSource("HetznerCloud"));

Exception Hierarchy

HetznerCloudException
├── NotFoundException (404)
├── UnauthorizedException (401)
├── ForbiddenException (403)
├── ValidationException (422)
├── ConflictException (409)
├── RateLimitExceededException (429)
├── ServerErrorException (500)
└── ServiceUnavailableException (503)

Requirements

• .NET 8.0 or .NET 9.0
• A Hetzner Cloud API token

License

MIT

Contributing

See CONTRIBUTING.md for guidelines.

Related Projects

• hcloud-go — Official Go library
• hcloud-python — Official Python library
• Hetzner Cloud API Docs
• API Changelog