Custom Database Connections | AdminUI Documentation

Overview

This page assumes you have read the AdminUI as a NuGet package documentation area.

The AdminUI NuGet package uses a factory abstraction for creating database connections. When using the AdminUI NuGet package in your web applications, you can use the default implementation. This uses connection strings in configuration to create the connection. The connection strings it uses are in appSettings.json and cover 5 different areas of functionality:

  "IdentityConnectionString": "...",
  "IdentityServerConnectionString": "...",
  "AuditRecordsConnectionString": "...",
  "DataProtectionConnectionString": "...",
  "OperationalConnectionString": "...",
  "DataProtectionConnectionString": "...",

You can get away with just using the first 2 as the last 3 will default to the second one. See here for more details.

Alternatively, you can write your own connection factory implementation to create connections using a different strategy. This opens up AdminUI to users who may have not been able to take advantage of it in the past - perhaps users who deploy AdminUI in Azure and authenticates with the database via an Azure AD token.

Changes

As mentioned above, AdminUI’s connection creation has historically been based purely on using connection strings.

AdminUI 6.7 adds a pluggable abstraction that allows for the decoupling from this old strategy.

The abstraction is IDatabaseConnectionFactory and it initialized in AdminUI's service layer with the default implementation. The interface is defined thus:

public interface IDatabaseConnectionFactory
{
     // Create connection for the Identity database (Users, Claim Types, Roles etc.)
    public DbConnection CreateIdentityConnection(bool migration = false);

    // Create connection for the IdentityServer database (Clients, Resources, Persited Grants etc.)
    public DbConnection CreateIdentityServerConnection(bool migration = false);

    // Create connection for the Auditing DbContext
    public DbConnection CreateAuditRecordsConnection(bool migration = false);

    // Create connection for the Persisted Grants DbContext
    public DbConnection CreateOperationalConnection(bool migration = false);

    // Creates connection for the DataProtectionKey DbContext
    public DbConnection CreateDataProtectionConnection(bool migration = false);
}

The migration parameter in each method is used to distinguish whether the method is called by AdminUI as part of its normal operation or when running migrations (in case you need to distinguish).

To change the default implementation, simply implement this interface and tell AdminUI to use it instead of the default.

Starting point

To get started, take the result of the NuGet Installation and update the service registration to the following:

builder.Services
    .AddAdminUI(
        options =>
        {
            options.DatabaseConnectionFactoryType = DatabaseConnectionFactoryType.Custom;
        })
    .WithConnectionFactory<MyCustomConnectionFactory>();

The WithConnectionFactory<MyCustomConnectionFactory>() method replaces the default connection factory implementation with that defined by MyCustomConnectionFactory class that you write.

That's it!

Additional Considerations

If the custom connection factory has additional interfaces injected into its constructor that are unknown to AdminUI then these will have to be registered with the DI container in the usual way using builder.Services, for example, if your custom connection factory implementation looks like this:

public class MyCustomConnectionFactory : IDatabaseConnectionFactory
{
    public MyCustomConnectionFactory(IConfiguration configuration, IMyOtherInterface myOtherInterface)
    {
        ...
    }

    ...
}

then the service registration might look like this:

builder.Services.AddSingleton<IMyOtherInterface, MyOtherInterfaceImplementation>();
builder.Services
    .AddAdminUI(
        options =>
        {
            options.DatabaseConnectionFactoryType = DatabaseConnectionFactoryType.Custom;
        })
    .WithConnectionFactory<MyCustomConnectionFactory>();

Sample code

A sample of how to replace the connection factory can be found on our GitHub in the CustomDatabaseConnection project. Remember to fill in the CustomConnectionFactoryConnectionString connection string and the license key in appSettings.json.

Previous Next