Uno Kiota
Uno.Extensions.Http.Kiota turns a Kiota-generated API client into a service: AddKiotaClient<TClient> gives it an HttpClient from the host with the endpoint's base address, the platform's native handler, every DelegatingHandler the app registered (the authentication token handler among them) and Kiota's own middleware. The recommended template ships this setup. Generic agents write HttpClient calls by hand, hand-edit the generated code, or create the client with new; each of those loses the base address, the token and the retry behaviour. This skill routes you to the step.
Workflow
- A new app gets Kiota from the
uno-build-apptemplate command (-http kiotais the preset's default); add-serverfor a backend project, an OpenAPI document inSpecs/and a generated client inContent/Client:dotnet new unoapp -preset recommended -presentation mvux -theme simple -tests unit -server -o <AppName>. Without-serverthe app has the feature but no client. Then fix the template gaps listed in the critical rules. - Read
references/generate.mdto create or regenerate the client,references/register.mdto register it, andreferences/calling.mdto call it. Addreferences/content-types.mdwhen an operation sends or returns anything other thanapplication/json, andreferences/testing.mdfor the service tests that prove every operation. - Ground details in the official docs: call
uno_platform_docs_search(...), thenuno_platform_docs_fetch(sourcePath="…")with thesourcePathfrom a result (a relative.mdpath). Never pass a URL,.htmllink, or hand-built path. - The API's URL and its OpenAPI document are the developer's. Never invent them: use a placeholder and report the API as not configured.
Topic map
| Task | Read | Key APIs |
|---|---|---|
| Install the Kiota CLI, generate a client from a spec file or a running server, regenerate after an API change, limit the generated paths | references/generate.md |
kiota generate, kiota update, kiota-lock.json, --include-path |
| Register the client, its base URL per environment, the configuration section name, default headers and timeout, several APIs | references/register.md |
UseHttp, AddKiotaClient, EndpointOptions, configure |
| Call the API: request builders, path and query parameters, bodies, per-request headers, errors, retries, cancellation, feeding MVUX | references/calling.md |
GetAsync, QueryParameters, ApiException, RetryHandlerOption |
An operation with text/plain, form, multipart or application/problem+json content, or the expected a application/json content type exception |
references/content-types.md |
AddClient<TClient>, HttpClientRequestAdapter |
Service tests of every operation through the app's registration, against the server in-process; the template test's icuuc77 failure |
references/testing.md |
WebApplicationFactory, UseHttp, SkipIcuDataInitializerGenerator |
The access token on Kiota calls, refresh on 401, the No-Refresh header |
the uno-authentication skill (references/http.md) |
UseAuthentication, No-Refresh |
Critical rules
- Feature and namespace:
HttpKiotain<UnoFeatures>; it brings the Kiota runtime packages, so add none of the packageskiota infolists.AddKiotaClientis inUno.Extensions.Http.Kiota(the template'sGlobalUsings.cshasglobal using Uno.Extensions.Http.Kiota;), not inUno.Extensions. - Register inside
UseHttp, inject the client, nevernewit.services.AddKiotaClient<TClient>(context, ...)inside.UseHttp((context, services) => ...), then takeTClientin the service or Model constructor. A client built from your ownHttpClientor request adapter gets no base address, no native handler and no token. - Generated code is regenerated, not edited. Change the OpenAPI document, then
kiota updatefrom the client's folder (references/generate.md). Put app logic in a service that wraps the client. - Every environment needs the Url. Without a base address the generated client silently calls the first
serversURL of the OpenAPI document; the template's ishttps://localhost:5002. The template readsApiClient:Url, which onlyappsettings.development.jsonsets, so a Release build (Production environment) calls localhost. Set the production Url inappsettings.json, or a host the build configuration chooses. - Pass the Url as
options, the way the template does. In trimmed Release builds (iOS, Android), an endpoint section bound byAddKiotaClientloses itsUrl(unoplatform/uno.extensions#3266);options: new EndpointOptions { Url = context.Configuration["ApiClient:Url"] }reads the value directly and survives trimming. PassingoptionsmakesAddKiotaClientignore the section's other keys. - Only JSON is parsed or serialized.
AddKiotaClientregisters only Kiota's JSON factories (unoplatform/uno.extensions#2799). Atext/plainresponse, a form or multipart body, and anapplication/problem+jsonerror body (ASP.NET Core'sResults.Problem,ValidationProblem) all throwArgumentOutOfRangeException: expected a application/json content type, which hides the API's status code.references/content-types.mdhas the registration that keeps every serializer. - Errors are exceptions. A status the spec maps to an error schema throws that generated model (it derives from
ApiException); any other non-success status throwsMicrosoft.Kiota.Abstractions.ApiExceptionwith the code inResponseStatusCode. Kiota retries a 503 (also 429 and 504) three more times before throwing, about 21 s without aRetry-Afterheader; turn it off per request withRetryHandlerOption { MaxRetry = 0 }for calls that must not run twice. - Template gaps: the endpoint Url is missing outside Development (above),
WeatherCacheround-trips the Kiota models throughISerializerto get an immutable list (.ToImmutableList()is enough), and a-serverapp also gets an unused RefitServices/Endpoints/IApiClient.csand a<AppName>.DataContractsproject for the weather records. With a Kiota client the OpenAPI document is the shared contract: when you replace the sample API, deleteIApiClient.cs,Services/Caching, the DataContracts project with its references,global usinglines andAddJsonTypeInfo(...)call, and keepUseSerialization.
Verified against Uno.Extensions 8.0.0-dev.150 (pinned by Uno.Sdk 7.0.0-dev.115, with Microsoft.Kiota.* 1.22.2), Uno.Templates 7.0.0-dev.120, and clients generated by Kiota 1.16 (the template's) and 1.37. The Uno.Samples UI/Http.KiotaExtensionsDemo was built from this skill: a design-first contract (Specs/TasksApi.yaml) with every content type above, the registration from references/content-types.md, and service tests of every operation. On other versions, check the template output and the docs.
Related skills
uno-authenticationfor sign-in and the token the HTTP handler adds to Kiota calls.uno-mvuxfor the feeds and states that load data through the client.uno-testingto exercise the running app against the API.