Mail.dat.BulkProcessor 10.4.4

Mail.dat Toolkit

Mail.dat Toolkit is a .NET 10 toolkit for working with USPS Mail.dat data. The repository contains reusable libraries for modeling, importing, exporting, and processing Mail.dat records, plus command-line entry points for import/export workflows and code generation.

Table of Contents

• What Is Mail.dat?
• Projects
• Architecture Overview
• Repository Structure
• Getting Started
• Usage
• Programmatic Usage
• Key Components
• Supported Specification Revisions
• Logging
• License

What Is Mail.dat?

Mail.dat is the USPS file format used to exchange mailing-job information such as postage, containers, pieces, routing, and services. A Mail.dat job is composed of multiple fixed-width record files such as .hdr, .seg, .mpu, .pdr, and .pbc.

This toolkit provides:

• Entity models for Mail.dat records
• Import and export services backed by SQLite
• Bulk-processing helpers for large jobs
• JSON specification models used to generate code
• Command handlers and console entry points for common workflows

Projects

The solution currently includes seven package-producing libraries, three command-handler libraries, two console entry-point projects, and two test projects.

Package-producing libraries

All package-producing library projects target net10.0, are currently version 10.4.2, and are configured with GeneratePackageOnBuild=True and symbol package generation.

Command and application projects

Architecture Overview

The codebase follows a layered design:

┌──────────────────────────────────────────────────────────────┐
│ MaildatCmd / MaildatCmd-BUILD                               │
├──────────────────────────────────────────────────────────────┤
│ ImportCommand / ExportCommand / BuildCommand                │
├──────────────────────────────────────────────────────────────┤
│ Mail.dat.Hosting                                             │
├──────────────────────────────────────────────────────────────┤
│ Mail.dat.Io                     Mail.dat.BulkProcessor      │
├──────────────────────────────────────────────────────────────┤
│ Mail.dat.Models                 Mail.dat.Version            │
├──────────────────────────────────────────────────────────────┤
│ Mail.dat.Json.Specification     Mail.dat.Abstractions       │
└──────────────────────────────────────────────────────────────┘

Key patterns used in the repository:

• Dependency injection via Microsoft.Extensions.Hosting
• Repository abstractions from Diamond.Core.Repository
• Command-handler composition for CLI commands
• Generated model and service registration code from Mail.dat JSON specifications

Repository Structure

Maildat-Toolkit/
├── .github/
│   └── workflows/
├── Src/
│   ├── Mail.dat.Abstractions/
│   ├── Mail.dat.Abstractions.Tests/
│   ├── Mail.dat.BuildCommand/
│   ├── Mail.dat.BulkProcessor/
│   ├── Mail.dat.ExportCommand/
│   ├── Mail.dat.Hosting/
│   ├── Mail.dat.ImportCommand/
│   ├── Mail.dat.Io/
│   ├── Mail.dat.Io.Tests/
│   ├── Mail.dat.Json.Specification/
│   ├── Mail.dat.Models/
│   ├── Mail.dat.Version/
│   ├── Mail.dat Toolkit Solution ALL.sln
│   ├── Maildat-Toolkit Solution - BUILD ONLY.sln
│   ├── Maildat-Toolkit Solution.sln
│   └── MaildatCmd/
├── ARCHITECTURE.md
├── LICENSE.md
└── README.md

Getting Started

Install packages

Package IDs match the project names:

dotnet add package Mail.dat.Io
dotnet add package Mail.dat.Models
dotnet add package Mail.dat.Hosting
dotnet add package Mail.dat.BulkProcessor
dotnet add package Mail.dat.Version

Build from source

The repository build workflow uses:

dotnet restore "./Src/Mail.dat Toolkit Solution ALL.sln"
dotnet build "./Src/Mail.dat Toolkit Solution ALL.sln" --no-restore --configuration Release
dotnet test "./Src/Mail.dat Toolkit Solution ALL.sln" --no-build --configuration Release --verbosity normal

Usage

Standard CLI (MaildatCmd)

The standard MaildatCmd project includes the import and export commands.

import

MaildatCmd import --source-file-path <maildat-or-zip> --target-file-path <sqlite-db>

export

