NetworkInspector.Exporters
0.22.0
dotnet add package NetworkInspector.Exporters --version 0.22.0
NuGet\Install-Package NetworkInspector.Exporters -Version 0.22.0
<PackageReference Include="NetworkInspector.Exporters" Version="0.22.0" />
<PackageVersion Include="NetworkInspector.Exporters" Version="0.22.0" />
<PackageReference Include="NetworkInspector.Exporters" />
paket add NetworkInspector.Exporters --version 0.22.0
#r "nuget: NetworkInspector.Exporters, 0.22.0"
#:package NetworkInspector.Exporters@0.22.0
#addin nuget:?package=NetworkInspector.Exporters&version=0.22.0
#tool nuget:?package=NetworkInspector.Exporters&version=0.22.0
NetworkInspector.Exporters
Write captured frames back to capture files, or parsed packets to analysis formats. Eight formats share one builder pattern and one lifecycle:
- Frame exporters (
IFrameListener) convert captures without parsing: PCAPNG, BLF, ASC. - Packet exporters (
IPacketListener) write parsed packets: JSON, CSV, Text, PBF, Parquet. They write selected fields, all fields, or all fields with hierarchy (see Choose What To Export); only the hierarchy needs a field tree. - DuckDB lives in the add-on package
NetworkInspector.Exporters.DuckDb.
Highlights
- One API for every format.
CreateBuilder()→To…()→With…()→Build()→OnFrame/OnPacket→OnFinish(). Switching formats is a one-line change. - Round trips you can trust. PCAPNG interface options, BLF channel names, CAN DLC 9–15, the LIN protected id, and the LIN checksum model survive read → write → read. The round-trip tests are cross-validated with an independent reference reader.
- Analytics-ready columnar output. Parquet, DuckDB, and PBF Columnar share one batch model with native unsigned 64-bit columns and a field catalog.
- No stray files. Output is opened lazily on the first item, so a filter that matches nothing writes nothing.
- Errors are reported, not swallowed. Tolerant mode (default) skips bad items and raises
ItemSkipped; strict mode stops at the first one. Every exporter counts written, skipped, and failed items. - Safe cleanup.
OnFinish()always releases every buffer and the output, even after a failing trailer, and reports release failures as oneAggregateException.Dispose()is an idempotentOnFinish(). - Size-based splitting.
EstimatedOutputBytesreports the live output size, which theniCLI uses for--split-size.
Install
dotnet add package NetworkInspector.Exporters
To read captures and parse packets you also need:
dotnet add package NetworkInspector.Sources
dotnet add package NetworkInspector.Protocols
NetworkInspector.Core comes in as a dependency.
Quick Start
Parse A Capture And Export JSON
using NetworkInspector.Core;
using NetworkInspector.Core.Ids;
using NetworkInspector.Exporters.Json;
using NetworkInspector.Protocols;
using NetworkInspector.Settings;
using NetworkInspector.Sources.Pcapng;
// One registry for the stack and the source; a different registry makes TryParse fail.
FrameInterfaceRegistry registry = new();
StackBuilder builder = new(new SettingsManager(), registry);
builder.RegisterStandardProtocols();
using Stack stack = builder.Build();
using PcapngSource source = PcapngSource.Open("capture.pcapng");
source.Start(registry.RegisterSource(source), registry);
using JsonExporter exporter = JsonExporter.CreateBuilder()
.ToFile("packets.json")
.WithFormat(JsonExportFormat.Pretty)
.Build();
exporter.ItemSkipped += (_, e) => Console.Error.WriteLine($"#{e.ItemIndex} {e.Kind}: {e.Message}");
// The default ParseOptions builds a field tree, which every packet exporter accepts. Selected-fields exports can skip it (see Choose What To Export).
// First-parse ids must be dense (0, 1, 2, ...): advance only on success.
ParseOptions options = new();
int nextId = 0;
while (source.NextFrame() is { } frame)
{
if (!Packet.TryParse(nextId, stack, frame, in options, out Packet? packet, out ParseFailure failure)
|| packet is null)
{
Console.Error.WriteLine($"frame {frame.Id.Value}: {failure}");
continue;
}
nextId++;
if (!exporter.OnPacket(packet))
{
break;
}
}
exporter.OnFinish();
Console.WriteLine($"{exporter.WrittenCount} packets written, {exporter.SkippedCount} skipped");
Replace JsonExporter with CsvExporter, TextExporter, PbfExporter, or ParquetExporter to change the
format; the loop stays the same.
Convert Frames Without Parsing (PCAPNG → BLF)
using NetworkInspector.Core;
using NetworkInspector.Exporters.Blf;
using NetworkInspector.Sources.Pcapng;
FrameInterfaceRegistry registry = new();
using PcapngSource source = PcapngSource.Open("capture.pcapng");
source.Start(registry.RegisterSource(source), registry);
using BlfExporter exporter = BlfExporter.CreateBuilder()
.ToFile("capture.blf")
.WithCompressionLevel(BlfCompressionLevel.Default)
.Build();
while (source.NextFrame() is { } frame)
{
if (!exporter.OnFrame(frame))
{
break;
}
}
exporter.OnFinish();
Choose What To Export
Every field exporter (CSV, JSON, Text, PBF, Parquet, DuckDB) takes an ExportContent through WithContent(…) that says
what to write. The choice also decides how much parse work the pipeline has to do:
| Shape | Writes | Parse work |
|---|---|---|
SelectedFields |
the fields you name, numbered by occurrence | parse without field tree (the exporter watches the fields) |
AllFields |
every field that has a value, numbered by occurrence | parse without field tree (the exporter watches every field) |
Hierarchy |
every node with parent and sibling order | parse with field tree |
The field tree is the leading content of every export. The members of ExportContent beyond the shape are additional:
Info (the packet summary line), CustomText and CustomRepresentation (written only where a dissector set one), and
FrameBytes, which is off by default: the tree already holds the parsed bytes of every layer, so a copy of every frame is
written only on request (ExportContent.FrameBytes = true, CLI frames=true). Every packet exporter can write it; the
exporter guide lists the form per format (CSV takes it as the
column CsvColumnKind.FrameBytes). Buffers is off by default too: protocols attach bytes to a packet that the tree shows only
as parsed values (the datagram a fragment completes, a TCP PDU, a decoded HTTP body, an unmasked WebSocket payload), and with
ExportContent.Buffers = true (CLI buffers=true) every packet exporter writes each of them with its index (CSV: the column
CsvColumnKind.Buffers). The frame exporters (PCAPNG, BLF, ASC) have no such option. Both members never change a field row.
// Two fields, first occurrence of each, written to DuckDB. No field tree is built for the export.
FieldRequest[] requests = [new("ip.src", Occurrences.First), new("udp.dstport", Occurrences.First)];
if (!FieldSelection.TryCreate(stack, requests, Occurrences.All, out FieldSelection? selection, out FieldSelectionError error))
{
throw new InvalidOperationException(error.Message);
}
using DuckDbExporter exporter = DuckDbExporter.CreateBuilder()
.ToFile("flows.duckdb")
.WithContent(new ExportContent { Shape = ExportShape.SelectedFields, Fields = selection })
.Build();
// The exporter tells the pipeline what it needs; the plan combines it with the needs of other consumers (a filter, a value cache).
ParseDemand[] demands = [exporter.ParseDemand];
if (!ParsePlan.TryCreate(stack, demands, out ParsePlan? plan, out ParsePlanError planError))
{
throw new InvalidOperationException(planError.Message);
}
ParseOptions options = plan.Options; // fields only, no tree (2 fields, 1 observer)
// ... Packet.TryParse(id, stack, frame, in options, ...) then exporter.OnPacket(packet) for every packet, then OnFinish().
- Occurrences. A field can appear more than once in a packet (an address in a tunnel).
Occurrences.Allwrites every appearance (nothing is dropped silently),FirstandLastwrite one. The occurrence number counts appearances of that field in the packet; it is not a position in the tree. - The same values in every shape. A selected-fields, an all-fields, and a hierarchy export of one packet carry the same values, types, and custom texts, whether the exporter was fed by a parse without tree or by a walk of the field tree.
- A filter costs no tree either.
FilterObserver.ParseDemandis the demand of a compiled filter; list it first in the plan and readTryReadMatchbefore you commit the packet. The exporter guide (§14, §15) explains the shapes, the demand, and the commit rule in full. - Defaults. An exporter without
WithContentwrites itsDefaultContent(the hierarchy shape for the field formats). The other exporters keepDefaultContentas the content written withoutWithContent; CSV writes packet rows without it, and itsContentTemplateis the starting point forWithContent.
Choose A Format
| Exporter | Kind | Output | Best for |
|---|---|---|---|
PcapngExporter |
Frames | .pcapng |
Capture exchange with any PCAPNG reader |
BlfExporter |
Frames | .blf |
Vector and automotive toolchains |
AscExporter |
Frames | .asc |
Readable bus traces |
JsonExporter |
Packets | .json |
Scripts and log pipelines |
CsvExporter |
Packets | .csv |
Spreadsheets and SQL imports |
TextExporter |
Packets | .txt |
Protocol trees for people |
PbfExporter |
Packets | .pbf |
Compact binary at scale |
ParquetExporter |
Packets | directory | DuckDB, pandas, Polars, Spark |
DuckDbExporter |
Packets | .duckdb |
SQL in one file |
Output targets: every exporter except Parquet supports ToFile. All except Parquet and DuckDB also support ToStream (the
caller keeps the stream open and owns it), ToStdout (the exporter closes stdout when it finishes), and
ToTarget(IExportTarget): the host's target, from which the exporter opens the one entry ExportEntryName.Main on its first
item. Parquet writes a dataset: ToDirectory (a folder) or ToTarget, which receives one named entry per table file.
DuckDB supports ToFile only, because its library opens the file itself. The target contract and the three ready targets
(FileExportTarget, StreamExportTarget, DirectoryExportTarget) are in the exporter guide.
Lifecycle And Errors
| Member | Meaning |
|---|---|
OnFrame / OnPacket |
Write one item; false means stop (limit, cancellation, strict error) |
OnFinish() |
Write trailers, flush, release; idempotent |
ErrorTolerance |
ErrorToleranceMode.Tolerant (default) or Strict |
ItemSkipped |
Event with ItemIndex, Kind (ExportErrorKind), Message |
WrittenCount, SkippedCount, ErrorCount, HasErrors |
Statistics |
EstimatedOutputBytes |
Live output size estimate |
- Call
OnFinish()before disposal to write final metadata. A failing trailer or flush is reported throughItemSkippedandHasErrors; every buffer and the output are still released. If releasing fails,OnFinish()throws oneAggregateExceptionafter every step ran. - Each builder also offers
WithTargetFrameCount/WithTargetPacketCountandWithCancellationToken. - A packet parsed without a field tree is written when the exporter staged its fields through its own observer (selected or
all fields) or when it writes packet-level data only (CSV packet rows); an exporter that needs the tree (the hierarchy shape)
skips such a packet and raises
ItemSkippedwithExportErrorKind.SerializationErrorand the messageSkip packets cannot be exported (HasFieldTree is false).(the same in every exporter with a hierarchy shape).
Round Trips
Frames read by NetworkInspector.Sources and written back keep their bus fields and interface metadata:
- Classic CAN bus DLC 9–15 (
len8_dlc), remote-frame DLC, the LIN protected id, and the LIN checksum model survive BLF and ASC. - BLF and ASC take the channel from
blf.channel,asc.channel, or a trailing number in the interface name. BLF writes interface names back as AppText channel names. - PCAPNG writes
if_name,if_description, and theif.*interface options back, and passes unknown DLT values through. - BLF start dates use UTC on both sides by default (
BlfExporter.Builder.WithTimestampTimeZone). UseTimeZoneInfo.Localfor files that Vector tools or other readers that assume local time will read. - ASC timestamps carry 6 to 9 fraction digits (
AscExporter.Builder.WithTimestampDecimals, default 6, rounded).
Limits And Thread-Safety Notes
- Exporter instances are single-threaded: call
OnFrame/OnPacket/OnFinishfrom one thread. DuckDB, Parquet, PBF, and BLF additionally write full batches on a writer thread of their own (WithWriteMode(ExportWriteMode.Background), the default); a stream passed to them must not be used untilOnFinishreturned.ExportWriteMode.Synchronouskeeps every write on the calling thread. See the exporter guide §9.5. - File targets do not create missing parent directories and overwrite existing files.
ToDirectoryandDirectoryExportTargetcreate the folders of their entries;ToDirectoryalso removes an earlier Parquet dataset first. A host target'sTryOpenWritemay be called from the writer thread, so it must not depend on thread affinity. - Exporters do not validate upstream trust assumptions; validate and bound input at the source and parse boundary.
- Format details (compression, schemas, dialects) are documented in each format README.
Safe Usage (STRIDE)
- Spoofing: Keep source provenance outside the export when chain of custody matters.
- Tampering: Log
ItemSkippeddecisions in calling code. - Repudiation: Store the exporter configuration next to the output for reproducibility.
- Information disclosure: JSON, CSV, Text, and columnar outputs can contain payload data. Protect them.
- Denial of service: Use target counts, cancellation, and split limits in high-volume runs.
- Elevation of privilege: Run exports with least-privilege write access.
Learn More
- Exporter guide: finish sequence, shared bus-field representation, BLF timestamps, test layout
- Sources · Core · CLI · Root overview
- GitHub repository · Issue tracker
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- InvariantStringHelper (>= 1.0.0)
- NetworkInspector.Core (>= 0.22.0)
- Parquet.Net (>= 6.1.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on NetworkInspector.Exporters:
| Package | Downloads |
|---|---|
|
NetworkInspector.Exporters.DuckDb
DuckDB packet exporter for NetworkInspector. Writes parsed packets to a single .duckdb file via DuckDBAppender bulk-load. Depends on NetworkInspector.Exporters for the shared columnar batch model. |
|
|
NetworkInspector.BuiltInPlugins
Built-in core-tier plugins: standard protocols, file and random sources, and the nine exporters on the plugin contract. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.22.0 | 111 | 11/16/2026 |
| 0.21.0 | 119 | 11/10/2026 |
| 0.20.0 | 129 | 11/4/2026 |
| 0.19.0 | 133 | 10/29/2026 |
| 0.18.0 | 129 | 10/22/2026 |
| 0.17.0 | 121 | 10/17/2026 |
| 0.16.0 | 127 | 10/17/2026 |
| 0.15.0 | 122 | 10/9/2026 |
| 0.14.0 | 148 | 10/8/2026 |
| 0.13.0 | 124 | 9/27/2026 |
| 0.12.0 | 135 | 9/17/2026 |
| 0.11.0 | 417 | 9/10/2026 |
| 0.10.0 | 148 | 9/8/2026 |
| 0.9.0 | 150 | 9/2/2026 |
| 0.8.0 | 177 | 8/28/2026 |
| 0.7.0 | 146 | 8/27/2026 |
| 0.6.0 | 155 | 8/21/2026 |
| 0.5.0 | 157 | 7/11/2026 |
| 0.4.0 | 160 | 6/2/2026 |
| 0.3.0 | 161 | 5/21/2026 |