[mapguide-commits] r10069 - branches/4.0/MgDev/Doc/dotnet_api/docs

[svn_mapguide at osgeo.org]

Author: jng
Date: 2023-11-10 12:45:50 -0800 (Fri, 10 Nov 2023)
New Revision: 10069

Added:
   branches/4.0/MgDev/Doc/dotnet_api/docs/unique-features.md
Modified:
   branches/4.0/MgDev/Doc/dotnet_api/docs/toc.yml
Log:
#2877: Document unique features of the .net API

Modified: branches/4.0/MgDev/Doc/dotnet_api/docs/toc.yml
===================================================================
--- branches/4.0/MgDev/Doc/dotnet_api/docs/toc.yml	2023-11-10 20:21:36 UTC (rev 10068)
+++ branches/4.0/MgDev/Doc/dotnet_api/docs/toc.yml	2023-11-10 20:45:50 UTC (rev 10069)
@@ -1,2 +1,4 @@
 - name: Getting Started
-  href: getting-started.md
\ No newline at end of file
+  href: getting-started.md
+- name: Unique features of the .net API
+  href: unique-features.md
\ No newline at end of file

Added: branches/4.0/MgDev/Doc/dotnet_api/docs/unique-features.md
===================================================================
--- branches/4.0/MgDev/Doc/dotnet_api/docs/unique-features.md	                        (rev 0)
+++ branches/4.0/MgDev/Doc/dotnet_api/docs/unique-features.md	2023-11-10 20:45:50 UTC (rev 10069)
@@ -0,0 +1,30 @@
+# Unique features of the .net API
+
+The MapGuide API for .net provides the following unique features on-top of the standard C++ API surface that is exposed and wrapped by proxy classes in .net.
+
+## Property support
+
+Most `Get` and `Set` pairs of methods are encapsulated as standard .net properties
+
+## MgReadOnlyStream
+
+The `MgByteReader` class models a read-only stream of data. However, when interoperating in the .net world such streams are generally represented in the form of `System.IO.Stream`. Thus, one would have to write stream conversion code to transfer the underlying stream contents from a `MgByteReader` to a `System.IO.Stream`.
+
+The .net API includes a `MgReadOnlyStream` class to eliminate such boilerplate by provided a `System.IO.Stream` adapter over the existing `MgByteReader`.
+
+## .net collection interface support
+
+All collection proxy classes implement the `IList<T>` interface allowing for instances of your MapGuide collection classes to be passed to anything expecting `IList<T>`.
+
+The only exception is `MgReadOnlyCollection`, which only implements `IReadOnlyList<T>` given its read-only nature
+
+## Library-specific initialization
+
+When using the MapGuide API, you must call `MapGuideApi.MgInitializeWebTier(<path to webconfig.ini>)` to initialize the API before using it.
+
+If you are building an application only using the `OSGeo.MapGuide.Foundation`, `OSGeo.MapGuide.Geometry` and `OSGeo.MapGuide.PlatformBase` subsets of the MapGuide API, the `MgInitializeWebTier` method is not available for you to call, as that is part of the `OSGeo.MapGuide.Web` module.
+
+For such cases, the `OSGeo.MapGuide.Foundation` provides the following methods to initalize only this subset:
+
+ * `FoundationApi.MgInitializeLibrary(string stringResourcesPath, string locale)`
+ * `FoundationApi.MgUninitializeLibrary()`
\ No newline at end of file