Class ServiceCollectionExtensions

Namespace

CSF.Extensions.WebDriver

Assembly

CSF.Extensions.WebDriver.dll

Extension methods for IServiceCollection to add web driver factory options, created from configuration.

public static class ServiceCollectionExtensions

Inheritance

object

ServiceCollectionExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Methods

AddWebDriverFactory(IServiceCollection, IConfigurationSection, Action<WebDriverCreationOptionsCollection>)

Adds/registers the web driver factory and related services for applications which make use of the Options & Configuration patterns, using a specified configuration section.

public static IServiceCollection AddWebDriverFactory(this IServiceCollection services, IConfigurationSection configSection, Action<WebDriverCreationOptionsCollection> configureOptions = null)

Parameters

services IServiceCollection

The service collection to which the services should be added.

configSection IConfigurationSection

A configuration section from which the WebDriverCreationOptionsCollection should be bound.

configureOptions Action<WebDriverCreationOptionsCollection>

An optional method body which may inspect or alter the options after it has been bound from the configuration.

Returns

IServiceCollection

The service collection, so that calls may be chained.

Remarks

When calling this method, there is no need to use AddWebDriverFactoryWithoutOptionsPattern(IServiceCollection), as this method implicitly adds those services as well.

This method enables the use of IGetsWebDriver and its implementation WebDriverFactory: A 'universal WebDriver factory'. This also adds an IOptions<TOptions> for WebDriverCreationOptionsCollection to dependency injection.

This overload expects the specified configuration section to correspond directly with the root of the WebDriverCreationOptionsCollection to be bound.

A good use-case for the configureOptions parameter is to add secrets/credentials for remote WebDrivers to the options. It is not best practice to include credentials/passwords in configuration which is checked into source control. Instead, configure secrets like this in your environment directly and consume them in your application/tests as environment variables. This options-configuration callback may be used to read those secrets from the environment and supplement the configuration, without the need to include those secrets in any configuration files.

An important technique to remember is that the IConfiguration may be populated from more than one source. For example, in a Microsoft Generic Host application, it is default behaviour to receive configuration from both an appsettings.json as well as supplemental command-line parameters and/or environment variables. That technique is very useful for setting the value of SelectedConfiguration. The options collection in a configuration file may contain all of the WebDriver configurations that your application would use in any scenario, and may use a single command-line parameter or environment variable to choose which of those WebDriver configurations should be activated.

AddWebDriverFactory(IServiceCollection, string, Action<WebDriverCreationOptionsCollection>)

Adds/registers the web driver factory and related services for applications which make use of the Options & Configuration patterns.

public static IServiceCollection AddWebDriverFactory(this IServiceCollection services, string configPath = "WebDriverFactory", Action<WebDriverCreationOptionsCollection> configureOptions = null)

Parameters

services IServiceCollection

The service collection to which the options should be added.

configPath string

An optional path from the root of the configuration; if null then the default value of WebDriverFactory will be used.

configureOptions Action<WebDriverCreationOptionsCollection>

An optional method body which may inspect or alter the options after it has been bound from the configuration.

Returns

IServiceCollection

The service collection, so that calls may be chained.

Remarks

When calling this method, there is no need to use AddWebDriverFactoryWithoutOptionsPattern(IServiceCollection), as this method implicitly adds those services as well.

This method enables the use of IGetsWebDriver and its implementation WebDriverFactory: A 'universal WebDriver factory'. This also adds an IOptions<TOptions> for WebDriverCreationOptionsCollection to dependency injection, using the IConfiguration present in the application.

If the configPath is not specified, then the options will be created from a configuration path named WebDriverFactory, relative to the root of the application's configuration.

A good use-case for the configureOptions parameter is to add secrets/credentials for remote WebDrivers to the options. It is not best practice to include credentials/passwords in configuration which is checked into source control. Instead, configure secrets like this in your environment directly and consume them in your application/tests as environment variables. This options-configuration callback may be used to read those secrets from the environment and supplement the configuration, without the need to include those secrets in any configuration files.

An important technique to remember is that the IConfiguration may be populated from more than one source. For example, in a Microsoft Generic Host application, it is default behaviour to receive configuration from both an appsettings.json as well as supplemental command-line parameters and/or environment variables. That technique is very useful for setting the value of SelectedConfiguration. The options collection in a configuration file may contain all of the WebDriver configurations that your application would use in any scenario, and may use a single command-line parameter or environment variable to choose which of those WebDriver configurations should be activated.

AddWebDriverFactoryWithoutOptionsPattern(IServiceCollection)

Adds/registers the service types required to make use of a WebDriver factory which does not depend upon the Options & Configuration patterns.

public static IServiceCollection AddWebDriverFactoryWithoutOptionsPattern(this IServiceCollection services)

Parameters

services IServiceCollection

The service collection to which the services should be added.

Returns

IServiceCollection

The service collection, so that calls may be chained.

Remarks

Use this method if your application does not make use of either Microsoft.Extensions.Options or Microsoft.Extensions.Configuration. You will not be able to use IGetsWebDriver or WebDriverFactory but you will be able to use ICreatesWebDriverFromOptions.

If you do use the Options & Configuration patterns then use an overload of AddWebDriverFactory(IServiceCollection, string, Action<WebDriverCreationOptionsCollection>) instead and do not use this method. The UseWebDriverFactory methods implicitly include all of the services which are included here.

AddWebDriverQuirks(IServiceCollection, QuirksData, bool, string)

Adds services to depenency injection which support the 'browser quirks' infrastructure.

public static IServiceCollection AddWebDriverQuirks(this IServiceCollection services, QuirksData quirksData = null, bool useOptions = true, string configPath = "WebDriverQuirks")

Parameters

services IServiceCollection

The service collection to which the services should be added.

quirksData QuirksData

An optional source of static quirks data.

useOptions bool

Whether or not to use quirks information from the Microsoft Options Pattern as a source of data, to either provide all of the quirks, or to supplement/shadow the data in quirksData.

configPath string

A string indicating the configuration path at which to find quirks data; meaningless and unused if useOptions is false.

Returns

IServiceCollection

Remarks

Either quirksData must not be null or useOptions must be true or else an exception will be raised from this method.

If you wish to make use of the browser-quirks functionality provided by this library then this method is used to set that functionality up within dependency injection. This method permits the usage of up to two sources of information for the QuirksData which shall be used to indicate which browsers/versions are affected by which quirks:

• A static source of data, provided via quirksData
• Data coming from the Microsoft Options Pattern, if useOptions is set to true (this is the default value)

The purpose of using two sources of data for the quirks is described in more depth in the remarks to QuirksDataProvider but in short it allows library authors to provide some static quirks data which may be supplemented and/or overridden (in part or completely) by user-specified options.

If you wish to use AddQuirks then this method must be used in order to add the required services to DI.

Exceptions

ArgumentException

If both quirksData is null and useOptions is false.

See Also

QuirksDataProvider

IHasQuirks