Upgrading to JauntyConfig.Configure
Warning This release breaks your build if your code sets any Jaunty mapping setting. Assigning
JauntyConfig.TableNameResolver,ColumnNameResolver,SchemaNameResolver,DefaultEnumStorage,CopyImportFactoryor anyReflection*Resolver, or callingJauntyConfig.RegisterTypeHandler,JauntyConfig.RemoveTypeHandler,JauntyReflectionExtensions.UseReflectionMapping(),SpecialTypeMappers.Register()orJauntyNpgsql.Use(), no longer compiles. Move those lines into oneJauntyConfig.Configurecall at startup, as shown below.
Code that only runs queries, or only sets Logger, the capacities, interceptors,
BulkCopyConfiguration or dialect registrations, is not affected. Code the source generator wrote
for your entities is not affected either; you do not need to rebuild for it.
What you will see
error CS0200: Property or indexer 'JauntyConfig.ColumnNameResolver' cannot be assigned to -- it is read only
error CS0117: 'JauntyConfig' does not contain a definition for 'RegisterTypeHandler'
error CS0117: 'JauntyNpgsql' does not contain a definition for 'Use'
error CS7036: There is no argument given that corresponds to the required parameter 'config' of 'JauntyReflectionExtensions.UseReflectionMapping(JauntyConfigBuilder)'
error CS7036: There is no argument given that corresponds to the required parameter 'config' of 'SpecialTypeMappers.Register(JauntyConfigBuilder)'
Why
One Jaunty operation reads these settings more than once: an Insert reads the column names for
its parameter values, then again for its SQL text. If another thread changed a setting between
those reads, the SQL and the parameters were built from different settings, and the call failed
with a confusing database error such as "Must add values for the following parameters". Setting
everything once, before the first query, removes that window, and removing the setters makes a
late change a compile error rather than a rare runtime failure. The full reasoning, the options
compared and the measurements are in
decision 014.
What to change
Put every line from the left column into one Configure call, as in the right column.
| Before | After, inside JauntyConfig.Configure(c => { ... }) |
|---|---|
JauntyConfig.TableNameResolver = f; |
c.TableNameResolver = f; |
JauntyConfig.SchemaNameResolver = f; |
c.SchemaNameResolver = f; |
JauntyConfig.ColumnNameResolver = f; |
c.ColumnNameResolver = f; |
JauntyConfig.DefaultEnumStorage = s; |
c.DefaultEnumStorage = s; |
JauntyConfig.CopyImportFactory = f; |
c.CopyImportFactory = f; |
JauntyConfig.ReflectionMapperResolver = f; (and the other 6 Reflection*Resolvers, SpecialTypeMapperResolver) |
c.ReflectionMapperResolver = f; |
JauntyConfig.RegisterTypeHandler<T>(fromDb, toDb); |
c.RegisterTypeHandler<T>(fromDb, toDb); |
JauntyConfig.RegisterTypeHandler(new MyHandler()); |
c.RegisterTypeHandler(new MyHandler()); |
JauntyReflectionExtensions.UseReflectionMapping(); |
c.UseReflectionMapping(); (usually not needed, see below) |
SpecialTypeMappers.Register(); |
SpecialTypeMappers.Register(c); (UseReflectionMapping already does this) |
JauntyNpgsql.Use(); |
c.UseNpgsqlCopy(); |
JauntyConfig.RemoveTypeHandler<T>(); |
No replacement: don't register it. Handlers are fixed at startup. |
Reading a setting still works the same way: JauntyConfig.ColumnNameResolver still returns the
resolver. But a read now counts as first use (rule 1), so code that logs a setting such as
JauntyConfig.DefaultEnumStorage before calling Configure must move after it.
A console app or worker
// Before
JauntyConfig.TableNameResolver = t => Snake(t.Name);
JauntyConfig.ColumnNameResolver = Snake;
JauntyConfig.RegisterTypeHandler(new MoneyHandler());
JauntyNpgsql.Use();
// After
JauntyConfig.Configure(c =>
{
c.TableNameResolver = t => Snake(t.Name);
c.ColumnNameResolver = Snake;
c.RegisterTypeHandler(new MoneyHandler());
c.UseNpgsqlCopy();
});
ASP.NET Core
Call it in Program.cs before builder.Build() runs anything that queries, and before any hosted
service starts:
var builder = WebApplication.CreateBuilder(args);
JauntyConfig.Configure(c =>
{
c.TableNameResolver = t => Snake(t.Name);
c.ColumnNameResolver = Snake;
});
builder.Services.AddJauntyLogging(); // runtime settings are unchanged
var app = builder.Build();
If a setting comes from configuration, read it first and use ConfigureOnce (see the rules below):
string schema = builder.Configuration["Db:Schema"] ?? "";
JauntyConfig.ConfigureOnce(c => c.SchemaNameResolver = _ => schema);
Reflection mapping
If your project references Extrode.Jaunty.Extensions.Reflection, Configure switches reflection
mapping on before your callback runs, exactly as Jaunty did on its own before. You only need
c.UseReflectionMapping() where that automatic step cannot run, which is a trimmed or NativeAOT
publish, or to put the hooks back after replacing one of them by hand. If you never call
Configure, Jaunty still switches reflection mapping on by itself on first use.
Rules to know
Call
Configureonce, at startup, before anything touches Jaunty. Running a query, a Fluent query, reading a generated member such asProduct.Jaunty.TableName, or reading a mapping setting such asJauntyConfig.DefaultEnumStoragecounts as first use.Configureafter that throws:textInvalidOperationException: JauntyConfig.Configure was called after Extrode.Jaunty had already read its settings (a query, a generated TableName, a Fluent query, or a read of a JauntyConfig mapping setting ran first).A query running on another thread while
Configureruns is detected the same way:Configurethrows, puts the previous settings back, and that query may fail too.A second call with the same settings does nothing; with different settings it throws. "The same" means every delegate refers to the same method on the same target. Method groups (
c.ColumnNameResolver = Snake;) and lambdas that capture nothing compare equal, and type handlers compare by their type, soc.RegisterTypeHandler(new MoneyHandler())is the same on every run. That also means two handlers of one class built with different constructor arguments count as the same, and the second call silently keeps the first. A lambda that captures a variable is a new delegate on every call, so make that call throughJauntyConfig.ConfigureOnce, which applies the first call and skips the rest without running them. A repeatedConfigureruns your callback again to compare, so keep it free of side effects.Settings cannot change while the app runs. Per-tenant or per-request table names are not supported: they would need settings scoped to a connection, which Jaunty does not have. If you switched a resolver at runtime, the usual replacement is one resolver that handles every case, or separate schemas chosen by the connection string.
Integration tests that start the app more than once
WebApplicationFactory, Aspire and similar hosts can run Program.cs several times in one test
process. That keeps working when the settings are the same each time (rule 2). If they differ, or
use captured values, call ConfigureOnce instead of Configure; it is safe when hosts start on
parallel threads. The first host's settings then apply to every host in that process.
Rule 1 applies to the whole test process: if any test runs a query before the first host starts,
every later Configure or ConfigureOnce throws, and which test runs first depends on ordering. Set
the settings once for the test assembly before any test runs, for example in a module initializer,
and let the hosts' own call become a no-op:
internal static class JauntyTestSetup
{
[System.Runtime.CompilerServices.ModuleInitializer]
internal static void Init() => JauntyConfig.ConfigureOnce(Startup.ConfigureJaunty);
}
where Startup.ConfigureJaunty is the same method Program.cs passes to Configure. Two limits:
- This works only if
Program.cspasses that same method, or callsConfigureOnce. IfProgram.csbuilds its settings frombuilder.Configuration, the module initializer cannot see them, and a plainConfigureinProgram.csthen throws "different settings". UseConfigureOnceinProgram.cs, and the module initializer's settings win. [ModuleInitializer]needs C# 9. On net472 or netstandard2.0 declare the attribute yourself (namespace System.Runtime.CompilerServices { internal sealed class ModuleInitializerAttribute : Attribute { } }) or use a polyfill package.
Fixtures in a separate shared assembly that query before the test assembly's module initializer runs are not supported: the order across assemblies cannot be controlled. Serialize those fixtures or configure from the shared assembly instead.
Your own unit tests
JauntyConfig.Reset() restores the defaults and allows Configure again. It is for tests only,
and it is not safe while another test is using Jaunty, so put tests that call Reset() and then
Configure in a collection that does not run in parallel (xUnit:
[CollectionDefinition("Jaunty config", DisableParallelization = true)]).
[Collection("Jaunty config")]
public sealed class SnakeCaseNamingTests : IDisposable
{
public SnakeCaseNamingTests()
{
JauntyConfig.Reset();
JauntyConfig.Configure(c => c.ColumnNameResolver = Snake);
}
public void Dispose() => JauntyConfig.Reset();
}
A test that used RemoveTypeHandler to undo its own registration now gets the same effect from
Reset() in its cleanup.
Packages that configure Jaunty
A library that set Jaunty settings in its own startup method, such as a type handler package with
a MyHandlers.Use() that called JauntyConfig.RegisterTypeHandler, has to become a builder
extension, and its users call it inside Configure:
// Before, in the package
public static void Use() => JauntyConfig.RegisterTypeHandler(new MoneyHandler());
// After, in the package
public static JauntyConfigBuilder UseMoneyHandlers(this JauntyConfigBuilder c)
=> c.RegisterTypeHandler(new MoneyHandler());
// After, in the app
JauntyConfig.Configure(c => c.UseMoneyHandlers());
Extrode.Jaunty.Extensions.Npgsql and Extrode.Jaunty.Extensions.Reflection made this change
themselves: JauntyNpgsql.Use() is now c.UseNpgsqlCopy(), and
JauntyReflectionExtensions.UseReflectionMapping() is now c.UseReflectionMapping().
UseNativeBulkCopy() is unchanged, because bulk copy settings stay settable at runtime.