API Rules for designers: use one encoding, not two

 

API Rules for designers: use one encoding, not two

 

"If you haven't tested your code, it's probably wrong"

 

Today's bad API example is from the Bluetooth Heart Rate system. Most of the protocol is fine: you get a notification every so often with updated heart rate information (e.g.,  heart rate in beats per minutes (BPM) plus optional stuff for overall energy and the "RR Interval" for fine-grained heart data).

 

Testing this protocol is extra expensive because the heart rate (BPM) can be sent in two ways. It might be a single byte, and it might be two bytes. There's a single bit in a flags structure to say which way it is. If the person's heart is 255 BPM or less, it's one byte. If it's 256 or more, it's two bytes. The app code (and device code) has to handle this.

 

For an app, the code is hard to test for two reasons. Most importantly, a human doesn't ever have a heart rate that high (according to Copilot, "255+ BPM is possible, but it’s always pathological"). The second is that even if I could find a person with a heart rate that high, I have no confidence that any specific consumer-grade device will ever produce this data. As just a person coding in their spare time, I can buy a couple of heart monitors. But imagine I still worked at Microsoft: what are the changes that a VP (that's the clearance it takes for approving purchases) would sign off on an unknown number of devices on the chance that one of them would produce this data?

 

In the end, I've got code in my new Bluetooth app (not on the Microsoft app store yet) to handle the special flag. But my confidence that it works isn't great.

 

The right API choice was to always send 2 bytes of data and not try to make something in the name of spurious efficiency.

 

For the nay-sayers: the awkward protocol doesn't support any interesting new scenarios, and doesn't have any appreciable amount of energy.

 

If they had kept the protocol as-is, developers would have the same abilities. The RR Interval data size would shrink from 9 entries to 8 -- but in typical use, there's only 3 or 4 entries. And if there's a case for needing more than 8 entries, the Bluetooth device could simply transmit more often.

 

Takeaway: Protocol designers should always include "how will a developer test their code" when considering complicated APIs.

 

IL2104 IL2026 TRIM and JSON with WinUI3 and newer C#

 JSON: why is C# TRIM so horrible for no reason 

Trim analysis warning IL2026: SerializeExtra.Demonstrate_Bug_Program.Demonstrate_Bug_Main(): Using member 'System.Text.Json.JsonSerializer.Serialize(!!0, JsonSerializerOptions)' which has 'RequiresUnreferencedCodeAttribute' can break functionality when trimming application code. JSON serialization and deserialization might require types that cannot be statically analyzed. Use the overload that takes a JsonTypeInfo or JsonSerializerContext, or make sure all of the required types are preserved.

In the old days, C# had a simple JSON story: always use the Newtonsoft JSON library, helpfully packaged up in NuGet, and never use anything else, ever. But then I tried making an app with WinUI3 and the more recent C# (like version 10?), and now it completely sucks, and it's ten times harder than it should be. And it's all Microsoft's fault

C# introduced a new concept: TRIM. This is a link time option. It's on by default for Release mode and off by default for Debug mode. What it does it go through your app and removes all of the "unneeded" code. The problem is that it means that the normal way Newtonsoft's JSON works doesn't work; it will just plain crash.

Note the horrific discovery mechanism for this, by the way: there you are, coding happily in a shiny new app, using shiny new features, and a switch you didn't set causes weird-ass warnings when you compile, and then your app crashes, but only when you're almost done and are now testing in Release mode.

The only solution is to switch to the System.Text.Json.JsonSerializer and Deserializer classes. But even these are completely broken with the new switch, and delightfully (sarcasm) the official Microsoft documentation guides you right into the absolute wrong way to use them.

Worse, the C# classes also guide you into the wrong way. Those shiny new templated classes? Those won't work at all.

Luckily, I've researched it so you can just jump right into the pit of success.

• When you make your SourceGenerationContext from JsonSerializerContext, always add a TypeInfoPropertyName option 
• When you call Serialize of Deserialize, you must use the non-templated versions. Pass in your object (or string, for deserialize), the typeof(yourclass) and your SourceGenerationContext.Default object. 
• Never new up a SourceGenerationContext object. When you do, it won't have the JsonSourceGenerationOptions that the Microsoft docs tell you to use
• Always specify a [JsonSourceGenerationOptions(WriteIndented = true)]. If you wanted a compressed serialization format, you'd have used Protocol Buffers, not JSON. When you use JSON, it's because your users want a human readable result, not some one-line nonsense.

See my complete project on Github for more details. The About file is particularly helpful. Look at the WeatherForecast_Fix1.cs file for full details. The bug is reported to Microsoft .NET team.

Fixing the dreaded XAML parsing failed

Fixing my XAML Parsing Failed bug (subfolders)

This is a doozy, and is about the last possible bug one would imagine in the new WinUI3 that Microsoft is pushing for us to use when making apps for Windows.

The background when you make an app using C# (and really, why wouldn't you?), you will use the XAML mini-language for describing your layout. XAML has conceptually been around for years, but Microsoft being Microsoft, they can't help but radically change it and rename it every few years. The XAML for WPF isn't the XAML for SilverLight, which isn't the XAML for UWP, which isn't the XAML for the most recent WinUI3

And a problem that a ton of people have discovered is that somewhat randomly they will write some XAML and it will just fail. But it won't fail at compile time (they do compile-time work to make it run fast; the XAML is not interpreted at runtime). Instead, it fails when your XAML page or control is displayed! The exception generally just says "XAML Parsing Error".

Well, I've figured what's going on. Like any seasoned developer, I use folders to organize my controls. Guess what programming system from a major OS company can't handled "putting a control into a folder"? That's right, Microsoft's WinUI3!

I've filed [a bug](WinUI3 (Microsoft.UI...) creates broken UserControls when creating in a sub-folder - Developer Community).

And I've got a simple repro [on GitHub](https://github.com/pedasmith/bug_WinUI3_usercontrol_in_folder_xaml_parse)

Weird EPUB bug: empty image files in the IRS i1040gi.epub file

This EPUB bug brought to you by the IRS and their i1040gi.epub file

Normally government EPUB files are pretty good about making usable EPUB files. But this year only, the IRS's "i1040gi.epub" file (the file with USA government tax information for filing out the very common 1040 tax form) has a subtly malformed epub file. The list of images (EPUB/img) has 28 GIF files which are all fine, and one JPG file (cover-instr-i1040.jpg) which is zero bytes long.

This file fails to load correctly which leads to a cascade of errors.

Solution is to catch the error and silently ignore it. (Technically, I first check for zero-byte files and ignore it, and also catch the exception and ignore it. Both branches were tested, of course)