UA.XManager.Client 10.0.3

UA.XManager.Client

UA.XManager.Client is the thin .NET client for calling the hosted XManager API from another application.

Its current practical surface is centered on project-scoped Port requests. The package is a good fit when an application already has XManager credentials and wants to invoke existing XManager request pipelines, but it is not yet a full local SDK for every XManager module.

What It Is

UA.XManager.Client wraps three concerns behind one small entry point:

• Dependency injection registration through AddXManager.
• Token acquisition through the client-credentials flow.
• Request composition through fluent builders exposed by XManagerService.

The main service facade exposes four builder families:

• Datacenter
• Domain
• Identity
• Port

At the moment, Port is the only family with public request operations. Datacenter, Domain, and Identity are exposed as builders, but they currently behave as placeholders rather than full feature clients.

Mental Model

Treat UA.XManager.Client as a remote gateway into an already-hosted XManager environment.

You configure project and credential settings once, inject XManagerService, then compose a request against the builder that matches the API area. In today's implementation, that usually means a Port request identified by project and request name.

Features

Service registration

• AddXManager registers a singleton HttpClient.
• AddXManager also registers XManagerService as a scoped dependency.
• Configuration is read from the XManager section.

Fluent Port requests

• Port requests are project-scoped.
• The indexer syntax Port["requestName"] builds the request path for a specific request.
• Query-string helpers support paging and timeout values.
• Argument adds named JSON arguments to the outgoing request.
• Content switches the request body to multipart/form-data when file-like content is attached.

Authentication and transport

• The client acquires bearer tokens through Microsoft identity client credentials.
• Tokens are cached in static fields and reused until expiry.
• Requests target the hosted XManager API directly.

Shared contract model

• Serialization uses the shared XManager model assembly.
• Result payloads deserialize into Tenet Result wrappers rather than raw collections alone.
• The package gives consumers the same request and response model vocabulary as the server-side stack.

Installation

Install via the .NET CLI:

dotnet add package UA.XManager.Client

Or via Package Manager Console:

Install-Package UA.XManager.Client

Configuration

The package expects an XManager configuration section with these keys:

• XManager:ProjectId
• XManager:ClientId
• XManager:ClientSecret
• XManager:Scopes

Example:

{
	"XManager": {
		"ProjectId": "demo-project",
		"ClientId": "00000000-0000-0000-0000-000000000000",
		"ClientSecret": "<secret>",
		"Scopes": "api://409c954b-96cb-4dd4-bb68-4bdcaf732b34/.default"
	}
}

Scopes is currently read as a single string value, not as an array.

Implemented surface today

Quick Start

using UA.Tenet.Design;
using UA.XManager.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddXManager();

public sealed class OrdersGateway
{
		private readonly XManagerService _xmanager;

		public OrdersGateway(XManagerService xmanager)
		{
				_xmanager = xmanager;
		}

		public async Task<Result<ICollection<OrderDto>>> GetRecentAsync()
		{
				return await _xmanager.Port["orders"]
						.Argument("status", "open")
						.Page(1, 50)
						.Timeout(TimeSpan.FromSeconds(30))
						.Get<OrderDto>();
		}
}

That example matches the current real surface of the package: Port is the only builder with public execution methods.

Multipart request example

using UA.Tenet.Design;
using UA.XManager.Client;

public sealed class ImportGateway(XManagerService xmanager)
{
	public async Task<Result<ICollection<ImportRowDto>>> PreviewAsync(string path)
	{
		using FileStream file = File.OpenRead(path);

		return await xmanager.Port["orders-import"]
			.Argument("mode", "preview")
			.Argument("culture", "en")
			.Content("file", file)
			.Timeout(TimeSpan.FromSeconds(60))
			.Get<ImportRowDto>();
	}
}

That is the main copyable pattern when a hosted Port request expects both named arguments and file-like content.

Architecture

XManagerService facade

XManagerService is the single injected facade. It exposes builder roots for Datacenter, Domain, Identity, and Port so application code does not need to construct request builders directly.

Base request pipeline

All builders inherit from the same base pipeline, which is responsible for:

• bearer token acquisition
• request URI composition
• query-string assembly
• JSON body creation
• multipart body creation when content is attached

Port-first client surface

The Port builder is where the implemented public API lives today. It supports:

• selecting a named request
• adding arguments
• attaching multipart content
• paging
• timeout
• executing GET operations and deserializing results

Behavioral Notes

• Paging parameters are only appended when both page and pageSize are greater than zero.
• Timeout is sent as a query parameter in seconds.
• When multipart content is present, the body becomes multipart/form-data instead of JSON.
• GET responses deserialize into Result<ICollection<T>>.
• Exceptions during GET execution are converted into Result error outcomes instead of always escaping directly.

Boundaries And Caveats

• The base API URL is fixed in the client implementation; there is no public environment-specific base URL override today.
• Datacenter, Domain, and Identity builders are not feature-complete yet, so the package is effectively a Port client today.
• The token cache is static, which means token state is shared across client instances in the process.
• Scopes are read from configuration, but token acquisition currently uses a fixed resource scope path internally.
• The exposed public execution surface is limited. There are no broad CRUD methods across every builder yet.
• Some request-setup failures are collapsed into a NotFound-like outcome, which can obscure the original root cause.

When To Use It

• Use it when another .NET application needs to call an existing hosted XManager request pipeline.
• Use it when you want the shared XManager request and result contracts in the caller.
• Avoid it when you need a complete local SDK for every XManager module today.

Related Packages

• UA.XManager for shared contracts and model types.
• UA.XManager.Web for the hosted web application.

Documentation

For broader platform context, pair this guide with the XManager web application guide and the generated API reference for the client assembly.

• XManager web host guide: https://docs.uadevs.org/xmanager/web