Writing a Database Provider¶

Options¶

Microsoft.EntityFrameworkCore.Infrastructure.DbContextOptions is the API surface for users to configure DbContext. Provider writers are responsible for creating API to configure options and to make services responsive to these options. For example, most providers require a connection string. These options are typically created using DbContextOptionsBuilder.

Services¶

System.IServiceProvider is the main interface used for interaction with services. EF makes heavy use of dependency injection (DI). The ServiceProvider contains a collection of services available for injection. Initialization uses DbContextOptions to add additional services if needed and select a scoped set of services that all EF operations will use during execution.

See also Understanding EF Services.

The Use Method¶

By convention, providers define a UseX() extension on DbContextOptionsBuilder. This configures options which it typically takes as arguments to method.

optionsBuilder.UseMyProvider("Server=contoso.com")

The UseX() extension method creates a provider-specific implementation of IDbContextOptionsExtension which is added to the collection of extensions stored within DbContextOptions. This is done by a call to the a hidden API IDbContextOptionsBuilderInfrastructure.AddOrUpdateExtension.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

    public static class MyProviderDbContextOptionsExtensions
    {
        public static DbContextOptionsBuilder UseMyProvider(this DbContextOptionsBuilder optionsBuilder,
            string connectionString)
        {
            ((IDbContextOptionsBuilderInfrastructure) optionsBuilder).AddOrUpdateExtension(
                new MyProviderOptionsExtension
                {
                    ConnectionString = connectionString
                });

            return optionsBuilder;
        }
    }

The Add Method¶

By convention, providers define a AddX() extension on EntityFrameworkServicesBuilder. This configures services and does not take arguments.

EntityFrameworkServicesBuilder is a wrapper around ServiceCollection which is accessible by calling GetInfrastructure(). The AddX() method should register services in this collection to be available for dependency injection.

In some cases, users may call the Add method directly. This is done when users are configuring a service provider manually and use this service provider to resolve an instance of DbContext. In other cases, the Add method is called by EF upon service initialization. For more details on service initialization, see Understanding EF Services.

A provider must register an implementation of IDatabaseProvider. Implementing this in-turn requires configuring several more required services. Read more about working with services in Understanding EF Services.

EF provides many complete or partial implementations of the required services to make it easier for provider-writers. For example, EF includes a class DatabaseProvider<TProviderServices, TOptionsExtension> which can be used in service registration to hook up a provider.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

    public static class MyProviderServiceCollectionExtensions
    {
        public static IServiceCollection AddEntityFrameworkMyProvider(this IServiceCollection services)
        {
            services.AddEntityFramework();

            services.TryAddEnumerable(ServiceDescriptor
                .Singleton<IDatabaseProvider, DatabaseProvider<MyDatabaseProviderServices, MyProviderOptionsExtension>>());

            services.TryAdd(new ServiceCollection()
                // singleton services
                .AddSingleton<MyModelSource>()
                .AddSingleton<MyValueGeneratorCache>()
                // scoped services
                .AddScoped<MyDatabaseProviderServices>()
                .AddScoped<MyDatabaseCreator>()
                .AddScoped<MyDatabase>()
                .AddScoped<MyEntityQueryableExpressionVisitorFactory>()
                .AddScoped<MyEntityQueryModelVisitorFactory>()
                .AddScoped<MyQueryContextFactory>()
                .AddScoped<MyTransactionManager>());

            return services;
        }
    }