CitiesHarmony.API misuse (TypeLoadException on load)

[drok]

Mods that do not use the API mechanisms for checking that Harmony is installed before use will eventually be denied Harmony access.

Mods should use IsHarmonyInstalled and DoOnHarmonyReady() before creating Harmony instances. This allows the API to ensure that if the Harmony Library is not installed at the time the mod is ready to use it, it will be subscribed and the mod be notified when ready.

The alternative is that attempting to create a Harmony instance without the assembly present will cause an TypeLoadException for a few users (those who install the troubled mod for the first time, not having any other Harmony mods already installed).

There are many mods that do not use the DoOnHarmonyReady() protocol currently, and in order to provide a smoother transition, the Harmony Mod only warns. Currently it is planned that at version v1.1 of the Harmony mod, the warnings will become denials for those mods that still misuse the interface.

Note this issue is similar to #9 but it happens not on mod enumeration, but at OnEnable(), OnLevelLoaded() or wherever the mod attempts to instantiate Harmony. The error is TypeLoadException, not ReflectionTypeLoadException as in #9.

Practical effects

When loading a city with the mod enabled, but without Harmony present, the CitiesHarmony.API is expected to pop up a warning explaining that Harmony is required but is not installed. Instead, the following AN ERROR HAS OCCURRED unhandled exception panel is shown to the unsuspecting player (this error doesn't give any actionable help):

The Mod D:\Users\Radu\AppData\Local\Colossal Order\Cities_Skylines\Addons\Mods\PopulationDemographics [CitiesHarmony.API.dll, PopulationDemographics.dll] has caused an error [ModException]

Details:
System.TypeLoadException: A type load exception has occurred.
  at LoadingWrapper.OnLevelLoaded (UpdateMode mode) [0x00000] in <filename unknown>:0 

How to test if your mod is affected

1. First Time User Scenario (user forgot to also subscribe the dependency Harmony):
   1. Subscribe both your mod and Harmony.
   2. delete the Harmony mod folder from the workshop folder.
   3. Load a city
   4. Observe crash displayed in "AN ERROR OCCURRED" exception window
2. User of local mods. (Epic Games players; content creators who require a stable, un-updated set of mods for production work; Players who run the game offline, on airplanes, for example; generally new players who are unaware of the Harmony workings):
   1. Subscribe your mod.
   2. Copy your mod to local %LOCALAPPDATA%. Do not copy the Harmony folder locally.
   3. Start the game with --noWorkshop.
   4. Observe crash displayed in "AN ERROR OCCURRED" exception window
3. Player who switches from boformer's Harmony to the redesigned (this) Harmony (users who want to access the Harmony Report to diagnose their mod collection issue):
   1. Subscribe your mod and boformer's Harmony.
   2. Unsubscribe boformer's Harmony
   3. Subscribe Harmony (redesigned)
   4. Start the game normally.
   5. The crash will be logged in the Harmony Report.

[drok]

Mods affected:

(partial list, there may be others I'm unaware of)

• Population Demographics by @rcav8tr. Reported as rcav8tr/PopulationDemographics#2
• Building Spawn Points by @MacSergey - no bug filed because the author has deleted previous bug reports without explanation. Uncooperative author.
• Network Multitool by @MacSergey - no bug filed. Uncooperative author.
  • Node Controller Renewal by @MacSergey - no bug filed. Uncooperative author.
  • Intersection Marking Tool by @MacSergey - no bug filed. Uncooperative author.

[drok]

Issue is detected and reported as of 4caa80e

[ghost]

Population Demographics and Building Usage have been updated to gracefully handle missing Harmony mod.