Class TcgDexOptions
- Namespace
- TcgDex
- Assembly
- TcgDex.CSharpSdk.dll
Configuration for the TCGdex client.
public sealed class TcgDexOptionsInheritance
Inherited Members
Properties
BaseAddress
The API root, without the language segment. Defaults to the official host.
public Uri BaseAddress { get; set; }Property Value
Remarks
Overridable so callers can target a mirror or a local test server. The trailing slash matters — it is what makes the language and resource segments append rather than replace the path.
DeserializePricing
Whether TcgDex.Models.Card.Pricing is populated. Defaults to true.
public bool DeserializePricing { get; set; }Property Value
Remarks
The pricing block is the most expensive part of a card to
deserialize — measured at 4.7 µs and 2.2 KB of a 23 µs card,
roughly a fifth of both — and it is paid whether or not anything reads
it. The API has no way to ask for a card without it: every field-
selection form tried against the live service returned the identical
2,940 bytes, so this cannot be saved on the wire, only in the parse.
Set to false in an application that never reads prices. The property is dropped from the deserialization contract, so System.Text.Json skips the block as an unknown field rather than building it and discarding it.
It defaults to on, and the reason is not performance. With it off,
card.Pricing is null for every card — which is
indistinguishable from a card the API genuinely has no prices for. That
turns a configuration choice into a silently wrong answer, so it is opt
out rather than opt in. Against a network round trip of 20–50 ms the
4.7 µs is around 0.02% of a request; turn it off because the data is
unwanted, not because it is slow.
GraphQlEndpoint
The GraphQL endpoint, used only by the opt-in projection and nested-fetch paths.
public Uri GraphQlEndpoint { get; set; }Property Value
Remarks
Deliberately separate from TcgDex.TcgDexOptions.BaseAddress: GraphQL lives outside the language segment because it has no language support at all.
Language
The language segment used for every request. Defaults to English. See TcgDex.TcgDexLanguages for the accepted values.
public string Language { get; set; }Property Value
MaxDeserializedCacheEntries
How many deserialized responses to retain so a repeat fetch can skip the parse. Defaults to 64. Set to zero to disable.
public int MaxDeserializedCacheEntries { get; set; }Property Value
Remarks
Deserialization is roughly 86% of the in-process cost of a request, and
the response cache does not avoid it — that cache stores bytes, because
it sits on the System.Net.Http.HttpMessageHandler pipeline
where ETag revalidation is possible and one implementation covers
every endpoint. A cache hit therefore re-parsed the same bytes into the
same object every time. This layer stops that.
Entries are validated by ETag, not by a lifetime of their
own. A stored model is reused only when the response carries the
exact ETag it was built from — whether that header came from the
server or from the byte cache replaying it. So a typed entry cannot be
staler than the bytes underneath it, and there is no second expiry policy
to keep in step with the first. A response without an ETag is
never served from here.
Callers share one instance. Two fetches of an unchanged resource
now return the same object rather than two equal ones. The models are
records with init-only properties, so this is safe for anything
the type system allows; a caller who casts an
System.Collections.Generic.IReadOnlyList`1 property back to System.Collections.Generic.List`1 and
mutates it would corrupt the entry for everyone. Set this to zero if that
is a risk your codebase cannot rule out.
The bound is a count, and deserialized objects are several times the size of the bytes they came from — the unpaginated card list is 2.3 MB on the wire and roughly 8 MB once parsed. 64 is deliberately far below the response cache's 512 for that reason.
MaxResponseBytes
The largest response body the client will buffer, in bytes. Defaults to 32 MiB. Set to zero to remove the limit.
public long MaxResponseBytes { get; set; }Property Value
Remarks
A response is read into memory before it is deserialized, so without a ceiling the peak memory of a request is whatever the server chooses to send. Compression makes that worse rather than better: a few kilobytes of hostile gzip can expand to gigabytes, and the expansion happens in the handler below this one, so the limit is applied to the *decompressed* bytes where it actually protects anything.
The default is generous on purpose. The largest response the API produces is the unpaginated card list at roughly 2.4 MB, so 32 MiB leaves an order of magnitude of headroom while still bounding memory. Raise it if you target a mirror that serves something larger.
Timeout
How long one request may take, headers and body together. Defaults to 30 seconds. Use System.Threading.Timeout.InfiniteTimeSpan to remove the limit.
public TimeSpan Timeout { get; set; }Property Value
Remarks
Without this the ceiling is System.Net.Http.HttpClient's own default of 100 seconds — a value nobody chose, which leaves a caller blocked for over a minute and a half on an endpoint that has stopped answering. The live API returns its largest response, the 2.3 MB unpaginated card list, in well under a second, so 30 seconds is around forty times the observed worst case and still well clear of a slow mobile connection.
Applied through a linked System.Threading.CancellationTokenSource rather than System.Net.Http.HttpClient.Timeout. Callers may supply their own System.Net.Http.HttpClient and share it with the rest of their application, so setting a property on it would reach outside this SDK — and System.Net.Http.HttpClient throws if a request has already been sent on it. The linked source also spans the body read, which System.Net.Http.HttpClient.Timeout would cover but a timeout scoped to sending alone would not: the transport reads headers first and streams the body afterwards.
An expiry becomes TcgDex.TcgDexApiException, in keeping with the single error contract. Cancellation the *caller* requested stays an System.OperationCanceledException, because that is theirs to observe rather than a fault to report.
Methods
Validate()
Throws when the options cannot produce valid requests.
public void Validate()Remarks
Validating up front turns a typo'd language into an immediate, readable failure rather than a 404 on the first call that looks like a missing card.
Exceptions
- ArgumentException
-
The language is not one the API accepts, or the base address is not absolute.