Class ConfigurationBuilder

A standard Builder pattern for constructing a Configuration instance.

Inheritance
object
ConfigurationBuilder
Inherited Members
Namespace: LaunchDarkly.EventSource
Assembly: LaunchDarkly.EventSource.dll
Syntax
public class ConfigurationBuilder
Remarks

Initialize a builder by calling new ConfigurationBuilder(uri) or Configuration.Builder(uri). The URI is always required; all other properties are set to defaults. Use the builder's setter methods to modify any desired properties; setter methods can be chained. Then call Build() to construct the final immutable Configuration.

All setter methods will throw ArgumentException if called with an invalid value, so it is never possible for Build() to fail.

Methods

BackoffResetThreshold(TimeSpan)

Sets the amount of time a connection must stay open before the EventSource resets its backoff delay.

Declaration
public ConfigurationBuilder BackoffResetThreshold(TimeSpan backoffResetThreshold)
Parameters
Type Name Description
TimeSpan backoffResetThreshold

the threshold time
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

If a connection fails before the threshold has elapsed, the delay before reconnecting will be greater than the last delay; if it fails after the threshold, the delay will start over at the initial minimum value. This prevents long delays from occurring on connections that are only rarely restarted.

The default value is DefaultBackoffResetThreshold. Negative values are changed to zero.

Build()

Constructs a Configuration instance based on the current builder properies.

Declaration
public Configuration Build()
Returns
Type Description
Configuration

the configuration

ConnectionTimeout(TimeSpan)

Obsolete name for ResponseStartTimeout(TimeSpan).

Declaration
[Obsolete("Use ResponseStartTimeout")]
public ConfigurationBuilder ConnectionTimeout(TimeSpan responseStartTimeout)
Parameters
Type Name Description
TimeSpan responseStartTimeout

the timeout
Returns
Type Description
ConfigurationBuilder

the builder

HttpClient(HttpClient)

Specifies that EventSource should use a specific HttpClient instance for HTTP requests.

Declaration
public ConfigurationBuilder HttpClient(HttpClient client)
Parameters
Type Name Description
HttpClient client

an HttpClient instance, or null to use the default behavior
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

Normally, EventSource creates its own HttpClient and disposes of it when you dispose of the EventSource. If you provide your own HttpClient using this method, you are responsible for managing the HttpClient's lifecycle-- EventSource will not dispose of it.

EventSource will not modify this client's properties, so if you call HttpMessageHandler(HttpMessageHandler) or ConnectionTimeout(TimeSpan), those methods will be ignored.

HttpMessageHandler(HttpMessageHandler)

Sets the HttpMessageHandler that will be used for the HTTP client, or null for the default handler.

Declaration
public ConfigurationBuilder HttpMessageHandler(HttpMessageHandler handler)
Parameters
Type Name Description
HttpMessageHandler handler

the message handler implementation
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

If you have specified a custom HTTP client instance with HttpClient(HttpClient), then HttpMessageHandler(HttpMessageHandler) is ignored.

HttpRequestModifier(Action<HttpRequestMessage>)

Sets a delegate hook invoked before an HTTP request is performed. This may be useful if you want to modify some properties of the request that EventSource doesn't already have an option for.

Declaration
public ConfigurationBuilder HttpRequestModifier(Action<HttpRequestMessage> httpRequestModifier)
Parameters
Type Name Description
Action<HttpRequestMessage> httpRequestModifier

code that will be called with the request before it is sent
Returns
Type Description
ConfigurationBuilder

the builder

InitialRetryDelay(TimeSpan)

Sets the initial amount of time to wait before attempting to reconnect to the EventSource API.

Declaration
public ConfigurationBuilder InitialRetryDelay(TimeSpan initialRetryDelay)
Parameters
Type Name Description
TimeSpan initialRetryDelay

the initial retry delay
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

If the connection fails more than once, the retry delay will increase from this value using a backoff algorithm.

The default value is DefaultInitialRetryDelay. Negative values are changed to zero.

The actual duration of each delay will vary slightly because there is a random jitter factor to avoid clients all reconnecting at once.

See Also

LastEventId(string)

Sets the last event identifier.

Declaration
public ConfigurationBuilder LastEventId(string lastEventId)
Parameters
Type Name Description
string lastEventId

the event identifier
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

Setting this value will cause EventSource to add a "Last-Event-ID" header in its HTTP request. This normally corresponds to the LastEventId field of a previously received event.

LogAdapter(ILogAdapter)

Sets the logging implementation to be used for all EventSource log output.

Declaration
public ConfigurationBuilder LogAdapter(ILogAdapter logAdapter)
Parameters
Type Name Description
ILogAdapter logAdapter

a LaunchDarkly.Logging.ILogAdapter
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

This uses the ILogAdapter abstraction from the LaunchDarkly.Logging library, which provides several basic implementations such as Logs.ToConsole and an integration with the .NET Core logging framework. For more about this and about adapters to other logging frameworks, see LaunchDarkly.Logging.

LaunchDarkly.Logging defines logging levels of Debug, Info, Warn, and Error. If you do not want detailed Debug-level logging, use the Level() modifier to set a minimum level of Info or above, as shown in the code example (unless you are using an adapter to another logging framework that has its own way of doing log filtering).

Log messages will use DefaultLoggerName as the logger name. If you want to specify a different logger name, use Logger(Logger).

If you don't specify LogAdapter(ILogAdapter) or Logger(Logger), EventSource will not do any logging.

Examples

using LaunchDarkly.Logging;

// Send log output to the console (standard error), suppressing Debug messages var config = new ConfigurationBuilder(uri). LogAdapter(Logs.ToConsole.Level(LogLevel.Info)). Build();

