Kristoffer's tidbits

Troubleshooting a failed Virtual Earth 3D installation

The Virtual Earth 3D setup program is a small executable that downloads and installs pre-requisites if they're not already installed and then the correct MSI for your OS flavor (32 or 64 bit). The pre-requisites are Windows Imaging Components and .NET Framework 2.0. WIC comes with Vista and XP sp3 and doesn't need to be downloaded on those platforms. The setup program logs its status to a file named VirtualEarth3DInstallLog.txt in the Temp folder. On a default Windows XP installation the Temp folder is located at C:\Documents and Settings\[username]\Local Settings\Temp.

After the pre-requisites have been validated VirtualEarth3D.msi or VirtualEarth3D64.msi are downloaded and installed.  The 64 bit MSI contains both 32 and 64 bit modules so you can run internet explorer in 32 or 64 bit mode. The MSI log is stored in MsiInstall.log, also in the Temp folder.

So what errors go to what log?

• If the error happens in the Setup program, for example a failure to download a prerequisite or the MSI, VirtualEarth3DInstallLog.txt will have an error message with the details.
• If the error happens once Setup starts running the Virtual Earth 3D MSI MsiInstall.log will contain the details.

How does Virtual Earth 3D find and load plugins?

On startup VE3D looks in the Plugins folder of the install directory (ProgramFiles\Virtual Earth 3D) and iterates through the assemblies in each subfolder of Plugins. A plugin named Sample would install itself as C:\Program Files\Virtual Earth 3D\Plugins\Sample\Sample.dll. Note that this folder doesn't exist by default so your plugin installer will need to create it.

Next each assembly is probed for classes that descend from Microsoft.MapPoint.PlugIns.PlugIn. For security reasons only assemblies that are in the GAC are allowed to run. The good news is that we are investigating allowing partially trusted plugins for our next release. This means you will be able to visit a website and have it load its own plugins to add new functionality to VE3D without forcing you to go through an install process. Since we're still in the early parts of our next release I don't know for sure if this will make the cut but it is something we would like to add.

Using a plugin to add a billboard to Virtual Earth 3D

To add objects to the VE3D world we need to create our own actor that knows how to render itself.

Actors descend from Microsoft.MapPoint.Rendering3D.Steps.Actors.Actor and must override the Render method. When it comes time to render a frame, all actors have their Render method called to queue up renderable objects. To show a billboard we'll create a BillboardActor and use a SpriteGraphicsObject to render our image.

Once we have our actor we just need to add it to the ActorManager so it knows to start rendering it. We can do this in our Activate method on the plugin.

You can browse the source code for the actor and the plugin online or download the entire project.
BillboardActor.cs | BillboardPlugin.cs
Download project

Creating a Hello World plugin for Virtual Earth 3D

