The first level of add-in debugging is the default Visual Studio Tools for Applications debugger, which you can use without modifying the host application. This approach requires little configuration and is the simplest option for providing add-in debugging support.

Visual Studio Tools for Applications creates a new instance of the host application and runs that instance in the same process as the add-in that is being debugged. When the user exits the debugger, Visual Studio Tools for Applications terminates the host application process. As a result, the add-in and the host application are forcefully terminated at that exact point in the execution.

This approach works as long as the host application can be forcefully terminated at an arbitrary point during execution without causing problems. For many host applications, this is not acceptable. Terminating the application without performing clean-up tasks could lead to corrupt files and other problems. In these cases, you might want the host application to be notified when the debug session terminates so the host application can perform the necessary clean-up tasks. To enable these notifications, consider setting up a non-destructive debugging environment.

Implementing Standard Visual Studio-Style Debugging

The second level of add-in debugging is a basic non-destructive implementation. Non-destructive debugging gives the host application an opportunity to perform any clean-up tasks that are necessary to exit properly. To enable this, you can configure the host application to receive notifications when the debug session starts and ends.

With non-destructive debugging, the host application and the add-in run in separate processes. Although this approach is more robust, communicating between processes can decrease performance.

You must modify the host application to receive events from the debugger. Visual Studio Tools for Applications starts the debugger in an external debug process. This process uses .NET Framework remoting to search for a registered instance of the IExternalDebugHost interface. Then, you can handle debug event notifications to unload and load add-ins or perform clean-up tasks to properly exit the application.

Implementing Basic Non-Destructive Debugging

private const string vstaHostDebugUriPrefix = "/vstaHostDebugUri:";
private const string vstaHostDebugReadyPrefix = "/vstaHostDebugReady:";
string[] args = Environment.GetCommandLineArgs(); 

for (int i = 1; i < args.Length; ++i)
{
    if (args[i].StartsWith(vstaHostDebugReadyPrefix))
    {
        hostDebugReadyEventName = 
            args[i].Remove(0, vstaHostDebugReadyPrefix.Length);
    }
    else if (args[i].StartsWith(vstaHostDebugUriPrefix))
    {
        hostDebugUri = 
            args[i].Remove(0, vstaHostDebugUriPrefix.Length);
    }
}

public class VstaRunTimeIntegration : IExternalDebugHost

ExternalDebugging.RegisterExternalDebugHost(
    (IExternalDebugHost)this, new Uri(hostDebugUri));
EventWaitHandle readyEvent = new EventWaitHandle(false,
    EventResetMode.ManualReset, hostDebugReadyEventName);
readyEvent.Set();

public int OnBeforeDebugStarting()
{
    // Create the process and start it.
    this.addInProcess = new AddInProcess();
    this.addInProcess.Start();

    // Hook up the event handlers.
    addInProcess.ShuttingDown += new 
        EventHandler<System.ComponentModel.CancelEventArgs>(
            AddInProcessExiting);
    isDebugging = true;
    return addInProcess.ProcessId;
}

public void OnDebugStarting()
{
    IEntryPoint addin = null;
    Collection<AddInToken> token = AddInStore.FindAddIn(
        typeof(IEntryPoint), 
        AddInStoreExtensions.DefaultPipelinePath, 
        addInPath,className);

    // Activate the add-in.
    addin = addinToken.Activate<IEntryPoint>(this.addInProcess,
        AddInSecurityLevel.FullTrust); 
    addin.Initialize(serviceProvider);
    addin.InitializeDataBindings();
    addin.FinishInitialization();
    addInList.Add(addin);
}

public void OnDebugStopping()
{
    if (isDebugging)
    {
        addInProcess.Shutdown();
        isDebugging = false;
    }
}

The third level of add-in debugging is non-destructive debugging that works with a running instance of the host application. In standard Visual Studio-style debugging and basic non-destructive debugging, Visual Studio Tools for Applications starts a new instance of the host application to run the add-in. However, you can use an existing instance of the host application to run the add-in during the debug session. This level of debugging does not forcefully close the host application, and it provides a more natural user experience for the add-in developer. This interactive approach provides an experience very similar to that of a Visual Basic for Applications (VBA) macro.

As with non-destructive debugging, you need to configure the host application to receive notifications when the debug session starts and ends. When the debug session starts, the host application receives a notification. The host application responds by unloading the add-in from the host process and then loading the add-in into the debug process. When the debug session ends, the host application receives another notification. The host application loads the add-in back into the host application process.

During an out-of-process debugging session, the Visual Studio Tools for Applications debugger, the add-in, and the host application each run in separate processes as they perform the following tasks. 

• The debugger process evaluates symbol names and functions on the thread for the add-in process.

• When the debugger evaluates a host object in the add-in process, the add-ins calls a host function, which is executed by Visual Studio Tools for Applications.

