Fluent Configuration

Fluent configuration is new feature of PetaPoco. Its design focus was on ease of use and powerful configuration possibilities. Using the traditional constructors, one would have to instantiate then possibly configure each PetaPoco instance. With the new fluent configuration, this is all handled in an elegant manner.

We believe the easiest way to explain this feature is through examples. The API is very much self-documenting and covers 100% of the configuration options. In fact, the fluent configuration API makes some of the harder parts of configuration super easy. We would suggest any new comer start with this.

Example - Basic: Shortest path to an instance

var db = DatabaseConfiguration.Build().Create();

Example - Basic: Configure a few options

var db = DatabaseConfiguration
    .Build()
    .UsingCommandTimeout(180)
    .WithAutoSelect()
    .WithoutNamedParams()
    .Create();

Example - Complex: PostgreSQL conventional table and column naming format

var db = DatabaseConfiguration.Build()
         .UsingConnectionName("MyConnection")
         .UsingDefaultMapper<ConventionMapper>(m =>
         {
             // Produces order_line
             m.InflectTableName = (inflector, tn) => inflector.Underscore(tn);
             // Or for order_lines m.InflectTableName = (inflector, tn) => inflector.Pluralise(inflector.Underscore(tn));

             // Produces order_line_id
             m.InflectColumnName = (inflector, cn) => inflector.Underscore(cn);
         })
         .Create();

Example - Complex: IOC/Container

var container = new SimpleInjector.Container();

container.RegisterSingleton<IDatabaseBuildConfiguration>(DatabaseConfiguration.Build()
    .UsingCommandTimeout(180)
    .WithAutoSelect()
    .WithNamedParams()
    .UsingConnectionStringName("myAppsConnection")
    .UsingDefaultMapper<ConventionMapper>(), Lifestyle.Transient);

container.Register<IDatabase>(() => container.GetInstance<IDatabaseBuildConfiguration>().Create());

API

Flags

WithNamedParams()

This is the default when no call to WithoutNamedParams() is made.

var db = DatabaseConfiguration.Build().WithNamedParams().Create();

WithoutNamedParams()

Do not allow named parameters.

var db = DatabaseConfiguration.Build().WithoutNamedParams().Create();

WithAutoSelect()

This is the default when on call to WithoutAutoSelect() is made.

var db = DatabaseConfiguration.Build().WithAutoSelect().Create();

WithoutAutoSelect()

Do not build the select part for any statement missing it.

var db = DatabaseConfiguration.Build().WithoutAutoSelect().Create();

Options that take parameters

UsingCommandTimeout(int seconds)

When not set the IDbCommand.CommandTimeout is not updated, so the .NET default of 30 seconds will be used.

var db = DatabaseConfiguration.Build().UsingCommandTimeout(60).Create();

UsingConnectionString(string connectionString)

Also requires a provider to be specified by a call to any UsingProvider method.

var db = DatabaseConfiguration.Build()
        .UsingConnectionString("my.connection.string;")
        .UsingProvider<MySqlDatabaseProvider>()
        .Create();

UsingConnectionStringName(string connecionStringName)

The value should match a corresponding connection string in the app/web configuration file.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <clear />
    <add name="mssql"
      connectionString="Data Source=.\SQLEXPRESS;AttachDbFileName=|DataDirectory|Databases\MSSQL\petapoco.mdf;Integrated Security=True;User Instance=True"
      providerName="System.Data.SqlClient"/>
  </connectionStrings>
</configuration>

var db = DatabaseConfiguration.Build()
        .UsingConnectionStringName("mssql")
        .Create();

UsingProvider<T>()

An instance of type T will be used.

var db = DatabaseConfiguration.Build()
        .UsingProvider<MySqlDatabaseProvider>()
        .UsingConnectionString("my connection string;")
        .Create();

UsingProvider<T>(Action<T> configure)

An instance of type T will be used. The parameter configure will be called with the instance of type T passed to it.

var db = DatabaseConfiguration.Build()
        .UsingProvider<CustomMySqlDatabaseProvider>(p =>
             {
                 p.EnableSuperFastNetworkSupportFeature = true;
                 p.SomeOtherItemThatCanBeConfigured = Configuration.Yey;
             }
        )
        .UsingConnectionString("my connection string;")
        .Create();

UsingProvider<T>(T provider)

Accepts a provider of type T.

var db = DatabaseConfiguration.Build()
        .UsingProvider(new MySqlDatabaseProvider())
        .UsingConnectionString("my connection string;")
        .Create();

UsingProvider<T>(T provider, Action<T> configure)

Accepts a provider of type T. The parameter configure will be called with the instance of type T passed to it.

var db = DatabaseConfiguration.Build()
        .UsingProvider(new CustomMySqlDatabaseProvider(), p =>
             {
                 p.EnableSuperFastNetworkSupportFeature = true;
                 p.SomeOtherItemThatCanBeConfigured = Configuration.Yey;
             }
        )
        .UsingConnectionString("my connection string;")
        .Create();

UsingDefaultMapper<T>()

An instance of T will be used.

var db = DatabaseConfiguration.Build()
         .UsingConnectionName("MyConnection")
         .UsingDefaultMapper<ConventionMapper>()
         .Create();

UsingDefaultMapper<T>(Action<T> configure)

An instance of type T will be used. The parameter configure will be called with the instance of type T passed to it.

var db = DatabaseConfiguration.Build()
         .UsingConnectionName("MyConnection")
         .UsingDefaultMapper<ConventionMapper>(m =>
         {
             // Produces order_line
             m.InflectTableName = (inflector, tn) => inflector.Underscore(tn);
             // Or for order_lines m.InflectTableName = (inflector, tn) => inflector.Pluralise(inflector.Underscore(tn));

             // Produces order_line_id
             m.InflectColumnName = (inflector, cn) => inflector.Underscore(cn);
         })
         .Create();

UsingDefaultMapper<T>(T mapper)

Accepts a mapper of type T.

var db = DatabaseConfiguration.Build()
         .UsingConnectionName("MyConnection")
         .UsingDefaultMapper(new MyCustomMapper())
         .Create();

UsingDefaultMapper<T>(T mapper, Action<T> configure)

Accepts a mapper of type T. The parameter configure will be called with the instance of type T passed to it.

var db = DatabaseConfiguration.Build()
         .UsingConnectionName("MyConnection")
         .UsingDefaultMapper(new MyCustomMapper(), m =>
         {
             m.UpperCaseEverything = true;
         })
         .Create();