WebRateProviderOptions Class
Definition
- Namespace
- Bodu.Financial.ExchangeRates
- Assembly
- Bodu.Financial.ExchangeRates.dll
- Package
- Bodu.Financial.ExchangeRates 1.3.0
Provides the configuration common to every web exchange-rate source, the pair-based sources and the Bank of England, ECB, RBA and IMF feeds alike: the endpoint base address, the HTTP contract (user agent, timeout and response-size cap), the synchronous-access, look-back and refresh behavior, the advertised history, the currency-alias map, and the per-concern diagnostic log levels. A concrete source derives from this type to add its own endpoint members and validation.
public abstract class WebRateProviderOptions
- Inheritance
-
WebRateProviderOptions
- Derived
- Inherited Members
- Extension Methods
Remarks
Every shared member carries a working default so the options bind cleanly through
Microsoft.Extensions.Options and require no configuration for the common case. A derived type sets
BaseAddress in its constructor - the base leaves it unset because the host differs per source - and
overrides TryValidateCore(out string?) to add its own invariants.
The *LogLevel members set the LogLevel at which each diagnostic the provider emits is logged,
so consumers can re-tune verbosity per concern without category-wide log filters. Set any of them to
None to suppress that event entirely.
using Bodu.Financial.ExchangeRates;
// Concrete options types (YahooRateProviderOptions, OfxRateProviderOptions, ...) share this surface.
var options = new YahooRateProviderOptions
{
HttpTimeout = TimeSpan.FromSeconds(10),
AllowSynchronousNetworkAccess = false, // force callers onto the asynchronous surface
DefaultLookback = TimeSpan.FromDays(14), // window used by the timeless lookup surface
};
options.CurrencyAliases["CNY"] = "CNH"; // request the source's CNH symbol wherever CNY is asked for
if (!options.TryValidate(out string? error))
throw new InvalidOperationException(error);
Constructors
WebRateProviderOptions()
protected WebRateProviderOptions()
Properties
AllowSynchronousNetworkAccess
Gets or sets a value indicating whether a synchronous lookup may block to fetch a missing pair on demand.
public bool AllowSynchronousNetworkAccess { get; set; }
Property Value
- bool
true to allow synchronous, blocking fetches from IDatedRateProvider lookups; false to serve only already-loaded data. Defaults to false.
Remarks
Blocking on network I/O from a synchronous method can deadlock in environments with a single-threaded synchronization context (classic ASP.NET, WPF, WinForms), so the default is snapshot-only. Leave this false and warm the store at startup; set it to true only to opt in to a blocking on-demand fetch from the synchronous lookup path.
BaseAddress
Gets or sets the base address of the source's API host. Should end with a trailing slash so relative paths resolve as expected.
public Uri BaseAddress { get; set; }
Property Value
- Uri
The base address; set by the derived source's constructor.
CurrencyAliases
Gets or sets the map between ISO 4217 codes and the currency symbols or labels the source uses where the two differ. Codes and labels absent from the map pass through unchanged.
public IDictionary<string, string> CurrencyAliases { get; set; }
Property Value
- IDictionary<string, string>
The alias map; defaults to an empty map.
Remarks
A source that names currencies in its requests, as the pair-based sources do, maps the ISO code (the key) to the symbol component it sends (the value) while building a request. A source that publishes a table naming its currencies, as the Bank of England, ECB and RBA feeds do, maps the label it publishes (the key) to the ISO code it is served under (the value) while reading the response. The derived options type states which applies. Every value must be a non-empty run of ASCII letters and digits; TryValidate(out string?) rejects any other.
DefaultLookback
Gets or sets the look-back window used when a synchronous, undated, or asynchronous single-date lookup must fetch on demand. The provider fetches the window ending on the requested date and spanning this duration, in whole days; a source that publishes whole files fetches every file the window reaches.
public TimeSpan DefaultLookback { get; set; }
Property Value
- TimeSpan
The look-back window; defaults to 7 days.
DownloadCompletedLogLevel
Gets or sets the level at which a completed pair download (with its observation count) is logged.
public LogLevel DownloadCompletedLogLevel { get; set; }
Property Value
- LogLevel
The log level; defaults to Information.
DownloadFailedLogLevel
Gets or sets the level at which a failed pair download is logged.
public LogLevel DownloadFailedLogLevel { get; set; }
Property Value
DownloadStartingLogLevel
Gets or sets the level at which the start of a pair download is logged.
public LogLevel DownloadStartingLogLevel { get; set; }
Property Value
HistoryAvailability
Gets or sets the history depth the provider advertises: how far back it can serve rates. A caller can consult it before requesting an old date.
public RateHistoryAvailability HistoryAvailability { get; set; }
Property Value
- RateHistoryAvailability
The advertised availability; defaults to Unbounded. A source whose feed publishes only the recent past sets a rolling window in its constructor.
HttpTimeout
Gets or sets the HTTP request timeout, applied to the client a provider builds for itself and to the client the dependency-injection registration configures.
public TimeSpan HttpTimeout { get; set; }
Property Value
- TimeSpan
The HTTP timeout; defaults to 30 seconds.
MaxResponseContentBufferSize
Gets or sets the maximum number of response bytes a provider-owned HttpClient buffers, bounding the memory a single response can consume.
public long MaxResponseContentBufferSize { get; set; }
Property Value
- long
The response buffer cap, in bytes; defaults to DefaultMaxResponseContentBufferSize (64 MiB).
Remarks
This value is applied when the provider creates and owns its own HttpClient, and to the named
client that a provider's dependency-injection registration (such as AddEcbExchangeRates) configures. When
a client is passed to the provider's constructor directly, bounding its response size is the caller's
responsibility and this value is not applied.
ObservationIngestedLogLevel
Gets or sets the level at which each individual ingested rate observation is logged.
public LogLevel ObservationIngestedLogLevel { get; set; }
Property Value
RefreshInterval
Gets or sets how long a load serves a request for a day the source could still publish before that day is downloaded again.
public TimeSpan RefreshInterval { get; set; }
Property Value
- TimeSpan
The refresh interval; defaults to 12 hours.
Remarks
A day of a load is final once it has passed (any day before the UTC date on which it was downloaded) or once the source has returned a rate for it, and a final day is never downloaded again. The other days of a load, today and any later day the source returned no rate for, are open: they are served for this interval, and the next request that reaches one of them after the interval has passed downloads it again, so a rate the source publishes later the same day is picked up. A source may apply the interval to more than its in-memory loads; the derived options type says where. The interval must be greater than zero; TryValidate(out string?) rejects any other value.
SynchronousNetworkFetchLogLevel
Gets or sets the level at which a synchronous, blocking on-demand network fetch is logged.
public LogLevel SynchronousNetworkFetchLogLevel { get; set; }
Property Value
UserAgent
Gets or sets the User-Agent header applied to the HTTP client.
public string UserAgent { get; set; }
Property Value
- string
The user-agent string; defaults to a browser-like identifier, because the public exchange-rate endpoints these options address commonly reject requests that do not present a recognizable user agent.
Remarks
This value is applied when the provider creates and owns its own HttpClient and by the dependency-injection registration when it configures the named client. When an HttpClient is supplied to the provider directly, configuring its headers is the caller's responsibility and this value is not applied.
Methods
MapCurrency(string)
Maps an ISO code through CurrencyAliases, returning the code unchanged when no alias exists.
protected string MapCurrency(string isoCode)
Parameters
isoCodestringThe ISO code to map.
Returns
- string
The aliased symbol component, or
isoCodewhen unmapped.
TryValidate(out string?)
Attempts to validate the options without throwing, reporting the first invariant that is violated.
public bool TryValidate(out string? error)
Parameters
errorstringWhen this method returns false, a message describing the first violated invariant; otherwise null.
Returns
Remarks
The shared invariants are checked first, then TryValidateCore(out string?) is consulted for source-specific
invariants. The throwing Validate() method is expressed in terms of this method, and the
dependency-injection registration wires it into ValidateOnStart so misconfiguration fails fast at
application startup.
TryValidateCore(out string?)
Validates the source-specific invariants. The default implementation reports success; a derived type overrides it to validate its own members and is invoked only after the shared invariants hold.
protected virtual bool TryValidateCore(out string? error)
Parameters
errorstringWhen this method returns false, a message describing the violated invariant; otherwise null.
Returns
Validate()
Validates the options, throwing when a required value is missing or an invariant is violated.
public void Validate()
Exceptions
- ArgumentException
Thrown when an invariant is violated.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |