NginxProxyManager.SDK 2.0.2

Nginx Proxy Manager SDK

A .NET SDK for interacting with the Nginx Proxy Manager API.

Features

• Client-based approach for easy access to all resources
• Fluent builder pattern for creating requests
• Comprehensive error handling with OperationResult pattern
• Automatic token management and refresh
• Broad support for Nginx Proxy Manager host, certificate, access-list, stream, user, setting, audit-log, report, and server-error endpoints
• Dependency injection support for ASP.NET Core applications

Installation

dotnet add package NginxProxyManager.SDK

Quick Start

using NginxProxyManager.SDK.Client;

// Create credentials
var credentials = AuthenticationCredentials.FromCredentials("admin@example.com", "your-password");

// Create a client
var client = new NginxProxyManagerClient("http://your-npm-instance:81", credentials);

// List all proxy hosts
var result = await client.ProxyHosts.GetAllAsync();
if (result.IsSuccess)
{
    foreach (var proxy in result.Result ?? Array.Empty<NginxProxyManager.SDK.Models.Proxies.ProxyHost>())
    {
        Console.WriteLine($"Proxy: {proxy.DomainNames[0]} -> {proxy.ForwardHost}:{proxy.ForwardPort}");
    }
}

Configuration

Using Dependency Injection

// In your Program.cs or Startup.cs
using NginxProxyManager.SDK.Client;

// Configure services
builder.Services.AddNginxProxyManager(options =>
{
    options.BaseUrl = "http://your-npm-instance:81";
    options.Credentials = AuthenticationCredentials.FromCredentials("admin@example.com", "your-password");
});

// In your controller or service
public class ProxyController : ControllerBase
{
    private readonly INginxProxyManagerClient _client;

    public ProxyController(INginxProxyManagerClient client)
    {
        _client = client;
    }

    public async Task<IActionResult> Index()
    {
        var result = await _client.ProxyHosts.GetAllAsync();
        if (result.IsSuccess)
        {
            return View(result.Result);
        }
        
        return BadRequest(result.Error);
    }
}

Using appsettings.json

{
  "NginxProxyManager": {
    "BaseUrl": "http://your-npm-instance:81",
    "TimeoutSeconds": 30,
    "Email": "admin@example.com",
    "Password": "your-password"
  }
}

Using Code

var config = new NPMConfiguration
{
    BaseUrl = "http://your-npm-instance:81",
    TimeoutSeconds = 30,
    Email = "admin@example.com",
    Password = "your-password"
};

services.AddNginxProxyManager(config);

Using Environment Variables

You can also configure the SDK using environment variables:

export NGINX_PROXY_MANAGER_BASE_URL="http://your-npm-instance:81"
export NGINX_PROXY_MANAGER_EMAIL="admin@example.com"
export NGINX_PROXY_MANAGER_PASSWORD="your-password"
export NGINX_PROXY_MANAGER_TIMEOUT_SECONDS="30"

Then in your code:

services.AddNginxProxyManager(); // Will use environment variables

Available Resources

The SDK provides access to the main Nginx Proxy Manager resources through the client:

// Create a client
var credentials = AuthenticationCredentials.FromCredentials("admin@example.com", "your-password");
var client = new NginxProxyManagerClient("http://your-npm-instance:81", credentials);

// Access resources
var proxyHosts = client.ProxyHosts;
var streams = client.Streams;
var certificates = client.Certificates;
var accessLists = client.AccessLists;
var serverErrors = client.ServerErrors;
var auditLogs = client.AuditLogs;
var reports = client.Reports;
var deadHosts = client.DeadHosts;
var users = client.Users;
var settings = client.Settings;

Builder Pattern

The SDK uses a fluent builder pattern for creating requests:

// Create a proxy host using the builder pattern
var result = await client.ProxyHosts.CreateBuilder()
    .WithDomainNames("example.com")
    .WithForwardHost("192.168.1.100")
    .WithForwardPort(8080)
    .WithSsl(true)
    .Build()
    .CreateAsync();

if (result.IsSuccess)
{
    Console.WriteLine($"Created proxy host with ID: {result.Result?.Id}");
}

Error Handling

The SDK uses the OperationResult<T> pattern for error handling:

var result = await client.ProxyHosts.CreateAsync(proxy);
if (result.IsSuccess)
{
    // Use the created item
    var item = result.Result;
}
else
{
    // Handle the error
    var error = result.Error;
    Console.WriteLine($"Error: {error?.Message}");
    
}

Documentation

For detailed documentation on each resource, see:

• Proxies - Manage proxy hosts
• Streams - Manage TCP/UDP streams
• Server Errors - View and manage server errors
• Certificates - Manage SSL certificates
• Access Lists - Manage access lists
• Audit Logs - View audit logs
• Reports - Generate reports
• Dead Hosts - Manage dead hosts
• Users - Manage NPM users
• Settings - Read and update NPM settings

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.