Using `dynamic` objects and custom data

In C# 4, Microsoft gave us a beautiful gift: the dynamic type. Their official documentation can be found here, but this page will cover what you need to know to use the dynamics found in CustomJSONData.

Member Access

The magic of dynamic is that any operation at all is assumed by the compiler to be valid for dynamic objects. This means, for instance, that if dyn is a variable of type dynamic, a reference to dyn.foo or dyn.bar will compile even if foo and bar are not declared as members of any type anywhere in your code. The custom data objects provided by CustomJSONData take advantage of this property; any member (e.g. foo) declared on the corresponding JSON object in your song's info.dat or per-difficulty .dat file is accessible to your code simply as (e.g.) _customData.foo.

Safe Member Access

However, attempting to access a nonexistent member this way will generate a nasty RuntimeBinderException. Of course, one can simply catch this exception manually; however, this can become tedious for many member accesses (you never know when your plugin will encounter an outdated or malformed custom data object that appears correct at first glance but lacks a crucial member), so you may wish to use one of the static methods listed below to make your life easier:

Trees.at

The most direct option, this method will return either a member's value or null for nonexistent members.

using static CustomJSONData.Trees;

// later, inside your code
string value = at(_customData, "value");

Trees.tryNull

A more flexible option; this method evaluates any code, and returns null instead if that code would throw an exception.

using static CustomJSONData.Trees;

// ...
string baz = tryNull( () => _customData.foo.bar.baz );
if (baz == null) // ...

Member Types

I'd love to tell you what types you'll find inside your custom data objects, but... I don't quite know myself. CustomJSONData curently uses Newtonsoft.JSON's ExpandoObjectConverter to parse custom data objects, and their documentation is more than a bit sparse in this area. However, it is known that JSON objects will deserialize as Trees (see CustomJSONData/Trees.cs for full definition, but essentially "the thing custom data objects are"). Anything past that will come out as some appropriate type, but I place no bets on the details. (This section may be updated with results from the field.)

More Info

For more details on the technical definition of Tree, and more utility functions for working with them, check out CustomJSONData.Trees.