Newtonsoft Json.NET for Unity3D

Newtonsoft Json.NET is a de facto standard JSON library in .NET ecosystem. But it doesn't support Unity3D, so it's a little bit hard to use JSON.NET just after getting Json.NET package. This package is for Unity3D programmers that need to use latest Json.NET in Unity3D.

Where can I get it?

Visit Release page to get latest Json.NET unity-package.

To use this library in IL2CPP build settings, you need to add link.xml to your project's asset folder. For detailed information about link.xml, read unity manual about this.

What's the deal?

Unity3D has old-fashioned and bizarre .NET Framework like these :)

• Basically based on .NET Framework 3.5 (forked Mono 2.6)
• Runtime lacks some types in .NET Framework 3.5 (like System.ComponentModel.AddingNewEventHandler)
• For iOS, dynamic code emission is forbidden by Apple AppStore.

Because Newtonsoft Json.NET doesn't handle these limitations, errors will welcome you when you use official Json.NET dll targetting .NET 3.5 Framework.

What's done?

Following works are done to make Json.NET support Unity3D.

• Based on Newtonsoft Json.NET 9.
• Disable IL generation to work well under AOT environment like iOS.
• Remove code related with System.ComponentModel.
• Remove System.Data and EntityKey support.
• Remove XML support.
• Remove DiagnosticsTraceWriter support.
• Workaround for differences between Microsoft.NET & Unity3D-Mono.NET

For Unity.Lite version, additional works are done to make more lite.

• Remove JsonLinq, JPath (JToken, ...)
• Remove Bson

Unit Test

Tests in Json.NET are updated to be able to run under UnityEditor Test Runner. All tests pass under Microsoft .NET 3.5 but with UnityEditor some of them fail because there are not-implemented features and bugs in Unity3D-Mono framework.

Test Result:

Profile	✅ Passed	❌ Failed	⚪ Ignored
Microsoft.NET	1605	0	1
Unity3D-Mono	1592	13	1

Detailed Description is here to tell you what failed and why.

Unity Compatibility

This library is tested on Unity 4.7, 5.2 and 5.3. For AOT environment like iOS, you need to use IL2CPP instead of obsolute Mono-AOT because IL2CPP handles generic code better than Mono-AOT. With Mono-AOT configuration, AOT related exception would be thrown.

For windows store build, there is a compatibility issue related with UWP. If you have a problem, please read workaround for UWP.

FAQ

Q: MissingMethodException is thrown for ComponentModel.TypeConverter.

MissingMethodException: Method not found:
Default constructor not found...ctor() of System.ComponentModel.TypeConverter.

Make sure that link.xml is added to your project.

Q: ExecutionEngineException is thrown in calling CreateValueInternal.

xecutionEngineException:
  Attempting to call method 'CLASS::.cctor' for which no ahead of time (AOT) code was generated.
at System.Reflection.MonoCMethod.Invoke (...)
at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.CreateValueInternal

This exception is thrown because Unity3D strips out unnecessary classes which are actually used by serialization. To fix this problem, just put new CLASS() in your code to prevent Unity3D from removing the class.

Reference: TroubleShootingIPhone

Q: ArgumentNullException is thrown in calling CreateParameterizedConstructor.

ArgumentNullException: Argument cannot be null.
Parameter name: method
at Newtonsoft.Json.Utilities.ValidationUtils.ArgumentNotNull (...)
at Newtonsoft.Json.Utilities.LateBoundReflectionDelegateFactory.CreateParameterizedConstructor (...)

This is similar with the previous case. But this case is tricky because this is caused by Json.NET internal classes such as CollectionWrapper<T>. To fix this problem, put AotHelper.EnsureList<T>() if you use HashSet<T> or AotHelper.EnsureDictionary<TKey, TValue>() if you use Dictionary<TKey, TValue> in working class.