Logger(Logger)

Sets a custom logger to be used for all EventSource log output.

Declaration
public ConfigurationBuilder Logger(Logger logger)
Parameters
Type Name Description
Logger logger

a LaunchDarkly.Logging.Logger instance
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

This uses the Logger type from the LaunchDarkly.Logging library, which provides several basic implementations such as Logs.ToConsole and an integration with the .NET Core logging framework. For more about this and about adapters to other logging frameworks, see LaunchDarkly.Logging.

If you don't specify LogAdapter(ILogAdapter) or Logger(Logger), EventSource will not do any logging.

Examples

using LaunchDarkly.Logging;

// Define a logger that sends output to the console (standard output), suppressing // Debug messages, and using a logger name of "EventStream" var logger = Logs.ToConsole.Level(LogLevel.Info).Logger("EventStream"); var config = new ConfigurationBuilder(uri). Logger(logger). Build();

MaxRetryDelay(TimeSpan)

Sets the maximum amount of time to wait before attempting to reconnect.

Declaration
public ConfigurationBuilder MaxRetryDelay(TimeSpan maxRetryDelay)
Parameters
Type Name Description
TimeSpan maxRetryDelay

the maximum retry delay
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

EventSource uses an exponential backoff algorithm (with random jitter) so that the delay between reconnections starts at InitialRetryDelay(TimeSpan) but increases with each subsequent attempt. MaxRetryDelay sets a limit on how long the delay can be.

The default value is DefaultMaxRetryDelay. Negative values are changed to zero.

See Also

Method(HttpMethod)

Sets the HTTP method that will be used when connecting to the EventSource API.

Declaration
public ConfigurationBuilder Method(HttpMethod method)
Parameters
Type Name Description
HttpMethod method
Returns
Type Description
ConfigurationBuilder
Remarks

By default, this is Get.

PreferDataAsUtf8Bytes(bool)

Specifies whether to use UTF-8 byte arrays internally if possible when reading the stream.

Declaration
public ConfigurationBuilder PreferDataAsUtf8Bytes(bool preferDataAsUtf8Bytes)
Parameters
Type Name Description
bool preferDataAsUtf8Bytes

true if you intend to request the event data as UTF-8 bytes
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

As described in MessageEvent, in some applications it may be preferable to store and process event data as UTF-8 byte arrays rather than strings. By default, EventSource will use the string type when processing the event stream; if you then use DataUtf8Bytes to get the data, it will be converted to a byte array as needed. However, if you set PreferDataAsUtf8Bytes to true, the event data will be stored internally as a UTF-8 byte array so that if you read DataUtf8Bytes, you will get the same array with no extra copying or conversion. Therefore, for greatest efficiency you should set this to true if you intend to process the data as UTF-8. Note that Server-Sent Event streams always use UTF-8 encoding, as required by the SSE specification.

ReadTimeout(TimeSpan)

Sets the timeout when reading from the EventSource API.

Declaration
public ConfigurationBuilder ReadTimeout(TimeSpan readTimeout)
Parameters
Type Name Description
TimeSpan readTimeout
Returns
Type Description
ConfigurationBuilder
Remarks

The connection will be automatically dropped and restarted if the server sends no data within this interval. This prevents keeping a stale connection that may no longer be working. It is common for SSE servers to send a simple comment line (":") as a heartbeat to prevent timeouts.

The default value is DefaultReadTimeout.

RequestBody(string, string)

Equivalent RequestBodyFactory(Func<HttpContent>), but for content that is a simple string.

Declaration
public ConfigurationBuilder RequestBody(string bodyString, string contentType)
Parameters
Type Name Description
string bodyString

the content
string contentType

the Content-Type header
Returns
Type Description
ConfigurationBuilder

the builder

RequestBodyFactory(Func<HttpContent>)

Sets a factory for HTTP request body content, if the HTTP method is one that allows a request body.

Declaration
public ConfigurationBuilder RequestBodyFactory(Func<HttpContent> factory)
Parameters
Type Name Description
Func<HttpContent> factory

the factory function, or null for none
Returns
Type Description
ConfigurationBuilder

the builder
Remarks

This is in the form of a factory function because the request may need to be sent more than once.

RequestHeader(string, string)

Adds a request header to be sent with each EventSource HTTP request.

Declaration
public ConfigurationBuilder RequestHeader(string name, string value)
Parameters
Type Name Description
string name

the header name
string value

the header value
Returns
Type Description
ConfigurationBuilder

the builder

RequestHeaders(IDictionary<string, string>)

Sets the request headers to be sent with each EventSource HTTP request.

Declaration
public ConfigurationBuilder RequestHeaders(IDictionary<string, string> headers)
Parameters
Type Name Description
IDictionary<string, string> headers

the headers (null is equivalent to an empty dictionary)
Returns
Type Description
ConfigurationBuilder

the builder

ResponseStartTimeout(TimeSpan)

Sets the maximum amount of time EventSource will wait between starting an HTTP request and receiving the response headers.

Declaration
public ConfigurationBuilder ResponseStartTimeout(TimeSpan responseStartTimeout)
Parameters
Type Name Description
TimeSpan responseStartTimeout

the timeout
Returns
Type Description
ConfigurationBuilder
Remarks

This is the same as the Timeout property in .NET's HttpClient. The default value is DefaultConnectionTimeout.

It is not the same as a TCP connection timeout. A connection timeout would include only the time of establishing the connection, not the time it takes for the server to prepare the beginning of the response. .NET does not consistently support a connection timeout, but if you are using .NET Core or .NET 5+ you can implement it by using SocketsHttpHandler as your HttpMessageHandler(HttpMessageHandler) and setting the ConnectTimeout property there.