RossWright.MetalCore.Data 2026.1.1

Ross Wright's Metal Core Data Library

Copyright (c) 2023-2026 Pross Co.

Table of Contents

• Entity Framework Extensions
  • Database Context
  • SaveChanges with FK Errors
  • RefreshTable
  • Database Timing Interceptor
• GeoCoder
• Installation
• See Also
• License

Entity Framework Extensions

Database Context

DbContextExtensions adds three utility methods to any DbContext that targets a relational database.

Obliterate() is destructive. It is designed for integration test teardown where a fresh schema is required between runs. Do not call it in production code.

SaveChanges with FK Errors

DbContextExtensions.SaveChangesAsyncWithFkErrors wraps SaveChangesAsync and provides structured handling for foreign key constraint violations. When EF throws a DbUpdateException caused by an FK constraint, the callback receives the parsed constraint name rather than requiring you to parse the exception message yourself.

await context.SaveChangesAsyncWithFkErrors(report =>
    throw new InvalidOperationException($"Cannot delete: referenced by '{report.ConstraintName}'"));

ForeignKeyErrorReport properties:

RefreshTable

RefreshTableExtensions.RefreshTable synchronizes a DbSet<DBENTITY> against an incoming collection of INENTITY objects in a single call, performing the insert/update/delete logic automatically. It returns an IRefreshResult reporting how many records were added, updated, and deleted.

var result = await context.Users.RefreshTable(incomingUsers);
// result.Adds, result.Updates, result.Deletes

By default, records absent from the incoming data are not deleted. Pass deleteSourceEntities: true to enable removal of absent records.

Record matching — overloads constrained to IHasId match by Guid Id. Overloads without that constraint accept a custom Func<DBENTITY, INENTITY, bool> isSame predicate.

Entity copying — by default, matching members are copied using CopyTo. Pass a custom Action<DBENTITY, INENTITY> update delegate to control exactly which fields are updated.

Data fetching — by default, ToListAsync() loads the current set. Pass a custom Func<DbSet<DBENTITY>, Task<List<DBENTITY>>> fetchOldData delegate to apply filters (e.g. restrict to a specific parent record).

The seven overloads cover combinations of these three axes:

IHasId is a core MetalCore contract (RossWright namespace) that requires a Guid Id property. Most database entity base classes implement it.

IRefreshResult

Database Timing Interceptor

IDatabaseTimingInterceptor accumulates the total EF command execution time for the current DI scope, enabling per-request database timing without external tooling.

Register in Program.cs and attach to your DbContext options:

// Program.cs
services.AddDatabaseTimingInterceptor();
services.AddDbContext<AppDbContext>((sp, opts) =>
    opts.UseSqlServer(connectionString)
        .UseDatabaseTimingInterceptor(sp));

// Inject IDatabaseTimingInterceptor anywhere in the same scope
var ms = timingInterceptor.RunTimeInMilliseconds;

Registration lifetime: AddDatabaseTimingInterceptor registers the interceptor as scoped, which is required for per-request timing to work correctly. Do not register IDatabaseTimingInterceptor as a singleton — doing so will cause timing to accumulate across all requests rather than resetting per scope.

GeoCoder

IGeoCoderService provides a single method that resolves a US postal code or "City, State" string to a latitude/longitude coordinate pair.

Offline lookup only. The bundled GeoCoderService uses an embedded data file — it does not contact any external API. Only US postal codes and "City, State" strings are supported. Unrecognized inputs throw MetalCoreException.

var coords = geoCoderService.GetCoordinates("90210");        // zip code
var coords = geoCoderService.GetCoordinates("Beverly Hills, CA"); // City, State
// coords.Lat, coords.Lng

Register with AddGeoCoderService():

services.AddGeoCoderService();

LatLong

LatLong is a value struct holding a latitude and longitude. It provides two utility methods for geographic calculations:

Service Reference

Installation

dotnet add package RossWright.MetalCore.Data

Or add directly to your project file:

<PackageReference Include="RossWright.MetalCore.Data" Version="*" />

See Also

License

All Ross Wright Metal Libraries including this one are licensed under Apache License 2.0 with Commons Clause.

You are free to:

• Use the libraries in any project (personal or commercial)
• Modify them
• Include them in products or services you sell

You may not:

• Sell the libraries themselves (or any product/service whose primary value comes from the libraries)
• Repackage them with minimal changes and sell them as your own standalone product

Full legal text: LICENSE.md