Honua.Sdk.Admin 1.13.1

Honua.Sdk.Admin

REST client for the Honua Admin API: service settings, metadata resources and manifests, secure database connections, published layers, styles, identity providers, RBAC, users, license, observability, deploy plans, alert rules, feature-event replay, and streaming subscriber operations. Also ships the portal-style Catalog client and the GeoServices-compatible Geocoding client.

Part of the Honua .NET SDK — see the repo README for the full package catalog, browser/WASM support, authentication, and release policy.

Install

Stable releases are on nuget.org and install anonymously. An unversioned add resolves to the newest stable release (the current SDK version is in the repo README). Prereleases stay on the authenticated GitHub Packages feed; see INSTALL.md.

dotnet add package Honua.Sdk.Admin

Quick usage

using Honua.Sdk.Admin;
using Honua.Sdk.Admin.Extensions;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddHonuaAdmin(o => o.BaseAddress = new Uri("https://your-honua-server"));
var provider = services.BuildServiceProvider();

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

var compatibility = await client.CheckCompatibilityAsync(cancellationToken);
var summaries = await client.ListServicesAsync(cancellationToken);
foreach (var service in summaries)
{
    var settings = await client.GetServiceSettingsAsync(service.ServiceName, cancellationToken);
    Console.WriteLine($"{service.ServiceName}: {string.Join(',', settings.EnabledProtocols)}");
}

For application code, prefer the narrow sub-interface that matches the workflow instead of depending on the aggregate IHonuaAdminClient. AddHonuaAdmin registers all sub-interfaces against the same underlying HonuaAdminClient.

using Honua.Sdk.Admin.Models;

var users = provider.GetRequiredService<IHonuaAdminUsersClient>();
var permissions = await users.GetEffectivePermissionsAsync(
    "user-operator",
    cancellationToken);

var alerts = provider.GetRequiredService<IHonuaAdminAlertsClient>();
var rules = await alerts.ListAlertRulesAsync(
    serviceId: "parcels",
    layerId: 1,
    cancellationToken);

var events = provider.GetRequiredService<IHonuaAdminFeatureEventsClient>();
var replay = await events.ReplayFeatureEventsAsync(
    new FeatureEventReplayQuery { Cursor = 1001, Limit = 100 },
    cancellationToken);

GeoServices/migration import lifecycle

Discover an ArcGIS service, queue a single-layer import, and wait for it to reach a terminal status without ever risking a duplicate import on retry:

using Honua.Sdk.Admin.Models;

var admin = provider.GetRequiredService<IHonuaAdminClient>();

var discovered = await admin.DiscoverGeoservicesServiceAsync(new GeoservicesDiscoverRequest
{
    ServiceUrl = "https://gis.example.com/arcgis/rest/services/Parcels/FeatureServer",
    Credentials = new GeoservicesCredentialDescriptor
    {
        Mode = "token",
        AccessTokenSecretReference = "secret://arcgis/token"
    }
});

var job = await admin.StartGeoservicesImportAsync(new GeoservicesStartImportRequest
{
    ServiceUrl = discovered.ServiceUrl,
    LayerId = discovered.Layers[0].Id,
    TableName = "parcels",
    TargetSrid = 4326,
    AutoPublish = true
});

// Reconnects to the job by polling status only; safe to call again after a
// client restart because it never re-invokes StartGeoservicesImportAsync.
var terminal = await admin.WaitForGeoservicesImportJobAsync(job.JobId);

if (terminal.Status is GeoservicesImportStatus.NeedsReview)
{
    var findings = terminal.ReconciliationArtifact!.Reasons;
    Console.WriteLine($"Import needs review: {string.Join("; ", findings)}");
}

Import several dependency-ordered layers as one resumable batch, and poll its rolled-up status plus per-child job ids:

var batch = await admin.StartMigrationBatchAsync(new MigrationBatchStartRequest
{
    SourceKind = "arcgis-geoservices-rest",
    Layers =
    [
        new MigrationBatchLayerSpec
        {
            SourceResourceId = "res:parcels",
            ServiceUrl = discovered.ServiceUrl,
            LayerId = 0,
            TableName = "parcels"
        },
        new MigrationBatchLayerSpec
        {
            SourceResourceId = "res:zoning",
            ServiceUrl = discovered.ServiceUrl,
            LayerId = 1,
            TableName = "zoning",
            DependsOn = ["res:parcels"]
        }
    ]
});

var status = await admin.GetMigrationBatchAsync(batch.BatchId);
foreach (var child in status.Children)
{
    Console.WriteLine($"{child.SourceResourceId}: {child.Status} (job {child.JobId})");
}

Independently, retrieve a migration run's signed reconciliation scorecard once the run (recorded separately by the migration engine) completes:

var scorecard = await admin.GetMigrationRunReconciliationScorecardAsync(runId);
Console.WriteLine($"Data reconciliation verdict: {scorecard.Verdict}");

Console control-plane contracts

The Admin package includes the stable Console P0 control-plane surface used by Blazor Web and MAUI hosts:

Most Admin endpoints use the server's ApiResponse<T> envelope and are unwrapped before returning typed SDK models. Table discovery returns raw TableDiscoveryResponse, and feature-event replay returns raw FeatureEventReplayResponse, because those current server endpoints are not envelope-wrapped. Admin requests are emitted as camelCase JSON, while response binding is case-insensitive so the server's current PascalCase replay payload (Events, NextCursor, HasMore, and event fields) binds to FeatureEventReplayResponse. Non-success HTTP statuses throw HonuaAdminApiException; successful responses that fail the expected contract throw HonuaAdminOperationException.

Catalog and Geocoding

using Honua.Sdk.Admin.Catalog;
using Honua.Sdk.Admin.Geocoding;

services.AddHonuaCatalog(o => o.BaseAddress = new Uri("https://your-honua-server"));
services.AddHonuaGeocoding(o => o.BaseAddress = new Uri("https://your-honua-server"));

var catalog = provider.GetRequiredService<IHonuaCatalogClient>();
var hits = await catalog.SearchAsync(
    new CatalogQueryOptions { Query = "parcels", Limit = 25 },
    cancellationToken);

var geocoder = provider.GetRequiredService<IHonuaGeocodingClient>();
var candidates = await geocoder.ForwardGeocodeAsync(
    "1600 Amphitheatre Pkwy, Mountain View, CA",
    options: null,
    cancellationToken);

Raster import (write/output)

IHonuaAdminRasterImportClient (part of IHonuaAdminClient) uploads a raster into PostGIS via the admin import endpoint. This is the write half of the raster geoprocessing round-trip; the read half is the read-only IHonuaRasterDataClient (ReadWindowAsync) in Honua.Sdk.GeoServices.

var admin = provider.GetRequiredService<IHonuaAdminClient>();

await using var tiff = File.OpenRead("output.tif");
var result = await admin.ImportRasterAsync(new RasterImportRequest
{
    Content = tiff,
    FileName = "output.tif",
    LayerId = 7,
    Name = "GP result",
    Srid = 4326,
}, cancellationToken);

var formats = await admin.GetSupportedRasterFormatsAsync(cancellationToken);

Server compatibility

IHonuaAdminClient.CheckCompatibilityAsync reports whether the connected Honua Server matches this SDK baseline. See compatibility.md for the policy and supported version matrix.

Documentation

• Quickstart
• Authentication
• Console client contracts
• Troubleshooting
• Metadata catalog parity

License

Apache 2.0

Publishing an editable layer

Set both the storage mode and capabilities when publishing a layer intended for edits. Leaving either option null omits it and preserves the server default.

var layer = await admin.PublishLayerAsync(connectionId, new PublishLayerRequest
{
    Schema = "public",
    Table = "parcels",
    LayerName = "Parcels",
    StorageMode = "managed",
    Capabilities = ["Query", "Create", "Update", "Delete"]
}, cancellationToken);

The server validates storage modes and capability combinations. Catalog discovery uses service and FeatureServer routes by default; groups, saved source descriptors and metadata-only filters require the legacy metadata-resource API and propagate server errors when unsupported.