[C#] support Object API (#5710)

* [C#] support Object API

* fix sign-compare

* fix indent

* add new line before for loop.

* using auto whenever possible

* reduce the amout of blank lines.

* wip: support vectors of union

* done: support unions of vectors

* set C# version to 4.0
* remove null propagation operator
* remove auto property initializer
* remove expression-bodied method
* remove pattern matching

* add Example2 to NetTest.sh

* separate JavaUsage.md and CsharpUsage.md from JavaCsharpUsage.md

* add C# Object based API notes.

* support vs2010.

* remove range based for loop.

* remove System.Linq

* fix indent

* CreateSharedString to CreateString

* check shared attribute

* snake case

5 files changed, 177 insertions, 77 deletions

diff --git a/docs/source/JavaCsharpUsage.md b/docs/source/CsharpUsage.md
index 102ce371..90a757fb 100644
--- a/docs/source/JavaCsharpUsage.md
+++ b/docs/source/CsharpUsage.md
@@ -1,54 +1,30 @@
-Use in Java/C#    {#flatbuffers_guide_use_java_c-sharp}
+Use in C#    {#flatbuffers_guide_use_c-sharp}
 ==============
 
 ## Before you get started
 
-Before diving into the FlatBuffers usage in Java or C#, it should be noted that
+Before diving into the FlatBuffers usage in C#, it should be noted that
 the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
-general FlatBuffers usage in all of the supported languages (including both Java
-and C#). This page is designed to cover the nuances of FlatBuffers usage,
-specific to Java and C#.
+general FlatBuffers usage in all of the supported languages (including C#).
+This page is designed to cover the nuances of FlatBuffers usage,
+specific to C#.
 
 You should also have read the [Building](@ref flatbuffers_guide_building)
 documentation to build `flatc` and should be familiar with
 [Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
 [Writing a schema](@ref flatbuffers_guide_writing_schema).
 
-## FlatBuffers Java and C-sharp code location
-
-#### Java
-
-The code for the FlatBuffers Java library can be found at
-`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the
-[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/
-java/com/google/flatbuffers).
-
-#### C-sharp
+## FlatBuffers C-sharp code location
 
 The code for the FlatBuffers C# library can be found at
 `flatbuffers/net/FlatBuffers`. You can browse the library on the
 [FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/
 FlatBuffers).
 
-## Testing the FlatBuffers Java and C-sharp libraries
+## Testing the FlatBuffers C-sharp libraries
 
 The code to test the libraries can be found at `flatbuffers/tests`.
 
-#### Java
-
-The test code for Java is located in [JavaTest.java](https://github.com/google
-/flatbuffers/blob/master/tests/JavaTest.java).
-
-To run the tests, use either [JavaTest.sh](https://github.com/google/
-flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/
-google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating
-system.
-
-*Note: These scripts require that [Java](https://www.oracle.com/java/index.html)
-is installed.*
-
-#### C-sharp
-
 The test code for C# is located in the [FlatBuffers.Test](https://github.com/
 google/flatbuffers/tree/master/tests/FlatBuffers.Test) subfolder. To run the
 tests, open `FlatBuffers.Test.csproj` in [Visual Studio](
@@ -63,62 +39,44 @@ by running the following commands from inside the `FlatBuffers.Test` folder:
   mono Assert.exe
 ~~~
 
-## Using the FlatBuffers Java (and C#) library
+## Using the FlatBuffers C# library
 
 *Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
-example of how to use FlatBuffers in Java or C#.*
+example of how to use FlatBuffers in C#.*
 
-FlatBuffers supports reading and writing binary FlatBuffers in Java and C#.
+FlatBuffers supports reading and writing binary FlatBuffers in C#.
 
-To use FlatBuffers in your own code, first generate Java classes from your
-schema with the `--java` option to `flatc`. (Or for C# with `--csharp`).
+To use FlatBuffers in your own code, first generate C# classes from your
+schema with the `--csharp` option to `flatc`.
 Then you can include both FlatBuffers and the generated code to read
 or write a FlatBuffer.
 
-For example, here is how you would read a FlatBuffer binary file in Java:
+For example, here is how you would read a FlatBuffer binary file in C#:
 First, import the library and generated code. Then, you read a FlatBuffer binary
 file into a `byte[]`.  You then turn the `byte[]` into a `ByteBuffer`, which you
-pass to the `getRootAsMyRootType` function:
-
-*Note: The code here is written from the perspective of Java. Code for both
-languages is both generated and used in nearly the exact same way, with only
-minor differences. These differences are
-[explained in a section below](#differences_in_c-sharp).*
+pass to the `GetRootAsMyRootType` function:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
-    import MyGame.Example.*;
-    import com.google.flatbuffers.FlatBufferBuilder;
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs}
+    using MyGame.Example;
+    using FlatBuffers;
 
     // This snippet ignores exceptions for brevity.
-    File file = new File("monsterdata_test.mon");
-    RandomAccessFile f = new RandomAccessFile(file, "r");
-    byte[] data = new byte[(int)f.length()];
-    f.readFully(data);
-    f.close();
-
-    ByteBuffer bb = ByteBuffer.wrap(data);
-    Monster monster = Monster.getRootAsMonster(bb);
+    byte[] data = File.ReadAllBytes("monsterdata_test.mon");
+
+    ByteBuffer bb = new ByteBuffer(data);
+    Monster monster = Monster.GetRootAsMonster(bb);
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Now you can access the data from the `Monster monster`:
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
-    short hp = monster.hp();
-    Vec3 pos = monster.pos();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs}
+    short hp = monster.Hp;
+    Vec3 pos = monster.Pos;
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-<a name="differences_in_c-sharp">
-#### Differences in C-sharp
-</a>
-
-C# code works almost identically to Java, with only a few minor differences.
-You can see an example of C# code in
-`tests/FlatBuffers.Test/FlatBuffersExampleTests.cs` or
-`samples/SampleBinary.cs`.
-
-First of all, naming follows standard C# style with `PascalCasing` identifiers,
+C# code naming follows standard C# style with `PascalCasing` identifiers,
 e.g. `GetRootAsMyRootType`. Also, values (except vectors and unions) are
-available as properties instead of parameterless accessor methods as in Java.
+available as properties instead of parameterless accessor methods.
 The performance-enhancing methods to which you can pass an already created
 object are prefixed with `Get`, e.g.:
 
@@ -147,13 +105,11 @@ To use it:
     array.
 -   Instead of calling standard generated method,
     e.g.: `Monster.createTestarrayoftablesVector`,
-    call `CreateSortedVectorOfMonster` in C# or
-    `createSortedVectorOfTables` (from the `FlatBufferBuilder` object) in Java,
+    call `CreateSortedVectorOfMonster` in C#
     which will first sort all offsets such that the tables they refer to
     are sorted by the key field, then serialize it.
 -   Now when you're accessing the FlatBuffer, you can use
     the `ByKey` accessor to access elements of the vector, e.g.:
-    `monster.testarrayoftablesByKey("Frodo")` in Java or
     `monster.TestarrayoftablesByKey("Frodo")` in C#,
     which returns an object of the corresponding table type,
     or `null` if not found.
@@ -165,8 +121,34 @@ To use it:
 ## Text parsing
 
 There currently is no support for parsing text (Schema's and JSON) directly
-from Java or C#, though you could use the C++ parser through native call
+from C#, though you could use the C++ parser through native call
 interfaces available to each language. Please see the
 C++ documentation for more on text parsing.
 
+## Object based API
+
+FlatBuffers is all about memory efficiency, which is why its base API is written
+around using as little as possible of it. This does make the API clumsier
+(requiring pre-order construction of all data, and making mutation harder).
+
+For times when efficiency is less important a more convenient object based API
+can be used (through `--gen-object-api`) that is able to unpack & pack a
+FlatBuffer into objects and standard System.Collections.Generic containers, allowing for convenient
+construction, access and mutation.
+
+To use:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.cs}
+    // Deserialize from buffer into object.
+    MonsterT monsterobj = GetMonster(flatbuffer).UnPack();
+
+    // Update object directly like a C# class instance.
+    Console.WriteLine(monsterobj.Name);
+    monsterobj.Name = "Bob";  // Change the name.
+
+    // Serialize into new flatbuffer.
+    FlatBufferBuilder fbb = new FlatBufferBuilder(1);
+    fbb.Finish(Monster.Pack(fbb, monsterobj).Value);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 <br>
diff --git a/docs/source/FlatBuffers.md b/docs/source/FlatBuffers.md
index 45ffbf22..2a2133f7 100644
--- a/docs/source/FlatBuffers.md
+++ b/docs/source/FlatBuffers.md
@@ -130,7 +130,9 @@ sections provide a more in-depth usage guide.
 -   How to [write a schema](@ref flatbuffers_guide_writing_schema).
 -   How to [use the generated C++ code](@ref flatbuffers_guide_use_cpp) in your
     own programs.
--   How to [use the generated Java/C# code](@ref flatbuffers_guide_use_java_c-sharp)
+-   How to [use the generated Java code](@ref flatbuffers_guide_use_java)
+    in your own programs.
+-   How to [use the generated C# code](@ref flatbuffers_guide_use_c-sharp)
     in your own programs.
 -   How to [use the generated Kotlin code](@ref flatbuffers_guide_use_kotlin)
         in your own programs.
diff --git a/docs/source/JavaUsage.md b/docs/source/JavaUsage.md
new file mode 100644
index 00000000..30ba0613
--- /dev/null
+++ b/docs/source/JavaUsage.md
@@ -0,0 +1,114 @@
+Use in Java    {#flatbuffers_guide_use_java}
+==============
+
+## Before you get started
+
+Before diving into the FlatBuffers usage in Java, it should be noted that
+the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to
+general FlatBuffers usage in all of the supported languages (including Java).
+This page is designed to cover the nuances of FlatBuffers usage,
+specific to Java.
+
+You should also have read the [Building](@ref flatbuffers_guide_building)
+documentation to build `flatc` and should be familiar with
+[Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and
+[Writing a schema](@ref flatbuffers_guide_writing_schema).
+
+## FlatBuffers Java code location
+
+The code for the FlatBuffers Java library can be found at
+`flatbuffers/java/com/google/flatbuffers`. You can browse the library on the
+[FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/
+java/com/google/flatbuffers).
+
+## Testing the FlatBuffers Java libraries
+
+The code to test the libraries can be found at `flatbuffers/tests`.
+
+The test code for Java is located in [JavaTest.java](https://github.com/google
+/flatbuffers/blob/master/tests/JavaTest.java).
+
+To run the tests, use either [JavaTest.sh](https://github.com/google/
+flatbuffers/blob/master/tests/JavaTest.sh) or [JavaTest.bat](https://github.com/
+google/flatbuffers/blob/master/tests/JavaTest.bat), depending on your operating
+system.
+
+*Note: These scripts require that [Java](https://www.oracle.com/java/index.html)
+is installed.*
+
+## Using the FlatBuffers Java library
+
+*Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth
+example of how to use FlatBuffers in Java.*
+
+FlatBuffers supports reading and writing binary FlatBuffers in Java.
+
+To use FlatBuffers in your own code, first generate Java classes from your
+schema with the `--java` option to `flatc`.
+Then you can include both FlatBuffers and the generated code to read
+or write a FlatBuffer.
+
+For example, here is how you would read a FlatBuffer binary file in Java:
+First, import the library and generated code. Then, you read a FlatBuffer binary
+file into a `byte[]`.  You then turn the `byte[]` into a `ByteBuffer`, which you
+pass to the `getRootAsMyRootType` function:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
+    import MyGame.Example.*;
+    import com.google.flatbuffers.FlatBufferBuilder;
+
+    // This snippet ignores exceptions for brevity.
+    File file = new File("monsterdata_test.mon");
+    RandomAccessFile f = new RandomAccessFile(file, "r");
+    byte[] data = new byte[(int)f.length()];
+    f.readFully(data);
+    f.close();
+
+    ByteBuffer bb = ByteBuffer.wrap(data);
+    Monster monster = Monster.getRootAsMonster(bb);
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now you can access the data from the `Monster monster`:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.java}
+    short hp = monster.hp();
+    Vec3 pos = monster.pos();
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+## Storing dictionaries in a FlatBuffer
+
+FlatBuffers doesn't support dictionaries natively, but there is support to
+emulate their behavior with vectors and binary search, which means you
+can have fast lookups directly from a FlatBuffer without having to unpack
+your data into a `Dictionary` or similar.
+
+To use it:
+-   Designate one of the fields in a table as the "key" field. You do this
+    by setting the `key` attribute on this field, e.g.
+    `name:string (key)`.
+    You may only have one key field, and it must be of string or scalar type.
+-   Write out tables of this type as usual, collect their offsets in an
+    array.
+-   Instead of calling standard generated method,
+    e.g.: `Monster.createTestarrayoftablesVector`,
+    call `createSortedVectorOfTables` (from the `FlatBufferBuilder` object).
+    which will first sort all offsets such that the tables they refer to
+    are sorted by the key field, then serialize it.
+-   Now when you're accessing the FlatBuffer, you can use
+    the `ByKey` accessor to access elements of the vector, e.g.:
+    `monster.testarrayoftablesByKey("Frodo")`.
+    which returns an object of the corresponding table type,
+    or `null` if not found.
+    `ByKey` performs a binary search, so should have a similar
+    speed to `Dictionary`, though may be faster because of better caching.
+    `ByKey` only works if the vector has been sorted, it will
+    likely not find elements if it hasn't been sorted.
+
+## Text parsing
+
+There currently is no support for parsing text (Schema's and JSON) directly
+from Java, though you could use the C++ parser through native call
+interfaces available to each language. Please see the
+C++ documentation for more on text parsing.
+
+<br>
diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md
index f871c4c0..c0f3b9e7 100644
--- a/docs/source/Tutorial.md
+++ b/docs/source/Tutorial.md
@@ -3374,13 +3374,13 @@ For your chosen language, see:
 [Use in C++](@ref flatbuffers_guide_use_cpp)
 </div>
 <div class="language-java">
-[Use in Java/C#](@ref flatbuffers_guide_use_java_c-sharp)
+[Use in Java](@ref flatbuffers_guide_use_java)
 </div>
 <div class="language-kotlin">
 [Use in Kotlin](@ref flatbuffers_guide_use_kotlin)
 </div>
 <div class="language-csharp">
-[Use in Java/C#](@ref flatbuffers_guide_use_java_c-sharp)
+[Use in C#](@ref flatbuffers_guide_use_c-sharp)
 </div>
 <div class="language-go">
 [Use in Go](@ref flatbuffers_guide_use_go)
diff --git a/docs/source/doxygen_layout.xml b/docs/source/doxygen_layout.xml
index 8253903d..72888f95 100644
--- a/docs/source/doxygen_layout.xml
+++ b/docs/source/doxygen_layout.xml
@@ -29,8 +29,10 @@
           title="Use in C"/>
       <tab type="user" url="@ref flatbuffers_guide_use_go"
           title="Use in Go"/>
-      <tab type="user" url="@ref flatbuffers_guide_use_java_c-sharp"
-          title="Use in Java/C#"/>
+      <tab type="user" url="@ref flatbuffers_guide_use_java"
+          title="Use in Java"/>
+      <tab type="user" url="@ref flatbuffers_guide_use_c-sharp"
+          title="Use in C#"/>
       <tab type="user" url="@ref flatbuffers_guide_use_javascript"
           title="Use in JavaScript"/>
       <tab type="user" url="@ref flatbuffers_guide_use_typescript"