Capstone A: the report as JSON
A report printed for a person is a table; a report kept for a program is JSON. The same grouping the previous lesson printed becomes one record with a list inside it, and System.Text.Json turns it into text without a serializer to write. The lesson also reads the text back, so the shape is proven to survive the trip.
The report as a record
Three records carry the report: one log line, one row per level and the report itself. The program parses the four lines of a small log, builds the report with a LINQ query and hands it to the serializer:
using System.Text.Json;
var path = Path.Combine(Path.GetTempPath(), "aredel-json.log");
File.WriteAllLines(path, new[]
{
"2024-03-10T09:30:00Z INFO request id=1 ms=12",
"2024-03-10T09:30:01Z WARN request id=2 ms=240",
"2024-03-10T09:30:02Z ERROR request id=3 ms=90",
"2024-03-10T09:30:03Z INFO request id=4 ms=30",
});
var entries = File.ReadLines(path)
.Select(line => line.Split(' ', StringSplitOptions.RemoveEmptyEntries))
.Where(parts => parts.Length >= 2)
.Select(parts => new LogLine(parts[1], int.Parse(parts[^1].Split('=')[1])))
.ToList();
var report = new Report(
Source: Path.GetFileName(path),
Requests: entries.Count,
TotalMs: entries.Sum(entry => entry.Ms),
Levels: entries
.GroupBy(entry => entry.Level)
.OrderBy(group => group.Key)
.Select(group => new LevelTotal(group.Key, group.Count(), group.Sum(entry => entry.Ms)))
.ToList());
var options = new JsonSerializerOptions { WriteIndented = true };
var json = JsonSerializer.Serialize(report, options);
Console.WriteLine(json);
var outPath = Path.Combine(Path.GetTempPath(), "aredel-report.json");
File.WriteAllText(outPath, json);
var copy = JsonSerializer.Deserialize<Report>(File.ReadAllText(outPath));
Console.WriteLine($"read back {copy?.Levels.Count} levels, total {copy?.TotalMs}");
Console.WriteLine($"bytes {new FileInfo(outPath).Length}");
File.Delete(path);
File.Delete(outPath);
record LogLine(string Level, int Ms);
record LevelTotal(string Level, int Count, int TotalMs);
record Report(string Source, int Requests, int TotalMs, List<LevelTotal> Levels);
The constructor of Report is called with named arguments, so the order of the four values in the call does not have to match the order of the parameters. A record also gives the type a constructor, value equality and a ToString that lists its members, which the serializer ignores.
dotnet run
echo "status: $?"
{
"Source": "aredel-json.log",
"Requests": 4,
"TotalMs": 372,
"Levels": [
{
"Level": "ERROR",
"Count": 1,
"TotalMs": 90
},
{
"Level": "INFO",
"Count": 2,
"TotalMs": 42
},
{
"Level": "WARN",
"Count": 1,
"TotalMs": 240
}
]
}
read back 3 levels, total 372
bytes 310
status: 0
The JSON
The property names are the names of the record parameters, because no naming policy was set. WriteIndented puts one member on a line and indents the nested list, which is what a person reads; without it the whole report is one line, and the second program of this lesson shows that form. The numbers keep their kind: the counts and totals are JSON numbers, not strings.
The file that the program writes and reads again is the same text, 310 bytes, and the reading half proves two things at once: the file is valid JSON, and the shape maps back onto the record exactly. A record with a parameter that the JSON does not have would deserialize to a default value rather than fail, which lesson 072 measured.
Reading it back
JsonSerializer.Deserialize<Report> needs no attribute, because the property names of the JSON and the parameter names of the record agree. The question mark on copy?.Levels.Count is there because deserialization returns a nullable reference: the text null would give null and not an exception. A file whose text is not JSON at all throws JsonException, which lesson 072 shows with its real message.
Another naming
A web API usually writes camelCase, and the option that does it is a naming policy. The second program serializes one row without indentation and with JsonNamingPolicy.CamelCase, then reads one member out of the text with JsonDocument, which parses without any record type at all:
using System.Text.Json;
var options = new JsonSerializerOptions
{
WriteIndented = false,
PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};
var row = new LevelTotal("INFO", 2, 42);
var json = JsonSerializer.Serialize(row, options);
Console.WriteLine(json);
using var document = JsonDocument.Parse(json);
Console.WriteLine(document.RootElement.GetProperty("totalMs").GetInt32());
record LevelTotal(string Level, int Count, int TotalMs);
dotnet run
echo "status: $?"
{"level":"INFO","count":2,"totalMs":42}
42
status: 0
GetProperty("totalMs") would throw KeyNotFoundException if the name were wrong, so a program that reads a document it did not write checks with TryGetProperty first. The document is disposed by the using declaration, because it holds the parsed text of the whole document in memory.
The next lesson turns the log parser into a table of good and bad lines, with a driver whose exit status says whether every case passed.
Exercises
- Add the file name and the time of the run to the report and serialize it again.
- Serialize the same report with JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull and see which members disappear.
- Read the report with JsonDocument and print the level of each row without the record.
- Change the record parameter TotalMs to Total and find out what the old JSON does on deserialization.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which property names does the default serializer write?
Answer
The names of the members, as they are spelled in the type
The measured output has Source, Requests, TotalMs and Levels; a naming policy changes that.
-
What does WriteIndented = true do?
Answer
Puts members on their own lines and indents nested values
The indented form is the readable one the first output block shows.
-
What does this program print?
using System.Text.Json; var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }; Console.WriteLine(JsonSerializer.Serialize(new { TotalMs = 5 }, options));Answer
{"totalMs":5}
The camelCase policy lowers the first letter of every property.
-
What does Deserialize return when the text is the four letters null?
Answer
null
The return type is nullable, which is why the program uses ?.
-
What does this program print?
using System.Text.Json; using var document = JsonDocument.Parse("""{"a":7}"""); Console.WriteLine(document.RootElement.GetProperty("a").GetInt32());Answer
7
GetProperty finds the member and GetInt32 converts its number.
-
Why can a record be serialized without an attribute?
Answer
Its public properties are the members of the JSON object
The serializer maps public properties, and a positional record generates them.
-
What does this program print?
using System.Text.Json; Console.WriteLine(JsonSerializer.Serialize(new[] { 1, 2 }));Answer
[1,2]
An array becomes a JSON array.
-
What happens when the text is not valid JSON?
Answer
JsonException, with the path and the byte position in its message
Lesson 072 shows the real message, which names the path and the position.
-
What does this program print?
Console.WriteLine((5, "x").ToString());Answer
(5, x)
A tuple prints its members in parentheses.
-
Why keep a report as a record and not as a string?
Answer
A program can serialize it, read it back and compare it by value
The type is the contract; the text is one form of it.
The code on this page was built with the .NET SDK 10.0.303 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev