When ASP.NET Core MVC endpoints process high-frequency webhooks, telemetry batches, or custom delimited payloads, default deserialisation pipelines can become a major source of memory churn. Reading an entire request stream into a string or byte[] array, splitting substrings with string.Split, and parsing individual tokens with int.Parse(string) or decimal.Parse(string) allocating heap objects on every request. Under heavy load, those short-lived allocations pressure the Garbage Collector (GC), trigger Gen0/Gen1/Gen2 collections, and spike tail (p99) latency.
By combining System.IO.Pipelines (PipeReader), ReadOnlySpan<byte> / ReadOnlySequence<byte>, and a custom TextInputFormatter / InputFormatter, you can stream incoming request bytes directly from Kestrel and parse structured records with minimal or zero heap allocations per record. This guide walks through how to design, implement, register, and benchmark a zero-allocation custom input formatter in ASP.NET Core MVC.
1. Architectural Blueprint & Allocation Hotspots
Understanding where allocations happen in standard request ingestion helps explain why PipeReader and Span<T> are so effective:
Stage | Naive Stream/String Approach | Zero-Allocation PipeReader + Span<byte> Approach |
Stream Reading | StreamReader.ReadToEndAsync() buffers the entire body into a large string on the heap.
| HttpContext.Request.BodyReader (PipeReader) yields ReadOnlySequence<byte> chunks as network buffers arrive.
|
Tokenization | `line.Split(' | ')allocates astring[]plus astring` instance for every field. |
Type Parsing | decimal.Parse(fieldStr) requires a string and culture-heavy overhead.
| Utf8Parser.TryParse(fieldSpan, out decimal value, out _) parses ASCII/UTF-8 digits straight from bytes.
|
HTTP Request Body (Kestrel Socket / Pipe)
│
▼
[PipeReader (HttpContext.Request.BodyReader)]
│ Reads ReadOnlySequence<byte> segments without copying entire payload
▼
[Custom InputFormatter (TelemetryBatchInputFormatter)]
│ Handles single-segment Span<byte> fast path + multi-segment SequenceReader fallback
│ Parses fields with Utf8Parser.TryParse (zero string allocations)
▼
[Strongly Typed Domain Model (TelemetryBatch)]
│
▼
[MVC Controller Action]
2. Target Domain Model & Wire Format
Suppose an ingestion endpoint receives high-throughput metering or telemetry batches formatted as newline-delimited pipe records (|-separated):
Plaintext
METER-1001|1732000800|148.75|200
METER-1002|1732000801|312.40|200
Each line contains:
DeviceCode (ASCII string)
UnixTimestampSeconds (long)
ReadingValue (decimal)
StatusCode (int)
We define the immutable domain model and batch container:
C#
public readonly record struct TelemetryReading(
string DeviceCode,
long UnixTimestampSeconds,
decimal ReadingValue,
int StatusCode
);
public sealed class TelemetryBatch
{
public List<TelemetryReading> Readings { get; } = [];
}
3. Implementing the Zero-Allocation Custom InputFormatter
When reading from PipeReader, a single line or field can occasionally straddle two ReadOnlyMemory<byte> segments inside a ReadOnlySequence<byte>. A production-grade formatter handles contiguous single-segment buffers on a fast path using ReadOnlySpan<byte> and Utf8Parser, while falling back to SequenceReader<byte> when a line spans multiple segments.
C#
using System.Buffers;
using System.Buffers.Text;
using System.IO.Pipelines;
using System.Text;
using Microsoft.AspNetCore.Mvc.Formatters;
using Microsoft.Net.Http.Headers;
public sealed class TelemetryBatchInputFormatter : InputFormatter
{
private const byte PipeByte = (byte)'|';
private const byte NewLineByte = (byte)'\n';
private const byte CarriageReturnByte = (byte)'\r';
private const int MaxBatchReadings = 10_000;
public TelemetryBatchInputFormatter()
{
SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/x-telemetry-batch"));
}
protected override bool CanReadType(Type type)
{
return type == typeof(TelemetryBatch);
}
public override async Task<InputFormatterResult> ReadRequestBodyAsync(InputFormatterContext context)
{
ArgumentNullException.ThrowIfNull(context);
var httpContext = context.HttpContext;
var reader = httpContext.Request.BodyReader;
var batch = new TelemetryBatch();
int lineNumber = 0;
try
{
while (true)
{
ReadResult result = await reader.ReadAsync(httpContext.RequestAborted);
ReadOnlySequence<byte> buffer = result.Buffer;
while (TryReadLine(ref buffer, out ReadOnlySequence<byte> lineSequence))
{
lineNumber++;
if (batch.Readings.Count >= MaxBatchReadings)
{
context.ModelState.TryAddModelError(
context.ModelName,
$"Batch exceeds maximum allowed size of {MaxBatchReadings} readings.");
reader.AdvanceTo(buffer.End);
return await InputFormatterResult.FailureAsync();
}
if (!TryParseLine(lineSequence, out TelemetryReading reading, out string? error))
{
context.ModelState.TryAddModelError(
context.ModelName,
$"Line {lineNumber}: {error ?? "Invalid telemetry record format."}");
reader.AdvanceTo(buffer.End);
return await InputFormatterResult.FailureAsync();
}
batch.Readings.Add(reading);
}
// Tell the PipeReader how much of the buffer was consumed and examined
reader.AdvanceTo(buffer.Start, buffer.End);
if (result.IsCompleted)
{
// Handle trailing data if the final line did not end with '\n'
if (!buffer.IsEmpty)
{
lineNumber++;
if (!TryParseLine(buffer, out TelemetryReading trailingReading, out string? error))
{
context.ModelState.TryAddModelError(
context.ModelName,
$"Line {lineNumber}: {error ?? "Invalid trailing telemetry record."}");
return await InputFormatterResult.FailureAsync();
}
batch.Readings.Add(trailingReading);
reader.AdvanceTo(buffer.End);
}
break;
}
}
return await InputFormatterResult.SuccessAsync(batch);
}
catch (OperationCanceledException)
{
throw;
}
catch (Exception ex)
{
context.ModelState.TryAddModelError(
context.ModelName,
$"Error reading telemetry stream: {ex.Message}");
return await InputFormatterResult.FailureAsync();
}
}
private static bool TryReadLine(ref ReadOnlySequence<byte> buffer, out ReadOnlySequence<byte> line)
{
SequencePosition? position = buffer.PositionOf(NewLineByte);
if (position is null)
{
line = default;
return false;
}
line = buffer.Slice(0, position.Value);
buffer = buffer.Slice(buffer.GetPosition(1, position.Value));
return true;
}
private static bool TryParseLine(
ReadOnlySequence<byte> line,
out TelemetryReading reading,
out string? error)
{
reading = default;
error = null;
// Fast path: entire line fits inside a single contiguous memory span
if (line.IsSingleSegment)
{
return TryParseSpan(line.FirstSpan, out reading, out error);
}
// Fallback path for lines split across PipeReader segments
var seqReader = new SequenceReader<byte>(line);
if (!seqReader.TryReadTo(out ReadOnlySequence<byte> deviceSeq, PipeByte, advancePastDelimiter: true) ||
!seqReader.TryReadTo(out ReadOnlySequence<byte> timestampSeq, PipeByte, advancePastDelimiter: true) ||
!seqReader.TryReadTo(out ReadOnlySequence<byte> valueSeq, PipeByte, advancePastDelimiter: true))
{
error = "Expected 4 pipe-delimited fields.";
return false;
}
ReadOnlySequence<byte> statusSeq = line.Slice(seqReader.Position);
if (statusSeq.IsEmpty)
{
error = "Missing status code field.";
return false;
}
string deviceCode = Encoding.ASCII.GetString(deviceSeq);
if (string.IsNullOrWhiteSpace(deviceCode))
{
error = "Device code cannot be empty.";
return false;
}
if (!TryParseInt64(timestampSeq, out long timestamp) ||
!TryParseDecimal(valueSeq, out decimal value) ||
!TryParseInt32(statusSeq, out int statusCode))
{
error = "One or more numeric fields could not be parsed.";
return false;
}
reading = new TelemetryReading(deviceCode, timestamp, value, statusCode);
return true;
}
private static bool TryParseSpan(
ReadOnlySpan<byte> span,
out TelemetryReading reading,
out string? error)
{
reading = default;
error = null;
// Trim optional trailing '\r' from CRLF payloads
if (!span.IsEmpty && span[^1] == CarriageReturnByte)
{
span = span[..^1];
}
if (span.IsEmpty)
{
error = "Empty telemetry line.";
return false;
}
int idx1 = span.IndexOf(PipeByte);
if (idx1 <= 0)
{
error = "Missing or invalid device code.";
return false;
}
ReadOnlySpan<byte> deviceSpan = span[..idx1];
ReadOnlySpan<byte> rest1 = span[(idx1 + 1)..];
int idx2 = rest1.IndexOf(PipeByte);
if (idx2 <= 0)
{
error = "Missing or invalid timestamp field.";
return false;
}
ReadOnlySpan<byte> timestampSpan = rest1[..idx2];
ReadOnlySpan<byte> rest2 = rest1[(idx2 + 1)..];
int idx3 = rest2.IndexOf(PipeByte);
if (idx3 <= 0)
{
error = "Missing or invalid reading value field.";
return false;
}
ReadOnlySpan<byte> valueSpan = rest2[..idx3];
ReadOnlySpan<byte> statusSpan = rest2[(idx3 + 1)..];
if (statusSpan.IsEmpty)
{
error = "Missing status code field.";
return false;
}
if (!Utf8Parser.TryParse(timestampSpan, out long timestamp, out int tsConsumed, 'D') ||
tsConsumed != timestampSpan.Length)
{
error = "Invalid integer timestamp.";
return false;
}
if (!Utf8Parser.TryParse(valueSpan, out decimal value, out int valConsumed) ||
valConsumed != valueSpan.Length)
{
error = "Invalid decimal reading value.";
return false;
}
if (!Utf8Parser.TryParse(statusSpan, out int statusCode, out int statusConsumed, 'D') ||
statusConsumed != statusSpan.Length)
{
error = "Invalid integer status code.";
return false;
}
string deviceCode = Encoding.ASCII.GetString(deviceSpan);
reading = new TelemetryReading(deviceCode, timestamp, value, statusCode);
return true;
}
private static bool TryParseInt64(ReadOnlySequence<byte> seq, out long value)
{
if (seq.IsSingleSegment)
{
return Utf8Parser.TryParse(seq.FirstSpan, out value, out int consumed, 'D') &&
consumed == seq.FirstSpan.Length;
}
Span<byte> stackBuf = stackalloc byte[32];
if (seq.Length > stackBuf.Length)
{
value = 0;
return false;
}
seq.CopyTo(stackBuf);
return Utf8Parser.TryParse(stackBuf[..(int)seq.Length], out value, out int consumed, 'D') &&
consumed == seq.Length;
}
private static bool TryParseDecimal(ReadOnlySequence<byte> seq, out decimal value)
{
if (seq.IsSingleSegment)
{
return Utf8Parser.TryParse(seq.FirstSpan, out value, out int consumed) &&
consumed == seq.FirstSpan.Length;
}
Span<byte> stackBuf = stackalloc byte[64];
if (seq.Length > stackBuf.Length)
{
value = 0;
return false;
}
seq.CopyTo(stackBuf);
return Utf8Parser.TryParse(stackBuf[..(int)seq.Length], out value, out int consumed) &&
consumed == seq.Length;
}
private static bool TryParseInt32(ReadOnlySequence<byte> seq, out int value)
{
if (seq.IsSingleSegment)
{
return Utf8Parser.TryParse(seq.FirstSpan, out value, out int consumed, 'D') &&
consumed == seq.FirstSpan.Length;
}
Span<byte> stackBuf = stackalloc byte[16];
if (seq.Length > stackBuf.Length)
{
value = 0;
return false;
}
seq.CopyTo(stackBuf);
return Utf8Parser.TryParse(stackBuf[..(int)seq.Length], out value, out int consumed, 'D') &&
consumed == seq.Length;
}
}
4. Registering the Formatter & Consuming It in an MVC Controller
Programmatic Registration (Program.cs)
Insert TelemetryBatchInputFormatter into MvcOptions.InputFormatters so MVC invokes it automatically when a request carries Content-Type: text/x-telemetry-batch and targets TelemetryBatch.
C#
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers(options =>
{
options.InputFormatters.Insert(0, new TelemetryBatchInputFormatter());
});
var app = builder.Build();
app.MapControllers();
app.Run();
Controller Action (TelemetryController.cs)
The controller action receives a validated TelemetryBatch without ever touching raw streams, StreamReader, or string splitting logic:
C#
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/telemetry")]
public sealed class TelemetryController : ControllerBase
{
private readonly ILogger<TelemetryController> _logger;
public TelemetryController(ILogger<TelemetryController> logger)
{
_logger = logger;
}
[HttpPost("ingest")]
[Consumes("text/x-telemetry-batch")]
public IActionResult Ingest([FromBody] TelemetryBatch batch)
{
if (!ModelState.IsValid)
{
return ValidationProblem(ModelState);
}
decimal totalReading = 0m;
foreach (var reading in batch.Readings)
{
totalReading += reading.ReadingValue;
}
_logger.LogInformation(
"Ingested {Count} telemetry readings with total value {Total}.",
batch.Readings.Count,
totalReading);
return Ok(new
{
AcceptedCount = batch.Readings.Count,
TotalReadingValue = totalReading
});
}
}
5. Verifying Behavior and Allocation Profile
You can verify both correctness and allocation behavior using integration tests with WebApplicationFactory<Program> and microbenchmarks with BenchmarkDotNet:
C#
using System.Net;
using System.Net.Http.Headers;
using System.Text;
using Microsoft.AspNetCore.Mvc.Testing;
using Xunit;
public sealed class TelemetryControllerTests : IClassFixture<WebApplicationFactory<Program>>
{
private readonly WebApplicationFactory<Program> _factory;
public TelemetryControllerTests(WebApplicationFactory<Program> factory)
{
_factory = factory;
}
[Fact]
public async Task Ingest_ValidPipeDelimitedBatch_ReturnsAcceptedSummary()
{
using var client = _factory.CreateClient();
const string payload = "MTR-01|1732000800|125.50|200\nMTR-02|1732000805|74.50|200\n";
using var content = new StringContent(payload, Encoding.ASCII);
content.Headers.ContentType = new MediaTypeHeaderValue("text/x-telemetry-batch");
var response = await client.PostAsync("/api/telemetry/ingest", content);
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
}
[Fact]
public async Task Ingest_MalformedNumericField_ReturnsValidationProblem()
{
using var client = _factory.CreateClient();
const string payload = "MTR-01|NOT_A_TIMESTAMP|125.50|200\n";
using var content = new StringContent(payload, Encoding.ASCII);
content.Headers.ContentType = new MediaTypeHeaderValue("text/x-telemetry-batch");
var response = await client.PostAsync("/api/telemetry/ingest", content);
Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
}
}
When benchmarking TelemetryBatchInputFormatter with BenchmarkDotNet ([MemoryDiagnoser]), keep two practical rules in mind:
Test both single-segment and multi-segment ReadOnlySequence<byte> inputs: A real network pipe often splits payloads across segments, so verify that your SequenceReader<byte> fallback produces identical results to the contiguous ReadOnlySpan<byte> fast path.
Guard against untrusted input sizes: Always enforce explicit line/batch limits (MaxBatchReadings) and validate Utf8Parser consumed byte counts (consumed == span.Length) so trailing garbage characters cannot slip past partial parses.
Conclusion
Pairing PipeReader, ReadOnlySpan<byte> / Utf8Parser, and a custom InputFormatter gives ASP.NET Core MVC applications a clean, high-throughput path for ingesting custom or high-volume payloads. Instead of buffering full request bodies into strings and allocating intermediate arrays per line, your application streams bytes directly from the network pipeline, validates malformed records early via ModelState, and hands clean domain models to your controllers with drastically lower GC pressure and tighter tail latency.
Join the conversation! Your thoughts help the community grow.