# The cscore Library [![](https://camo.githubusercontent.com/5ba2b22fa6ec9f7022d16858b52a6953f4fcf7fa/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f63732d7574696c2d636f6d2f6373636f72653f6c6162656c3d53686f7725323052656c6561736573267374796c653d666c61742d737175617265)](https://github.com/cs-util-com/cscore/releases) [![](https://camo.githubusercontent.com/266924e303e5ca32f0f773990b9407cd13e68d75/68747470733a2f2f696d672e736869656c64732e696f2f747769747465722f666f6c6c6f772f63737574696c5f636f6d3f6c6162656c3d53686f772532304e657773267374796c653d736f6369616c)](https://twitter.com/csutil_com) [**Website**](https://cs-util-com.github.io/cscore/) **•** [**GitHub**](https://github.com/cs-util-com/cscore) **•** [**Examples**](https://github.com/cs-util-com/cscore/raw/master/#-usage--examples) **•** [**Getting started**](https://github.com/cs-util-com/cscore/raw/master/#-getting-started) `cscore` is a lightweight library providing commonly used helpers & patterns for both your pure `C#` and `Unity` projects. Fewer 3rd party libraries and dependencies included in a project means fewer code and complexity which in the end leads to less bugs. On the other hand having zero dependencies very likely means that a few fundamental concepts and patterns you will have to implement over and over for each new project. This repo tries to provide a single source for a few simple to extend features to make sure these work great together and build up on each other. Some things like logging, communication of components, dependency and state management, easy to use IO and similar fundamental challenges in software are things all applications benefit from. This is why I think it makes sense to put this into a single compact `core` library with great test coverage and great documentation. And these two can go hand in hand, well written tests can serve as a easy to understand documentation + usage examples, which automatically stay up to date since they have to change with the code over time. That's how the unit tests in this project ensure all features are well tested and documented. **See below** for some extracts from these tests. To ensure full test coverage mutation testing is used (thanks to [Stryker](https://github.com/stryker-mutator/stryker-net)!) All components are loosly coupled so that components can be used individually when needed without deep knowledge about the full cscore library required. # Overview The following summary gives a quick overview of all library features: ### Pure C# Components The aim of the cscore package as to stay is slim/minimal as possible while including the feature and functionality typical projects would benefit from. * [Log](https://github.com/cs-util-com/cscore/raw/master/#logging) - A minimalistic logging wrapper + [AssertV2](https://github.com/cs-util-com/cscore/raw/master/#assertv2) to add saveguards anywhere in your logic * [EventBus](https://github.com/cs-util-com/cscore/raw/master/#The-EventBus) - Publish and subscribe to global events from anywhere in your code. Handles **1 million events a second** with minimal memory footprint! * [Injection Logic](https://github.com/cs-util-com/cscore/raw/master/#Injection-Logic) - A simple inversion of control pattern that does not rely on magic. Relies on the EventBus system, so it has the same speed as well! * [JSON Parsing](https://github.com/cs-util-com/cscore/raw/master/#JSON-Parsing) - Reading and writing JSON through a simple interface. Default implementation uses [Json.NET](https://github.com/JamesNK/Newtonsoft.Json) to ensure high performance * [REST Extensions](https://github.com/cs-util-com/cscore/raw/master/#REST-Extensions) - Extensions to simplify sending REST requests in as few lines as possible without limiting flexibility * [Directory & File Extensions](https://github.com/cs-util-com/cscore/raw/master/#directory--file-extensions) - To simplify handling files, folders and persisting data * Common String extension methods demonstrated in StringExtensionTests.cs * [Functional extensions](https://github.com/cs-util-com/cscore/raw/master/#IEnumerable-Extensions) and [Transducers](https://github.com/cs-util-com/cscore/raw/master/#Transducers) to allow functional data mapping (filter, map, reduce, ..) * Simple [statemachines](https://github.com/cs-util-com/cscore/raw/master/#Statemachines) that work on your existing classes * An asynchronous chainable [key value store](https://github.com/cs-util-com/cscore/raw/master/#KeyValueStore) (get & set) that can be used for anything from simple persistent settings to remote server/DB access * An [immutable datastore](https://github.com/cs-util-com/cscore/raw/master/#immutable-datastore) (Redux syntax) that includes undo/redo, timetravel (replay recordings) and a thunk middleware (dispatching async tasks) * A [JsonMerger](https://github.com/cs-util-com/cscore/raw/master/#JsonMerger) helper to allow simple Json merging and diffing logic that helps to update an instance of a class using a [Three-way merge](https://en.wikipedia.org/wiki/Merge_(version_control)#Three-way_merge) * An AutoMapper to map fields and attributes from one class to another using simple json serialization under the hood. * Many other helpful extension methods best demonstrated in HelperMethodTests.cs ### Additional Unity Components * [GameObject.Subscribe & MonoBehaviour.Subscribe](https://github.com/cs-util-com/cscore/raw/master/#gameobjectsubscribe--monobehavioursubscribe) - Listening to events while respecting the lifecycle of Unity objects * [MonoBehaviour Injection & Singletons](https://github.com/cs-util-com/cscore/raw/master/#monobehaviour-injection--singletons) - Using the injection logic to create and access Unity objects * [The Link Pattern](https://github.com/cs-util-com/cscore/raw/master/#the-link-pattern) - Making it easy to connect prefabs with code (and by that separate design & UI from your logic) * [The ViewStack Pattern](https://github.com/cs-util-com/cscore/raw/master/#the-viewstack-pattern) - Using GameObjects as separate views stacked in a parent object and controlled by a single ViewStack to introduce a simple solution for switching views and UI screens. * [MonoBehaviour.ExecuteDelayed & MonoBehaviour.ExecuteRepeated](https://github.com/cs-util-com/cscore/raw/master/#monobehaviourexecutedelayed--monobehaviourexecuterepeated) - Executing asynchronous actions delayed and/or repeated * [UnityWebRequest.SendV2](https://github.com/cs-util-com/cscore/raw/master/#unitywebrequestsendv2) - UnityWebRequest extension methods * [PlayerPrefsV2](https://github.com/cs-util-com/cscore/raw/master/#playerprefsv2) - Adds `SetBool`, `SetStringEncrypted` and more, see PlayerPrefsV2Tests.cs for all examples * [Running xUnit tests in Unity](https://github.com/cs-util-com/cscore/raw/master/#Running-xUnit-tests-in-Unity) - Execute your xUnit tests in Unity even in the built application to ensure everything works as expected in the production runtime # 💡 Usage & Examples See below for a full usage overview to explain the APIs with simple examples. ## Logging A lightweight zero config Log wrapper that is automatically **stripped from production** builds and can be combined with other logging libraries like Serilog for more complex usecases ```cs Log.d("I'm a log message"); Log.w("I'm a warning"); Log.e("I'm an error"); Log.e(new Exception("I'm an exception")); Log.w("I'm a warning with parmas", "param 1", 2, ".."); ``` This will result in the following output in the Log: ``` > I'm a log message at LogTests.TestBasicLogOutputExamples() > WARNING: I'm a warning at LogTests.TestBasicLogOutputExamples() >>> ERROR: I'm an error at Log.e(System.String error, System.Object[] args) c:\...\Log.cs:line 25 LogTests.TestBasicLogOutputExamples() c:\...\LogTests.cs:line 15 >>> EXCEPTION: System.Exception: I'm an exception at Log.e(System.Exception e, System.Object[] args) c:\...\Log.cs:line 29 LogTests.TestBasicLogOutputExamples() c:\...\LogTests.cs:line 16 > WARNING: I'm a warning with parmas : [[param 1, 2, ..]] at LogTests.TestBasicLogOutputExamples() ``` Creating logging-adapters is simple, the following logging-adapters can be used out of the box (and they can be seen as examples/templates): - [LogToConsole.cs](https://github.com/cs-util-com/cscore/raw/master/CsCore/PlainNetClassLib/src/Plugins/CsCore/com/csutil/logging/LogToConsole.cs) - The default logger which uses the normal `System.Console` - [LogToUnityDebugLog.cs](https://github.com/cs-util-com/cscore/raw/master/CsCore/CsCoreUnity/Plugins/CsCoreUnity/com/csutil/logging/LogToUnityDebugLog.cs) - The default logger when using the library in Unity projects, when using it `UnityEngine.Debug.Log` is used for all logging events - [LogToFile.cs](https://github.com/cs-util-com/cscore/raw/master/CsCore/PlainNetClassLib/src/Plugins/CsCore/com/csutil/logging/LogToFile.cs) - Allows to write all log outputs into a persisted file - [LogToMultipleLoggers.cs](https://github.com/cs-util-com/cscore/raw/master/CsCore/PlainNetClassLib/src/Plugins/CsCore/com/csutil/logging/LogToMultipleLoggers.cs) - Allows to use multiple loggers in parallel, e.g. to log to the console, a file and a custom error reporting system simultaneously The used logging-adapter can be set via `Log.instance = new MyCustomLogImpl();` Through this abstraction it becomes easy to later switch to more complex logging backends, e.g. the [Serilog logging library](https://github.com/serilog/serilog), while keeping your code unchanged. ### AssertV2 - `AssertV2` can be used anywhere in your code - Will be automatically removed/stripped from your production code - Can be configured to `Log.e` an error (the default) or to throw an exception - Use `AssertV2` in places where you would otherwise add a temporary `Log` line while testing. `AssertV2` can stay in your code and will let you know of any unexpected behaviour - Will automatically pause the Debugger if it fails while debugging ```cs AssertV2.IsTrue(1 + 1 == 3, "This assertion will fail"); ``` See [here](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/Plugins/CsCoreXUnitTests/com/csutil/tests/LogTests.cs#L63) for more examples. ### Log.MethodEntered & Log.MethodDone - Simple monitoring of method calls and method-timings to detect abnormal behavior - Easy to follow logging pattern for each method or method section where logging is helpful - Optional `maxAllowedTimeInMs` assertion at the end of the method - The returned `Stopwatch` can be used for additional logging if needed ```cs private void SomeExampleMethod1(string s, int i) { Stopwatch timing = Log.MethodEnteredWith("s=" + s, "i=" + i); { // .. here would be some method logic .. Thread.Sleep(3); } // .. as the last line in the tracked method add: Log.MethodDone(timing, maxAllowedTimeInMs: 50); // If the method needed more then 50ms an error is logged } ``` This will result in the following output in the Log: ```cs > --> LogTests.SomeExampleMethod1(..) : [[s=I am a string, i=123]] at LogTests.SomeExampleMethod1(System.String s, Int32 i) > <-- LogTests.SomeExampleMethod1(..) finished after 3 ms at LogTests.SomeExampleMethod1(System.String s, Int32 i) ``` ## The EventBus - Publish and subscribe to global events from anywhere in your code - Sends **1 million events in under 3 seconds** with minimal memory footprint! ([Tested](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/com/csutil/tests/EventBusTests.cs#L158) on my mid-range laptop - will add some more detailed numbers soon) ```cs // The EventBus can be accessed via EventBus.instance EventBus eventBus = EventBus.instance; string eventName = "TestEvent1"; //Register a subscriber for the eventName that gets notified when ever an event is send: object subscriber1 = new object(); // can be of any type eventBus.Subscribe(subscriber1, eventName, () => { Log.d("The event was received!"); }); // Now send out an event: eventBus.Publish(eventName); // When subscribers dont want to receive events anymore they can unsubscribe: eventBus.Unsubscribe(subscriber1, eventName); ``` __Rule of thumb__: Only use an `EventBus` if you can't exactly tell who will listen to the published events. Do not use the `EventBus` to pass an event from x to y if you know exactly who x and y will be! Artificially separating 2 components that tightly belong together does not help ## Injection Logic - A simple inversion of control pattern with the main call being `MyClass1 x = IoC.inject.Get(this);` where `this` is the requesting entity - Relies on the EventBus system, so its fast with minimal memory footprint as well (got about a million injections in ~3 sec). - Free of any unpredicable magic via anotations - I tried to keep the injection API as simple as possible, existing libraries often tend to overcomplicate things in my opinion - Lazy loading, singletons and transient types (every inject request creates a new instance) are all easily implementable via `.RegisterInjector`, see examples below: ```cs // The default injector can be accessed via IoC.inject Injector injector = IoC.inject; // Requesting an instance of MyClass1 will fail because no injector registered yet to handle requests for the MyClass1 type: Assert.Null(injector.Get(this)); // Setup an injector that will always return the same instance for MyClass1 when IoC.inject.Get() is called: MySubClass1 myClass1Singleton = new MySubClass1(); injector.SetSingleton(myClass1Singleton); // Internally .SetSingleton() will register an injector for the class like this: injector.RegisterInjector(new object(), (caller, createIfNull) => { // Whenever injector.Get is called the injector always returns the same instance: return myClass1Singleton; // Here the singleton could be lazy loaded }); // Now calling IoC.inject.Get() will always result in the same instance: MyClass1 myClass1 = injector.Get(this); Assert.Same(myClass1Singleton, myClass1); // Its the same object reference ``` Another extended example usage can be found in [`InjectionTests.ExampleUsage2()` (see here)](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/com/csutil/tests/InjectionTests.cs#L40) ## IEnumerable Extensions For common tasks on IEnumerables cscore provides methods like `Map` (same as LINQs Select), `Reduce` (same as LINQs Aggregate) and `Filter` (same as LINQs Where) but also `IsNullOrEmpty` and `ToStringV2` which are explained in this simple example: ```cs IEnumerable myStrings = new List() { "1", "2", "3", "4", "5" }; IEnumerable convertedToInts = myStrings.Map(s => int.Parse(s)); IEnumerable filteredInts = convertedToInts.Filter(i => i <= 3); // Keep 1,2,3 Assert.False(filteredInts.IsNullOrEmpty()); Log.d("Filtered ints: " + filteredInts.ToStringV2(i => "" + i)); // "[1, 2, 3]" int sumOfAllInts = filteredInts.Reduce((sum, i) => sum + i); // Sum up all ints Assert.Equal(6, sumOfAllInts); // 1+2+3 is 6 ``` More usage examples can be found in the [HelperMethodTests.cs](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/com/csutil/tests/HelperMethodTests.cs) ## Transducers Transducers allow to do similar things as the functional concepts like ``Filter``, ``Map`` and ``Reduce``. The main idea of transducers is to make this functional style as efficient as possible, iterating through the target structure only once and bulding a pipeline still of the same easy to understand functional building blocks. A first example that uses only ``Filter`` will give a better idea how this looks like: ```cs List testData = new List() { 1, 2, 3, 4, 5, 6, 7, 8 }; var filter1 = Transducers.NewFilter(x => x > 4); var filter2 = Transducers.NewFilter(x => x % 2 != 0); { List result = testData.FilterToList(Transducers.Compose(filter1, filter2)); Assert.Equal(2, result.Count()); // 5 and 7 will be left Assert.Equal(5, result.First()); Assert.Equal(7, result.Last()); } { // without Transducers.Compose the filters have to be chained manually: List result = testData.FilterToList(x => (filter1(filter2(x)))); Assert.Equal(2, result.Count()); // 5 and 7 will be left Assert.Equal(5, result.First()); Assert.Equal(7, result.Last()); } ``` A more complex example that uses ``Filter``, ``Map`` and ``Reduce``: ```cs List testData = newExampleList(); Transducer filter1 = Transducers.NewFilter(x => x != null); Transducer filter2 = Transducers.NewFilter(x => x.someInt > 1); Transducer mapper = Transducers.NewMapper(x => x.someInt); Func sumReducer = (total, x) => total + x; // Create the reducer by composing the transducers: var sum = testData.ReduceTo(x => filter1(filter2(mapper(x))), sumReducer, seed: 0); Assert.Equal(6, sum); ``` More examples can be found in the [TransducerTests.cs](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/com/csutil/tests/datastructures/TransducerTests.cs). The syntax is still work in progress and I am happy for any suggestions how to improve this. And there are some great [related sources](https://jrsinclair.com/articles/2019/magical-mystical-js-transducers/) you can read to learn more about Transducers. ## JSON Parsing - The `JsonWriter` and `JsonReader` interfaces are an abstraction that should be flexiable enough to be used for most usecases. - The underlying implementation can easily be swapped if needed and the default implementation uses [Json.NET](https://github.com/JamesNK/Newtonsoft.Json). ```cs class MyClass1 { // example class with a field and a property public string myString; public string myString2 { get; set; } } MyClass1 x1 = new MyClass1() { myString = "abc", myString2 = "def" }; // Generate a json object from the object that includes all public fields and props: string jsonString = JsonWriter.GetWriter().Write(x1); // Parse the json string back into a second instance x2 and compare both: MyClass1 x2 = JsonReader.GetReader().Read(jsonString); Assert.Equal(x1.myString, x2.myString); Assert.Equal(x1.myString2, x2.myString2); ``` ## Directory & File Extensions The [DirectoryInfo](https://docs.microsoft.com/en-us/dotnet/api/system.io.directoryinfo) and [FileInfo](https://docs.microsoft.com/en-us/dotnet/api/system.io.fileinfo) classes already provide helpful interfaces to files and directories and the following extensions improve the usability if these classes: ```cs // Get a directory to work in: DirectoryInfo myDirectory = EnvironmentV2.instance.GetAppDataFolder(); Log.d("The directory path is: " + myDirectory.FullPath()); // Get a non-existing child directory var childDir = myDirectory.GetChildDir("MyExampleSubDirectory1"); // Create the sub directory: childDir.CreateV2(); // myDirectory.CreateSubdirectory("..") works too // Rename the directory: childDir.Rename("MyExampleSubDirectory2"); // Get a file in the child directory: FileInfo file1 = childDir.GetChild("MyFile1.txt"); // Saving and loading from files: string someTextToStoreInTheFile = "Some text to store in the file"; file1.SaveAsText(someTextToStoreInTheFile); string loadedText = file1.LoadAs(); // loading JSON would work as well Assert.Equal(someTextToStoreInTheFile, loadedText); // Deleting directories: Assert.True(childDir.DeleteV2()); // (Deleting non-existing directories would returns false) // Check that the directory no longer exists: Assert.False(childDir.IsNotNullAndExists()); ``` ## StateMachines A statemachine in it's simplest form is a current state and a set of allowed state transitions. Transitioning from state 1 to 2 can be done in a single short [method](https://github.com/cs-util-com/cscore/raw/master/CsCore/PlainNetClassLib/src/Plugins/CsCore/com/csutil/datastructures/StateMachine.cs#L14) on the set of allowed transitions. Here an example statemachine: ```cs // First define a set of allowed transitions to define the state machine: Dictionary> stateMachine = new Dictionary>(); stateMachine.AddToValues(MyStates.MyState1, MyStates.MyState2); // 1 => 2 allowed stateMachine.AddToValues(MyStates.MyState2, MyStates.MyState3); // 2 => 3 allowed // Initialize a state-machine: MyStates currentState = MyStates.MyState1; // It is possible to listen to state machine transitions: StateMachine.SubscribeToAllTransitions(new object(), (machine, oldState, newState) => { Log.d("Transitioned from " + oldState + " to " + newState); }); // And its possible to listen only to specific transitions: StateMachine.SubscribeToTransition(new object(), MyStates.MyState1, MyStates.MyState2, delegate { Log.d("Transitioned from 1 => 2"); }); // Transition the state-machine from state 1 to 2: currentState = stateMachine.TransitionTo(currentState, MyStates.MyState2); Assert.Equal(MyStates.MyState2, currentState); // Invalid transitions throw exceptions (current state is 2): Assert.Throws(() => { currentState = stateMachine.TransitionTo(currentState, MyStates.MyState1); }); ``` More [statemachine examples can be found here](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/Plugins/CsCoreXUnitTests/com/csutil/tests/StateMachineTests.cs#L17). ## KeyValueStore Provides an async chainable key value store (get & set) that can be used for simple persistent settings but also for remote server/DB access. Different store implementations are included for some common use cases: * InMemoryKeyValueStore - Keeps a very fast in memory dictionary for fastest possible read write * FileBasedKeyValueStore - Enables persisting values permanently * RetryKeyValueStore - A retry layer using exponential backoff * ExceptionWrapperKeyValueStore - To handle exceptions of an inner store (e.g. if a connection to a remote server throws a timeout exception this can be handled to return the cached local value instead) ```cs IKeyValueStore store = new InMemoryKeyValueStore(); string myKey1 = "myKey1"; MyClass1 x1 = new MyClass1() { myString1 = "Abc", myString2 = "Abc2" }; store.Set(myKey1, x1); MyClass1 x2 = store.Get(myKey1, defaultValue: null).Result; Assert.Equal(x1.myString1, x2.myString1); Assert.Equal(x1.myString2, x2.myString2); ``` The KeyValueStores can be chained so that if the outer store does not find the element it will ask the next inner store. This allows to have fast stores like the ``InMemoryKeyValueStore`` on the most outer level and the slowest stores like the connection to the database on the most inner one: ```cs string myKey1 = "test123"; MyClass1 x1 = new MyClass1() { myString1 = "Abc", myString2 = "Abc2" }; // Create a fast memory store and combine it with a LiteDB store that is persisted to disk: IKeyValueStore store = new InMemoryKeyValueStore().WithFallbackStore(new FileBasedKeyValueStore(EnvironmentV2.instance.GetOrAddTempFolder("SomeFolder123"))); await store.Set(myKey1, x1); MyClass1 x2 = await store.Get(myKey1, null); Assert.Equal(x1.myString1, x2.myString1); Assert.Equal(x1.myString2, x2.myString2); ``` More examples [can be found here](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/Plugins/CsCoreXUnitTests/com/csutil/tests/datastructures/KeyValueStoreTests.cs). ## Immutable DataStore * It uses the Redux syntax and core principles to not reinvent a matured and well proven wheel * Enables undo/redo of all dispatched actions out of the box without any additional work * Enables timetravel to enable recording the full userinteraction and replaying it later to get back into the same state * Includes a thunk middleware to dispatcht async tasks (e.g. talking to a remote server) See [this example for a first introduction](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/Plugins/CsCoreXUnitTests/com/csutil/tests/model/immutable/DataStoreExample1.cs#L11) including an example datamodel, example actions and some listeners that are informed when the datamodel changes. See [here for additional more complex examples](https://github.com/cs-util-com/cscore/tree/master/CsCore/xUnitTests/src/Plugins/CsCoreXUnitTests/com/csutil/tests/model/immutable) which include the other features like undo/redo, middlewares and server synchronization. ## JsonMerger [Json merging and diffing logic](https://github.com/cs-util-com/cscore/raw/master/CsCore/xUnitTests/src/Plugins/CsCoreXUnitTests/com/csutil/tests/json/JsonDiffAndMergeTests.cs#L14) that helps to update an instance of a class using a [Three-way merge](https://en.wikipedia.org/wiki/Merge_(version_control)#Three-way_merge). Here an example: ```cs MyClass1 originalObj = new MyClass1() { myString = "abc", myString2 = "def" }; MyClass1 copy1 = originalObj.DeepCopyViaJson(); copy1.myString = "abcd"; copy1.complexField = new MyClass1() { myString = "123", myString2 = "456" }; copy1.complexField.complexList = new List() { new MyClass1() { myString = "listEntry1" } }; MyClass1 copy2 = originalObj.DeepCopyViaJson(); copy2.myString2 = "defg"; var merge = MergeJson.Merge(originalObj, copy1, copy2); Assert.False(merge.hasMergeConflict); // Parse the merged result back into a MyClass1 object: MyClass1 mergeResult1 = merge.GetResult(); // The changes from both copies were merged correctly: Assert.Equal(copy1.myString, mergeResult1.myString); Assert.Equal(copy2.myString2, mergeResult1.myString2); ``` ## REST Extensions ```cs // The property names are based on the https://httpbin.org/get json response: class HttpBinGetResp { public string origin { get; set; } public Dictionary headers { get; set; } } RestRequest request = new Uri("https://httpbin.org/get").SendGET(); // Send the request and parse the response into the HttpBinGetResp class: HttpBinGetResp response = await request.GetResult(); Log.d("Your external IP is " + response.origin); ``` A more complex REST example can be found in the `WeatherReportExamples` test class. It uses your IP to detect the city name you are located in and then sends a weather report request to MetaWeather.com: ```cs var ipLookupResult = await IpApiCom.GetResponse(); string yourCity = ipLookupResult.city; var cityLookupResult = await MetaWeatherLocationLookup.GetLocation(yourCity); int whereOnEarthIDOfYourCity = cityLookupResult.First().woeid; var weatherReports = await MetaWeatherReport.GetReport(whereOnEarthIDOfYourCity); var currentWeather = weatherReports.consolidated_weather.Map(r => r.weather_state_name); Log.d("The weather today in " + yourCity + " is: " + currentWeather.ToStringV2()); ``` # Unity Component Examples There are additional components specifically created for Unity, that will be explained below: ## `GameObject` and `MonoBehaviour` Extensions Some helper methods are added when the com.csutil namespace is imported to help with scene graph manipulation via code. The added extension methods are `GetParent`, `AddChild`, `GetOrAddChild`, `GetOrAddComponent`, `Destroy` and `IsDestroyed`. Here are some examples: ```cs GameObject myGo = new GameObject(); // Adding children GameObjects via AddChild: GameObject myChildGo = myGo.AddChild(new GameObject()); // Getting the parent of the child via GetParent: Assert.AreSame(myGo, myChildGo.GetParent()); // Lazy-initialization of the GameObject in case it does not yet exist: GameObject child1 = myGo.GetOrAddChild("Child 1"); // Lazy-initialization of the Mono in case it does not yet exist: MyExampleMono1 myMono1 = child1.GetOrAddComponent(); // Calling the 2 methods again results always in the same mono: var myMono1_ref2 = myGo.GetOrAddChild("Child 1").GetOrAddComponent(); Assert.AreSame(myMono1, myMono1_ref2); myGo.Destroy(); // Destroy the gameobject Assert.IsTrue(myGo.IsDestroyed()); // Check if it was destroyed ``` ## `GameObject.Subscribe` & `MonoBehaviour.Subscribe` There are extension methods for both `GameObjects` and `Behaviours` which internally handle the lifecycle of their subscribers correctly. If a `GameObject` for example is currently not active or was destroyed the published events will not reach it. ```cs // GameObjects can subscribe to events: var myGameObject = new GameObject("MyGameObject 1"); myGameObject.Subscribe("MyEvent1", () => { Log.d("I received the event because I'm active"); }); // Behaviours can subscribe to events too: var myExampleMono = myGameObject.GetOrAddComponent(); myExampleMono.Subscribe("MyEvent1", () => { Log.d("I received the event because I'm enabled and active"); }); // The broadcast will reach both the GameObject and the MonoBehaviour: EventBus.instance.Publish("MyEvent1"); ``` ## MonoBehaviour Injection & Singletons Often specific `MonoBehaviours` should only exist once in the complete scene, for this scenario `IoC.inject.GetOrAddComponentSingleton()` and `IoC.inject.GetComponentSingleton()` can be used. ```cs // Initially there is no MonoBehaviour registered in the system: Assert.IsNull(IoC.inject.Get(this)); // Calling GetOrAddComponentSingleton will create a singleton: MyExampleMono1 x1 = IoC.inject.GetOrAddComponentSingleton(this); // Calling GetOrAddComponentSingleton again now returns the singleton: MyExampleMono1 x2 = IoC.inject.GetOrAddComponentSingleton(this); Assert.AreSame(x1, x2); // Both references point to the same object // Calling the default IoC.inject.Get will also return the same singleton: MyExampleMono1 x3 = IoC.inject.Get(this); Assert.AreSame(x1, x3); // Both references point to the same object ``` Calling `GetOrAddComponentSingleton` will create a singleton. The parent gameobject of this singleton will be created together with it in the scene. The location of the singleton will be: `"Singletons" GameObject` -> `"MyExampleMono1" GameObject` -> `MyExampleMono1` This way all created singletons will be created and grouped together in the `"Singletons" GameObject` and accessible like any other MonoBehaviour as well. ### Scriptable Object Injection & Singletons Scriptable objects are ment as data containers created not at runtime but at editor time to store configuration data and use it in the editor UI or load it during runtime. * The scriptable object consists of the class that extends `ScriptableObject` and the instance file that typically is created via the [CreateAssetMenu](https://docs.unity3d.com/ScriptReference/CreateAssetMenuAttribute.html) annotation or via an editor script (see [ScriptableObject.CreateInstance](https://docs.unity3d.com/ScriptReference/ScriptableObject.CreateInstance.html)). * This allows to have many parallel instance files for a scriptable object that contain different configurations. These asset files can be loaded during runtime when placed in a [Resources folder](https://unity3d.com/learn/tutorials/topics/best-practices/resources-folder) or can be linked directly in prefabs and Unity scenes in the Editor UI. If scriptable object instances have to be dynamically loaded during runtime, the following example can help to avoid loading multiple different instances for the same ScriptableObject subclass into memory at once: ```cs // Load a ScriptableObject instance and set it as the singleton: var path = "MyExampleScriptableObject_Instance1.asset"; MyExampleScriptableObject x1 = ResourcesV2.LoadScriptableObjectInstance(path); IoC.inject.SetSingleton(x1); // Now that the singleton is set this instance is always returned for the ScriptableObject class: MyExampleScriptableObject x2 = IoC.inject.Get(this); Assert.AreSame(x1, x2); ``` ## The `Link` Pattern Connecting prefabs created by designers with internal logic (e.g what should happen when the user presses Button 1) often is beneficial to happen in a central place. To access all required parts of the prefab the `Link` pattern and helper methods like `gameObject.GetLinkMap()` can be used: ```cs // Load a prefab that contains Link MonoBehaviours: GameObject prefab = ResourcesV2.LoadPrefab("ExamplePrefab1.prefab"); // Collect all Link MonoBehaviours in the prefab: Dictionary links = prefab.GetLinkMap(); // In the Prefab Link-Monos are placed in all GameObjects that need // to be accessed by the code. Links have a id to reference them: // Via the Link.id the objects can quickly be accessed: Assert.IsNotNull(links.Get("Button 1")); // The GameObject "Button 1" contains a Button-Mono that can be accessed: Button button1 = links.Get