MaildatCmd export --source-file-path <sqlite-db> --target-file-path <maildat-or-zip>

If the export target is a .zip, the generated Mail.dat files are compressed automatically.

Build/code-generation CLI

The build command is provided by Mail.dat.BuildCommand and is wired into the alternate MaildatCmd-BUILD console project used by Maildat-Toolkit Solution - BUILD ONLY.sln.

MaildatCmd build --specification-files <comma-delimited-paths> --models-directory <path> --hosting-directory <path>

The generator merges the supplied specification files and regenerates model classes, interfaces, repositories, MaildatContext, and DI registration code.

Programmatic Usage

Register services

Mail.dat.Hosting exposes AddOpenMaildat<TDatabaseContext>():

using Mail.dat.Hosting;

services.AddOpenMaildat<MaildatContext>();

That extension chains:

• AddMaildatModels()
• AddMaildatIo<TDatabaseContext>()
• AddMaildatBulkProcessor<TDatabaseContext>()

It registers entity factories and repositories for the 29 Mail.dat entities, plus:

• IMaildatImport<TDatabaseContext>
• IMaildatExport
• IBulkProcessorFactory

Import a Mail.dat job

ImportOptions options = new()
{
    SourceFile = MaildatFile.Create("/path/to/job.zip"),
    TargetFile = MaildatFile.Create("/path/to/output.db"),
    TemporaryDirectory = Path.GetTempPath(),
    ExcludeExtensions = [],
    FavorMemoryOverPerformance = false,
    MaxRecordsInMemory = 10_000,
    MaxDegreeOfParallelism = Environment.ProcessorCount,
    CancellationToken = CancellationToken.None
};

IMaildatImport<MaildatContext> importer = MaildatImport<MaildatContext>.Create(
    factory,
    async message => Console.WriteLine(message.StatusMessage)
);

(bool success, MaildatContext context) = await importer.ImportAsync(options);

Export a Mail.dat job

ExportOptions options = new()
{
    SourceFile = MaildatFile.Create("/path/to/source.db"),
    TargetFile = MaildatFile.Create("/path/to/export.zip"),
    TargetVersion = "26-1",
    TargetRevision = "1.0",
    Encoding = Encoding.UTF8,
    LineTerminator = Environment.NewLine,
    MaxDegreeOfParallelism = Environment.ProcessorCount,
    CancellationToken = CancellationToken.None
};

IMaildatExport exporter = MaildatExport.Create(
    async message => Console.WriteLine(message.StatusMessage)
);

bool success = await exporter.ExportAsync(options.TargetFile, options);

Key Components

Mail.dat.Abstractions

Defines shared interfaces, attributes, exceptions, and conversion helpers used across the solution.

Mail.dat.Models

Contains:

• MaildatContext
• 29 generated entity models under Src/Mail.dat.Models/Models
• 168 lookup/value classes under Src/Mail.dat.Models/Values
• Repository implementations for each entity

Mail.dat.Io

Contains:

• MaildatImport<TDatabaseContext>
• MaildatExport
• ImportOptions and ExportOptions
• IMaildatFile and MaildatFile

Mail.dat.Hosting

Contains the DI extensions used to register model repositories, I/O services, and bulk-processing services.

Mail.dat.BulkProcessor

Wraps EFCore.BulkExtensions.Sqlite and provides IBulkProcessorFactory plus the bulk insert/update implementation used during imports.

Mail.dat.Json.Specification

Stores the JSON schema model types and the source specification folders used by the code generator.

Mail.dat.Version

Provides the MaildatVersion model used to represent parsed Mail.dat version and revision information.

Supported Specification Revisions

The repository currently includes Mail.dat specification content for:

• 23-1
• 24-1
• 25-1
• 25-1.1
• 26-1
• 26-1.1

The generated model layer and tests include version-selection support across those revisions.

Logging

MaildatCmd uses Serilog configuration from:

• Src/MaildatCmd/appsettings.json
• Src/MaildatCmd/appsettings.Development.json
• Src/MaildatCmd/appsettings.Production.json

The configured file sink writes logs to:

%TEMP%/MaildatCmd/Logs/MaildatCmd-Log.txt

License

This repository is distributed under the custom license in LICENSE.md.

It is not an open-source license.