With latest release of the Virtual Earth 3D release we now support loading plugins to perform additional functionality not implemented in the main product. Two new features of the release are even implemented as plugins (bird's eye photos and user created models).

To get you started with creating your own plugin for VE3D here's a short starter guide using Visual Studio 2005.

1. Create a new C# Class Library project, call it HelloWorld.
2. Add references to the following assemblies located in C:\Program Files\Virtual Earth 3D:
   
   • Microsoft.MapPoint.Rendering3D.dll
   • Microsoft.MapPoint.Rendering3D.Utility.dll
3. Rename Class1.cs to HelloWorldPlugin.cs and paste the following code over the file:
   

   using System;

   using System.Collections.Generic;

   using System.Text;

    

   using Microsoft.MapPoint.PlugIns;

   using Microsoft.MapPoint.Rendering3D;

    

   namespace VirtualEarth3DSamplePlugins.HelloWorld

   {

       public class HelloWorldPlugin : PlugIn

       {

           #region Constructor

           public HelloWorldPlugin(Host host)

               : base(host)

           {

           }

           #endregion

           #region Overrides

           public override void Activate(object activationObject)

           {

               this.Host.Notifications.Display("Hello world!");

    

               base.Activate(activationObject);

           }

           public override string Name

           {

               get

               {

                   return "HelloWorldPlugin";

               }

           }

           #endregion

       }

   }

4. Go to Project Properties, Signing, check Sign the assembly and create a new key to sign your project with. Only plugins that are in the GAC will be granted permissions to run and only strongly named assemblies may be placed in the GAC.

   Build your project and copy HelloWorld.dll to a new folder named C:\Program Files\Virtual Earth 3D\Plugins\HelloWorld. From a Visual Studio 2005 Command Prompt run
   gacutil -i "C:\Program Files\Virtual Earth 3D\Plugins\HelloWorld\HelloWorld.dll"

Now start up 3D mode on maps.live.com and you should see a notification upon startup from the hello world plugin.

 That's it for creating a simple plugin. If you want to explore further on your own the Host object contains all the interfaces for a plugin to communicate with VE3D.

Mandatory disclaimer so I don't get into trouble: creating plugins is not officially supported.

Is your e-mail going unanswered?

As a general rule the chance of your e-mail getting a response is inversely proportional to the number of people on the To and Cc lines.

Let's take an example:

You e-mail Bob a question. Bob now feels directly responsible for your question and promptly replies.

You e-mail Bob, Anna, and Frank a question and put them all on the To line. Now Bob, Anna, and Frank are only one third responsible each for replying and all three ignore your e-mail hoping one of the other two will respond.

Psychologists call this "diffusion of responsibility".

Virtual Earth update

Visual Studio Tip: Examining long strings while debugging

Long strings can be a pain to examine in Visual Studio while you're debugging but in .NET projects you can easily write these to a file on the fly. If for example we want to examine the contents of string s, open up the Immediate Window (Ctrl+I) and type

System.IO.File.WriteAllText("C:\\Debug.txt", s);

Then open up C:\Debug.txt to see the entire string.

Navigate large solutions in Visual Studio quicker

The one Visual Studio tip that everyone should know is how to quickly open a file in a large solution without having to remember which folder or project it's in.

Press Ctrl+Alt+A to open up the Command Window, then type open and the first few letters of the filename and you'll get a dropdown of all matching files in the current solution. Press Enter to open the selected file.

Javascript prototype versus closure execution speed

When Javascript execution speed matters consider using prototype instead of closures where possible. Even for a small closure the difference can be noticable when called hundreds of times. Consider the following example that implements a Pixel object with some ancillary functions in both the closure and prototype patterns:

When this is run in IE7 on my machine, the closure implementation takes around 450ms and prototype takes around 140ms. Add two more empty functions and the closure time increases to 560ms and prototype to 155ms.

On Firefox 1.5.0.9 the difference is in the listed example is even larger with the closure taking 515ms and prototype still around 140ms.

For small applications that don't construct hundreds or thousands of the same type of object the execution speed difference between closure and prototype probably doesn't matter so as with all performance advice measure, measure, measure.

Debugging memory usage in managed code using Windbg

Windbg, is there anything it can't do?

CLR Profiler is great for getting an overview of memory allocations and usage for managed applications but it doesn't work for very large applications and can't be attached after the application has been running for a while to determine why after 12 hours memory use spikes. Windbg can be an acceptable alternative when you find yourself looking at an unexpected memory spike and you're curious where all that memory is being allocated.

Start Windbg, attach to the process, and load the sos dll (see previous post).

We start out by getting a summary of our memory allocations with !dumpheap

We've got about 3 megs worth of System.Byte[] allocated so let's focus in on this to see why these objects exist.

A few small Byte arrays but 3 of them are a meg each so let's find out why the first object is still alive (or if it is alive at all, a GC might not have happened to collect it yet).

The application has a reference to Form1 which has a reference to an ArrayList which has a reference to my Byte array. If a GC were to happen right now this object would be kept alive.

Instead of checking each Byte array by address individually we can use the .foreach token.

By using the /ps parameter to .foreach (see Windbg help file for details) you can run gcroot on every nth item to get a sample of objects.

Debugging lock issues in managed code using Windbg

Windbg can be helpful for locking lock issues in managed code that seem to only happen on client machines when the moon is full and the stars are aligned just right. Windbg is a minimal installation and with managed code doesn't require debug symbols to still be useful.

For my test scenario I have an application that hangs for 10 seconds at a time once a button is pressed so I start up windbg and break during the hang so I can inspect what's going on. First we check to see what the managed threads are currently running what:

Debugging exceptions in managed code using Windbg

By default Windbg will break for access violations (or null reference exceptions as they're called in managed code). To get Windbg to break for managed exceptions use the sxe command.

A little while later our program generates a CLR exception and pops into the debugger.

This is a first chance exception so this may be expected and handled, as the message helpfully reminds you. Let's find out what caused this exception.

We can also have a look at the managed stack trace to see where this exception happened.

If we want to get a feel for what sorts of exceptions are generated by our program but not necessarily inspect each one we can tell Windbg to stop on exceptions, print out some information about the exception, and then continue running all without user intervention.

Setting a breakpoint in managed code using Windbg

One of the great features of managed code is getting call stacks and proper class and member function names without debug symbols. We can examine the methods of a class and set breakpoints based on name.

To see the methods on an object in Windbg we first need to find its method table. We can do this with the !name2ee command which will look up information about a class.

With the method table address we can examine all the methods defined on the object.

For the curious we can see whether the function is ngen'ed code or if it has been JITted yet. PreJIT means ngen code, JIT and NONE is whether the function has been JITted or not. From here we can set a breakpoint.

It's a pending breakpoint because this code has not been jitted yet and thus has no place to put the debug breakpoint. You can also set breakpoints directly by name using !bpmd.

Getting started with Windbg and managed code

Windbg (or wind bag as my friend calls it) is my one stop shop for almost everything debugging related. It's great for finding issues that only happen on a client machine and you don't want a full blown Visual Studio installation mucking up your repro.

With the sos extension Windbg becomes useful at debugging managed code as well. To get started with Windbg and sos fire up Windbg and attach to a managed process. I'm using .Net 2.0 for my development so I need to load the sos dll from the Framework directory (for 1.1 .Net use .load clr10\sos.dll instead) . I can do this with the .loadby command:

This tells Windbg to load the debugger extension sos.dll from the same directory that the current process has mscorwks.dll loaded from.
Next we hit Debug | Go (or F5) and the process is now happily running away.

Once the problem occurs go back to Windbg and press Debug | Break and we can now examine the process state in safety. If at any point you need help with the sos commands, !help will get you going.

Coming up next week: using Windbg to debug exceptions, deadlocks, and memory problems in managed code.

Loading website images in parallel

By default web browsers will only open 2 simultaneous connections to a named website to be a good client. If you're loading several images this means you may hamstring your bandwidth usage and make your website load slower.

Take the following HTML source as our base, off a site hosted at www.example.com:

By not allowing more than 2 images to be downloaded at once the total page load time takes longer than is necessary. Since we own the host in question we know we can safely allow more than 2 images to be downloaded at once so we create two DNS aliases, img1.example.com and img2.example.com that both point to www.example.com. We now modify our HTML source to make use of these two new hosts:

Web browsers will now open 2 connections per named host (www.example.com, img1.example.com, and img2.example.com) for a total of 6 concurrent connections.

Downloading all of them at the same time decreases the amount of bandwidth available for any individual image but will maximize the overall bandwidth usage leading to faster load times.