• The Visual Studio Tools for Applications runtime calls the add-in process to retrieve add-in lifetime management information.

Because the add-in process is frozen by the debugger and only one thread is allowed to evaluate variables, the call from the host cannot be serviced. Thus, the add-in process stops responding.

To resolve this problem, the registry can be modified to instruct the debugger to enable execution of all threads when evaluating an object. When all threads execute, the add-in process can service the call from the host process, and the debugger is not blocked. However, this workaround may cause side effects if the add-in has multiple threads scheduled to run when the debugger breaks.

If you want Visual Studio Tools for Applications to use all threads to evaluate a variable, you must set a registry key.

The following procedure demonstrates how to configure the debugger to use all threads.

To debug your add-in using all threads

Implementing Advanced Non-Destructive Debugging

IVstaHostAdapter vha = (IVstaHostAdapter)macroProject.get_Extender(
    "VSTAHostAdapter2007");
string hostDebugUri = ExternalDebugging.RegisterExternalDebugHost(
    (IExternalDebugHost)this, "ShapeAppCSharp");
string debugCommandLine = "/vstaHostDebugUri:\"" + 
    hostDebugUri + "\"";
vha.SetDebugInfo("ShapeAppCSharp.exe", debugCommandLine,"");

 [C#]
// Create an external process to use for debugging.
int IExternalDebugHost.OnBeforeDebugStarting()
{
    // Create an external process.
    this.macroAddInProcess = new AddInProcess();
    this.macroAddInProcess.Start();

    // Watch for when the user finishes debugging.
    this.macroAddInProcess.ShuttingDown += MacroAddInProcessExiting;
    return this.macroAddInProcess.ProcessId;
}

// Called when debugging is started.
void IExternalDebugHost.OnDebugStarting()
{
    this.isDebugging = true;
    IEntryPoint addIn = null;

    // Unload add-ins from the host application.
    foreach (IEntryPoint inProcAddin in macroAddIns)
    {
        if (inProcAddin != null)
        {
            if (!isDebugging)
            {
                inProcAddin.OnShutdown();
            }
            AddInController controller = 
                AddInController.GetAddInController(inProcAddin);
            controller.Shutdown();
        }
    }
    macroAddIns.Clear();

    // Load the add-in into the external debug process.
    Collection<AddInToken> addInToken = 
        AddInStore.FindAddIn(typeof(IEntryPoint), 
        AddInStoreExtensions.DefaultPipelinePath, 
        addInPath, 
        startUpClass);

    // Activate the add-in in the external debug process.
    addIn = addInToken[0].Activate<IEntryPoint>(
        this.macroAddInProcess, AddInSecurityLevel.FullTrust);
    addIn.Initialize(this.serviceProvider);
    addIn.InitializeDataBindings();
    addIn.FinishInitialization();
}

// Called when debugging is stopped. 
void IExternalDebugHost.OnDebugStopping()
{
    this.isDebugging = false;
    macroAddInProcess.ShuttingDown -= MacroAddInProcessExiting;
    macroAddInProcess = null;

    // Unload add-ins from the external debug process.
    foreach (IEntryPoint inProcAddin in macroAddIns)
    {
        if (inProcAddin != null)
        {
            if (!isDebugging)
            {
                inProcAddin.OnShutdown();
            }
            AddInController controller = 
                AddInController.GetAddInController(inProcAddin);
            controller.Shutdown();
        }
    }
    macroAddIns.Clear();

    // Load the add-in into the host application.
    IEntryPoint addIn = null;
    Collection<AddInToken> addInToken = 
        AddInStore.FindAddIn(typeof(IEntryPoint), 
        AddInStoreExtensions.DefaultPipelinePath, 
        addInPath, 
        startUpClass);

    // Activate the add-in in the host application.
    addIn = addInToken[0].Activate<IEntryPoint>(
        AddInSecurityLevel.FullTrust);
    addIn.Initialize(this.serviceProvider);
    addIn.InitializeDataBindings();
    addIn.FinishInitialization();
}

In destructive and non-destructive debugging scenarios, the values that are shown for local variables or properties in the immediate window might actually be the value of the proxy object. You may see the following errors in the Locals or Immediate windows:

1. System.Reflection.TargetException: Non-static method requires a target.

2. Microsoft.Office.Tools.Debugger appears in the name column.

3. The delayedEventList list appears, but it should not be visible.

4. Cannot obtain fields or call methods on the instance of type type because it is a proxy to a remote object.

As a workaround, create a local variable and assign it to the value of the host, especially for struct variables. For example, if you want to the size of a shape in the host application, create a local size variable and set it to the value of the shape.size. Then, you can evaluate the local variable to test the value.

Tasks

Concepts

Other Resources