== Adding a layer to the initial map ==
This page describes how to use the MaestroAPI from the [wiki:maestro MapGuide Maestro] project in your own application.

An example of how to add a layer to the map BEFORE it is loaded, using Meastro API. To get Maestro API, please download latest Maestro package, then reference OSGeo.!MapGuide.MaestroAPI.dll and !MapGuideDotNetApi.dll only. 

If you choose the local version below, Maestro API communicates with MapGuide through a !LocalNativeConnection object which talks to MG through a native connection. So all the !MapGuide unmanaged DLL's must be present in the applications Bin folder.

If you choose the remote version, Maestro API communicates with MapGuide through HTTP and no MapGuide binaries are required.

Read about [wiki:maestro/MaestroAPI/basics the difference between LocalNativeConnection and HttpServerConnection here]

(VB.NET)
{{{
#!text/x-vba
Imports OSGeo.MapGuide.MaestroAPI
...

'Read the setup, either from QueryString, Form, Cookies or hardcoded values
Dim username As String = IIF(Request.Params("USERNAME") Is Nothing, "Anonymous", Request.Params("USERNAME"))
Dim password As String = IIF(Request.Params("PASSWORD") Is Nothing, "", Request.Params("PASSWORD"))
Dim layout As String = IIF(Request.Params("LAYOUT") Is Nothing, "Library://MyLayout.WebLayout", Request.Params("LAYOUT"))
Dim locale As String = IIF(Request.Params("LOCALE") Is Nothing, "en", Request.Params("LOCALE"))


'Create a connection to MapGuide
Dim conn As IServerConnection

'Pick your connection method here
Dim local As Boolean = True

If (local) Then
    'Replace "webconfig.ini" with the full path to "webconfig.ini"
    conn = New LocalNativeConnection("webconfig.ini", username, password, "en")
Else
    'Replace "myserver" with the server name, or use "localhost"
    Dim host As New Uri("http://myserver/mapguide/mapagent/mapagent.fcgi")
    conn = New HttpServerConnection(host, username, password, "en", true)
End If


'Get the original layout
Dim weblayout As WebLayout = conn.GetWebLayout(layout)

'Get the mapDefinition
Dim mapDef As MapDefinition = conn.GetMapDefinition(weblayout.Map.ResourceId)

'Create a new MapLayer object
Dim layer As new MapLayerType()

'Absolute minimum properties
layer.Visible = true
layer.ResourceId = "Library://MyExtraLayer.LayerDefinition"

'Extra properties
layer.ExpandInLegend = true
layer.ShowInLegend = true
layer.LegendLabel = "My layer"
layer.Name = "MyLayer"

'Add the layer to the MapDefinition
'Unfortunately we cannot control the order at this time, so we do it manually
Dim maplayers as new List(Of MapLayerType)(mapDef.Layers)
maplayers.Insert(0, layer)
mapDef.Layers = new MapLayerTypeCollection()
For Each mlt as MapLayerType in maplayers
    mapDef.Layers.Add(mlt)
Next

'Generate a temporary MapDefinition id
Dim tempMapDef As String = new ResourceIdentifier("MyMap", ResourceTypes.MapDefinition, con.SessionID)

'Save the modified map at its new temporary location
con.SaveResourceAs(mapDef, tempMapDefName)

'Generate a temporary WebLayout id
Dim tempWebLayout As String = new ResourceIdentifier("MyMap", ResourceTypes.WebLayout, con.SessionID)

'Update the WebLayout to point at the modified MapDefinition
weblayout.Map.ResourceId = tempMapDef 

'Save the modified layout at its new temporary location
con.SaveResourceAs(weblayout, tempWebLayout)

'Redirect the page to the viewer, using the temporary map
Response.Redirect("/mapguide/ajaxviewer/?LAYOUT=" & Server.UrlEncode(tempWebLayout) & "&SESSION=" &  Server.UrlEncode(con.SessionID), true)
}}}