Share via

Adding a Virtual Earth 3D Plug-in to your webpage

  • Article

Note: this entry references code for an older version of VE3D. The newest code samples are here. 

 

Want to try custom code for the 3D view of Virtual Earth? This is the place to find out how!

What do I need?

· Virtual Earth 3D installed. Navigate to maps.live.com, click the 3D button, and follow the upgrade/install steps.

· Visual Studio 2005 or higher and some c# coding skills (any .NET language actually, but samples will be in C#).

· This package.

If you do not have Visual Studio installed, you can download a free version of Visual Studio 2008 here. See notes at the end of the post for details.

 

Extract the samples zip to c:\Samples (or any other directory, but you'll have to fix up some paths in the projects). There's a Readme, but you should be able to just open the sln in Visual Studio, set one of the projects to the Startup project, and hit F5. For this post, we'll just talk about the basics of how the plug-in will be loaded.

 

Try building and launching the project SimpleObjectPlacement.

 

Selecting the Startup Project

By default, you'll get an IE window with a script warning. This only happens because we're loading the html off the local drive, and will not happen if we point to a web server.

Script warning in IE

You can change startup behavior by modifying the values in the Debug pane of the project.

Debug pane of the project properties

Once there you should see the globe, and after a moment it will zoom to off the coast of Africa to see a floating cube.

Yay, a colored cube!

So what happened? First, we have a very simple webpage that loads the JavaScript SDK, and then extracts the 3D control from it to do some special loading. This is an unsupported thing to do (well heck, everything in these samples is unsupported, but that doesn’t mean it won’t work), but we need to get at the Events and LoadPlugInDll methods.

    map = new VEMap('myMap');

    map.SetDashboardSize(VEDashboardSize.Normal);

    map.LoadMap(null, 2, 'a', false, VEMapMode.Mode3D);

    control3D = map.vemapcontrol.Get3DControl();

    control3D.AttachEvent("OnPlugInLoaded", "On3DPlugInLoaded");

    control3D.AttachEvent("OnPlugInActivated", "On3DPlugInActivated");

    control3D.AttachEvent("OnPlugInDeactivated", "On3DPlugInDeactivated");

    control3D.LoadPlugInDll("C:\\Samples\\SimpleObjectPlacement\\bin\\Debug\\SimpleObjectPlacement.dll");

Events are just callbacks when certain things happen. In this case, when a plug-in is finished loading the SDK will try to call a function called "On3DPlugInLoaded". It has to be this way because the LoadPlugInDll method is asynchronous -- otherwise we'd have to sit and wait for loading to complete, causing a negative user experience. But you don't have to worry much about this, just know that you can listen to events and you'll be called when things happen. You can also fire your own events, which we'll get to later. In this case, if you look at the handler you'll see when we finish loading the plug-in we'll activate it. We could do more, but this is the minimum.

You can specify a plug-in to load in two ways. First is like this, with a local file path. Second is by specifying the fully qualified name. Either method requires that the plug-in be installed in the GAC, which is an unfortunate security limitation that we hope to relax in the future. You can get installed into the GAC by using utilities that come with VS, or by writing an MSI installer. We'll get into more on that later. All the samples here install their output into the GAC as a post-build step to help you get past these details.

When the plug-in is loaded, then we start executing the C# code. If you put breakpoints in SimpleObjectPlugIn.cs, you'll see it gets a call to the constructor, and then one to the Activate function. In a future post we'll walk through the details of what happens next, how the cube gets into the world, and why it changes color when you mouse over it. In the meantime, try playing with the other samples. Let us know what you think, and please enjoy.

Download Samples.zip

 

Notes on VS 2008 and VS 2008 Express:

If you use either of these, you'll have to run the solution upgrade wizard.  It should be painless, but you may encounter some of the following issues:

VS 2008 Full and Express:

If you get errors on build about gacutil and return code 3, you may need to update the path in the project pre- and post-build steps to "$(DevEnvDir)..\..\..\Microsoft SDKs\Windows\v6.0A\bin\gacutil".

VS 2008 Express:

A message about a property not supported.  This is related to the last point below, and can be ignored.

A message about Solution Items not supported (VS Express).  This is just the readme file and can be ignored (you can still read the readme by just navigating to c:\samples).

Express only builds to the Release bin path, so the html files (TestPage.htm) need to be updated such that the LoadPlugInDll call points to bin\\Release instead of bin\\Debug.

VS Express doesn't support debugging a different process than the one launched.  This is tricky because plug-ins run in the browser's process.  To run the plug-in samples you'll need to build the project, and then run the html file manually in your favorite browser.  However, you can debug a forms app as normal, so you can work around this by debugging your code inside the SimpleForm sample, and then copying to the plug-in.  We apologize for this inconvenience, but it was free after all ;)

 Update:

The intellisense files in the samples zip have been updated to be more complete.

Comments

  • Anonymous
    April 17, 2008
    Hidden treasures! I think this blog is being confused with the 3D spaces blog that also just launched. I put a link on the MSDN forums. For those playing with the code just remove the source control bindings and ignore the missing 3 projects. All run fine, looking forward to having some time to play and blog about it. Thanks!

  • Anonymous
    April 18, 2008
    Hi SoulSolutions, thanks for letting me know.  I've fixed the solution file in the package, it shouldn't complain anymore.

  • Anonymous
    May 27, 2008
    Hi, very interresting blog. Hope it will grow up... I am currently writing a windows application with VE3D. But it is not really easy to find any documentation for the MapPoint assemblies... In top of that, I am using the last version of VE3D (beta) and there are some differences in the way that some classes are implemented (from previous versions). So, I was wondering if "by luck", it could be possible to find somewhere any kind of stuff to help understanding this HUGE collection of classes that VE3D uses. Any suggestion will be welcome ;-)

  • Anonymous
    May 27, 2008
    Hi Zorg, thanks for reading.  The reason it's hard to find much information out there is because VE3D is technically unsupported as an API, which means that we haven't released a lot of the nice stuff like detailed docs.  We're also still actively refining the API, so things get broken from version to version.  Part of this is to make sure that when we do release, the breakage problem will be reduced. So, about the classes, if you check out the samples in this post, they touch most of the major families/namespaces of classes that are intended to be used by other developers.  The five assemblies that you see referenced in the projects are the main ones, but you may often find yourself only needing Rendering3D, Rendering3D.Utility, and Geometry.  Data in particular is narrowly used, and contains many classes that you can mostly ignore.  The other assemblies are probably not going to be part of the standard API, and though in some situations they may be used it will only be part of a special case or a workaround for something that hasn't been implemented yet. Thanks again, and have fun!

  • Anonymous
    May 27, 2008
    Hi NicolaiF, I understand and appreciate your clear answer. So, thanks a lot for all the nice work you and the others are posting in this pages. It is a great source of knowlegde and I do consider it as a reference for VE3D development. I will come back very often to learn more from this community. May be one day I could help someone on VE3D issues too ;-) Have a nice day.

  • Anonymous
    July 08, 2008
    Some entries were missing or incomplete from the xml intellisense files in the samples zip in the first

  • Anonymous
    November 20, 2008
    How do I integrated the xml doc files (Microsoft.MapPoint.Geometry.xml, doc) with MS Visual C# 2008? Thanks for the great samples. They are helping me a lot.

  • Anonymous
    November 20, 2008
    Oh.. just read the article http://blogs.msdn.com/virtualearth3d/archive/2008/07/08/new-intellisense-files.aspx.  Answer was there. Thanks.