Class FixedWidthBinaryExtractor<TRecord>

Namespace
Wolfgang.Etl.FixedWidth
Assembly
Wolfgang.Etl.FixedWidth.dll

Reads a fixed-length binary record file (mainframe / COBOL, #21) and yields records of type TRecord. Unlike FixedWidthExtractor<TRecord>, records are not newline-delimited — each record is a fixed number of bytes (the sum of the ByteLength of every field), read directly from the stream, so packed-decimal and binary bytes that happen to be 0x0A/0x0D are never mistaken for record separators.

public sealed class FixedWidthBinaryExtractor<TRecord> : ExtractorBase<TRecord, FixedWidthReport>, IExtractWithProgressAndCancellationAsync<TRecord, FixedWidthReport>, IExtractWithCancellationAsync<TRecord>, IExtractWithProgressAsync<TRecord, FixedWidthReport>, IExtractAsync<TRecord>, IReportsItemErrors, IAsyncDisposable, IDisposable where TRecord : notnull, new()

Type Parameters

TRecord

The record type, whose FixedWidthBinaryFieldAttribute properties define the byte layout. Requires a public parameterless constructor.

Inheritance
ExtractorBase<TRecord, FixedWidthReport>
FixedWidthBinaryExtractor<TRecord>
Implements
IExtractWithProgressAndCancellationAsync<TRecord, FixedWidthReport>
IExtractWithCancellationAsync<TRecord>
IExtractWithProgressAsync<TRecord, FixedWidthReport>
IExtractAsync<TRecord>
IReportsItemErrors
Inherited Members
ExtractorBase<TRecord, FixedWidthReport>.ExtractAsync()
ExtractorBase<TRecord, FixedWidthReport>.DisposeAsync()
ExtractorBase<TRecord, FixedWidthReport>.Dispose()
ExtractorBase<TRecord, FixedWidthReport>.ReportingInterval
ExtractorBase<TRecord, FixedWidthReport>.CurrentItemCount
ExtractorBase<TRecord, FixedWidthReport>.CurrentSkippedItemCount
ExtractorBase<TRecord, FixedWidthReport>.CurrentErrorItemCount
ExtractorBase<TRecord, FixedWidthReport>.MaximumItemCount
ExtractorBase<TRecord, FixedWidthReport>.SkipItemCount
ExtractorBase<TRecord, FixedWidthReport>.WorkerResilience
ExtractorBase<TRecord, FixedWidthReport>.ErrorPolicy

Examples

await using var stream = File.OpenRead("accounts.dat");
using var extractor = new FixedWidthBinaryExtractor<AccountRecord>(stream);
await foreach (var account in extractor.ExtractAsync(token))
{
    // account.Balance decoded from COMP-3, account.TransactionCount from COMP, …
}

Constructors

FixedWidthBinaryExtractor(Stream, ILogger<FixedWidthBinaryExtractor<TRecord>>)

Initializes a new FixedWidthBinaryExtractor<TRecord> from a Stream using the default options, with diagnostic logging.

[Obsolete("Use the constructor that takes FixedWidthBinaryExtractorOptions. This overload will be removed in a future release.")]
public FixedWidthBinaryExtractor(Stream stream, ILogger<FixedWidthBinaryExtractor<TRecord>> logger)

Parameters

stream Stream

The stream to use.

logger ILogger<FixedWidthBinaryExtractor<TRecord>>

The logger to use for diagnostic output.

Exceptions

ArgumentNullException

stream is null.

FixedWidthBinaryExtractor(Stream, FixedWidthBinaryExtractorOptions?, ILogger<FixedWidthBinaryExtractor<TRecord>>?)

Initializes a new FixedWidthBinaryExtractor<TRecord> that reads fixed-length binary records from stream. The caller retains ownership of the stream.

public FixedWidthBinaryExtractor(Stream stream, FixedWidthBinaryExtractorOptions? options = null, ILogger<FixedWidthBinaryExtractor<TRecord>>? logger = null)

Parameters

stream Stream

The readable binary record stream.

options FixedWidthBinaryExtractorOptions

Options that control behaviour, including the encoding. When null — or omitted — the documented defaults apply.

logger ILogger<FixedWidthBinaryExtractor<TRecord>>

An optional ILogger<TCategoryName> for diagnostic output. Pass null (the default) to disable logging.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream is not readable.

Properties

Encoding

The Encoding used by this instance. Superseded by Encoding.

[Obsolete("Set Encoding on FixedWidthBinaryExtractorOptions and pass it to the constructor instead. This property will be removed in a future release.")]
public Encoding Encoding { get; init; }

Property Value

Encoding

Remarks

Retained for source compatibility with 0.10.x. It is honoured only when the constructor was given no options object; a caller who passes options is using the supported route and that value wins. The two cannot conflict in existing code, because the options constructor did not exist before 0.11.0.

RecordByteLength

The number of bytes in one record, derived from the field layout.

public int RecordByteLength { get; }

Property Value

int

Methods

CreateProgressReport()

Creates a progress report of type TProgress. This gives the derived class the opportunity to implement a custom progress report that is specific to the extraction process.

protected override FixedWidthReport CreateProgressReport()

Returns

FixedWidthReport

Progress of type TProgress

CreateProgressTimer(IProgress<FixedWidthReport>)

Creates the Wolfgang.Etl.Abstractions.IProgressTimer used to drive progress callbacks. Override this method in a derived class to inject a custom timer (for example, a custom implementation that allows manual control in unit tests).

protected override IProgressTimer CreateProgressTimer(IProgress<FixedWidthReport> progress)

Parameters

progress IProgress<FixedWidthReport>

The progress sink that will receive callbacks.

Returns

IProgressTimer

A started Wolfgang.Etl.Abstractions.IProgressTimer instance.

ExtractWorkerAsync(CancellationToken)

This method is the core implementation of the extraction logic and should be overridden by derived classes.

protected override IAsyncEnumerable<TRecord> ExtractWorkerAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

Returns

IAsyncEnumerable<TRecord>

IAsyncEnumerable<TSource> The result may be an empty sequence if no data is available or if the extraction fails.

Edit this page