Troubleshooting Extension Development

This topic deals with various problems that may come up when building a WebMatrix extension:


There are a few common problems that people run into that we can help you past.


General Debugging Tips

The first thing to do is make sure you can debug your extension while it is running in WebMatrix. Follow the steps outlined in the ReadMe.txt file included in any WebMatrix extension folder created using the Visual Studio [extension template]:

  1. Open your extension's Properties (either using Solution Explorer, or by selecting Properties at the bottom of the Project menu.
  2. Switch to the Debug tab.
  3. Select Start external program.
  4. Click the "..." browse button beside it.
  5. Browse to WebMatrix.exe. If you are running a 32-bit OS, it will be located at: C:\Program Files\Microsoft WebMatrix\WebMatrix.exe
    If you are running a 64-bit OS, on the other hand, it will be at:
    C:\Program Files (x86)\Microsoft WebMatrix\WebMatrix.exe
  6. Thereafter, every time you press F5 WebMatrix will automatically start and load the extension for debugging, as long as the build was successful.

To debug an extension running on a remote machine, you can also attach to a running process by following the following steps:

  1. On the Debug menu, select Attach to Process.
  2. In the Attach to Process dialog box, find the program that you want to attach to from the Available Processes list.

    • If the program that you want to debug is running on another computer, use the Qualifier list box to select or specify the remote computer. For more information, see Remote Debugging Setup.
    • If the process is running under a different user account, select the Show processes from all users check box.
    • If you are connected through Remote Desktop Connection, select the Show processes in all sessions check box.
  3. In the Attach to box, make sure that the type of code you will debug is listed. The default Automatic setting tries to determine what type of code you want to debug. If the automatic setting is not appropriate:

    • Click Select.
    • In the Select Code Type dialog box, click Debug these code types and select the types to debug.
    • Click OK.
  4. Click Attach.


My extension works on my machine, but fails on others

Be sure that you are targeting version 4.0 of the .NET Framework. By default, Visual Studio 2012 targets version 4.5, but WebMatrix still supports configurations where 4.5 is not available. Check your settings in the Application tab of your project's properties to make sure that it is targeting version 4.0:

Target Framework in Visual Studio 2012


My Extension Has Stopped Loading in WebMatrix

You're coding away, and you load your new extension in WebMatrix. Then, you run into a bug. The program displays the following dialog:

Extension Failure Dialog

No problem! You see what's wrong, and go fix it, but now when you rebuild, your extension has stopped showing up in WebMatrix...

What has happened is that WebMatrix has added your extension to a list of disabled extensions that it won't load. How do you fix this? You delete the disabled extensions file, which is located in your %localappdata% folder into which all WebMatrix extensions are installed:

Disabled Extensions file to delete

On your home drive, look for the following file:


If you have version 2.0 of WebMatrix installed, the location will be almost the same, except that the \30 folder will be \20.


I Need to Copy a File with Admin Privileges, But Can't

Sometimes you may need to copy a file into an application folder that is under one of the Program Files folders, or in some other protected location where copying requires admin privileges. Figuring out how to do this may have you stumped.

You can find an example to follow in the Node Power Tools sample extension. In the WebMatrixExtension.cs file, the method checks to see whether the iisnode-inspector.dll is already installed, and if not, shells out to NodeElevator.exe to install it, so that the operating system can asks the user for permission to install into a protected loction. InstallNodeInspector is implemented as follows:

protected void InstallNodeInspector()
  // check whether iisnode-inspector.dll is installed in iisnode-dev
  var programfiles = Environment.GetEnvironmentVariable("ProgramFiles(x86)");
  var path = programfiles + @"\iisnode-dev\release\x86\iisnode-inspector.dll";
  if (!File.Exists(path))
    // if the file isn't there, use NodeElevator to run as admin and copy into program files
    var pathToExe = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "NodeElevator.exe");

    var psi = new ProcessStartInfo()
      FileName = pathToExe,
      UseShellExecute = true,
      Verb = "runas",
      CreateNoWindow = true,
      WindowStyle = ProcessWindowStyle.Hidden

    var process = Process.Start(psi);

    if (process.ExitCode != 0)
        MessageBox.Show(string.Format("There was an error copying iisnode-inspector.dll into {0}.  The exit code was {1}.", path, process.ExitCode));

The NodeElevator code is as follows:

static int Main(string[] args)
  int retVal = 1;

    var programfiles = Environment.GetEnvironmentVariable("ProgramFiles(x86)");
    var path = programfiles + @"\iisnode-dev\release\x86\iisnode-inspector.dll";
    if (!File.Exists(path))
      var originPath = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "iisnode-inspector.dll");
      if (Directory.Exists(programfiles + @"\iisnode-dev\release\x86\"))
        File.Copy(originPath, programfiles + @"\iisnode-dev\release\x86\iisnode-inspector.dll");
    retVal = 0;
  catch (System.Security.SecurityException secEx)
    retVal = 1;
  catch (UnauthorizedAccessException authEx)
    retVal = 2;
  catch (Exception ex)
    retVal = 3;
  Console.WriteLine("NodeElevator completed with return code: {0}", retVal.ToString());

  return (retVal);

Using this approach, you can install libraries or utilities that your extension depends on into protected locations.


My Extension Doesn't Work Just After It Is Installed

One thing to check is whether your extension is depending on an event like IWebMatrixHost.WebSiteChanged to get started. Normally, this makes perfect sense, but right after the extension is first installed, you may already be in an existing site, and so the event you're waiting on won't be raised.

The solution is to move your start-up logic out of the event handler into its own method that the event-handler calls. Then, you can do a different check in the extension's Extension.Initialize method to see if you are in the right context to run, and if so, call that start-up method.


Summary and Useful Links

This topic reviewed some common problems developers may encounter while building WebMatrix extensions, and provided guidance for solving them.

  Useful Links: