Generators
A generator is the tool that turns a document into client code. Chirograph runs one of two, chosen per client with Generator. Neither
is a Roslyn source generator: each is a .NET tool that runs as a process during the build. See
How generation runs.
| Kiota | Refitter | |
|---|---|---|
| What it writes | A client class, <ClientName>, with request builders and models |
A Refit interface, I<ClientName>, and its contracts |
| A call looks like | await client.Rockets[id].GetAsync() |
await client.GetRocket(id) |
| Package added | Microsoft.Kiota.Bundle, and Microsoft.Extensions.Http |
Refit.HttpClientFactory |
| Without a base address | Uses the first server of the document | Needs one |
| Tool package | Microsoft.OpenApi.Kiota |
Refitter |
Choose Kiota for a large API, or one whose shape changes often: its request builders follow the paths. Choose Refitter for a smaller API where one method per operation reads better, or when you already use Refit.
The packages added to the project
Section titled “The packages added to the project”The generated code needs a runtime library, which Chirograph adds as an implicit PackageReference when at least one client uses the
generator:
- Kiota:
Microsoft.Kiota.Bundle, andMicrosoft.Extensions.Httpfor the registration. A project that also has a Refitter client doesn’t getMicrosoft.Extensions.Http:Refit.HttpClientFactorybrings it, possibly at a newer version than the one Chirograph was packed with, and adding the older one would be a downgrade (NU1605). - Refitter:
Refit.HttpClientFactory, which brings Refit, its source generator andMicrosoft.Extensions.Http. Authentication="Azure"on any client:Azure.Identity.Authentication="ClientCredentials"on any client:Duende.AccessTokenManagement4.x, which bringsMicrosoft.Extensions.Http(so a Kiota client’s isn’t added) andMicrosoft.Extensions.Http.Resilience(so the registration’s resilience block is written too, off unlessResilienceistrueor an object of its settings).
A package the project references itself wins: its own PackageReference and its version are left alone, and Chirograph adds nothing.
So reference a package yourself to choose its version, or set the matching property.
What Chirograph passes
Section titled “What Chirograph passes”Kiota runs as:
kiota generate --language CSharp --openapi <document> --class-name <ClientName> --namespace-name <Namespace> \ --output <client folder>/generated --clean-output --exclude-backward-compatible --log-level Warning <Options>Refitter runs with a settings file Chirograph writes, <ClientName>.refitter, which sets the document, the namespace, the interface
name (useOpenApiTitle off) and cancellation tokens on every method:
refitter --settings-file <client folder>/<ClientName>.refitter --output <client folder>/generated/<ClientName>.cs \ --no-logging --no-banner --simple-output <Options>Options goes last, so you can add to what Chirograph passes. Don’t change the output, the class or interface name or the namespace
there: the registration expects them.
Versions
Section titled “Versions”Each Chirograph release is packed with a version of each tool and of each package it adds. Set ChirographKiotaVersion or
ChirographRefitterVersion to run another version of a tool; the properties list them all. A different
tool version generates every client of that generator again.