Debugging Your Custom IIS Transform Manager Task

The during an initialization phase, the ITask interface provides your custom task with injected dependent objects, see here for more details on these objects. One challenge while writing a custom ITask implementation is debugging your task with real-time injected values. One approach is to have your debugger launch a finished or failed job in a similar environment as the IIS Transform Manager would. Here are the high level tasks to achieve this:  
  1. Run and locate a job instance
  2. Identify the program and arguments to execute
  3. Setup the working environment
  4. Run the command under your debugger

Run and Locate a Job Instance

To begin, you’ll need to get either a finished or failed job.  At this point, if you have not registered your task with the IIS Transform Manager Service yet you should. See here for more details on this. You should also have a WatchFolder setup using a job template with the custom task in question. Finally, copy all the files that are needed to start a job in the watch folder. This will create a job instance which will either end up in the finished or failed queue. Here’s an example of a failed job instance directory:

%WatchFolderRoot%\WorkQueue\Failed\20111028035216_DC0AA2A0A63146B6B0B41B34200FED69\
This job instance directory contains all the files and metadata needed to run a job.  

Identify the Program and Arguments to Execute

The Job instance directory contains a job manifest file, *.smil. The name of the file matches the directory name as well as the Job Instance ID. In the failed job example above there should be a file in that directory, called 20111028035216_DC0AA2A0A63146B6B0B41B34200FED69.smil, representing the job manifest. If you edit that file, somewhere in the RDF block of the head element, you’ll see what the task scheduler was configured to execute.

    …<iisms:commandLine>
   <iisms:program>C:\Program Files\IIS\Transform Manager\TaskEngine.exe</iisms:program>   <iisms:arguments> /taskIndex 1 /manifest 20111028035216_DC0AA2A0A63146B6B0B41B34200FED69.smil</iisms:arguments>
</iisms:commandLine>...
These iisms:program and iisms:arguments values can be used to re-build the TaskEngine.exe command needed to invoke your task. TaskEngine.exe is the IIS Transform Manager executable that loads your assembly, locates the ITask interface class and calls your implementation of the Initialize, Start and Dispose methods.  The /taskIndex 1 argument tells the TaskEngine.exe to locate the first task listed in the job manifest; it’s a 1 based index. If you have more than one task in your Job Template, you’ll need to find the right task . The /manifest tells the TaskEngine.exe where to locate the Job Manifest file.

Setup the Working Environment

One important detail you need to know is that the TaskEngine.exe is expecting to have its working directory set to the parent folder, not the Job instance folder. In this case the failed directory.  At this point you can run the task from a command line by executing these two commands:

cd /D %SystemDrive%\inetpub\media\Transform Manager\MyWatchFolder\WorkQueue\Failed\  

“%SystemDrive%\Program Files\IIS\Transform Manager\TaskEngine.exe” /taskIndex 1 /manifest 20111028035216_DC0AA2A0A63146B6B0B41B34200FED69.smil

One more thing to keep in mind; make sure the credentials you are running under are the same as what the Watch Folder settings are configure to run under. Otherwise, you might miss out on some important access/permission issues.

Run the Command Under Your Debugger

Knowing where to run the program from and the command line to execute, you can now launch a windbg session and start debugging.

I.e. 

C:\inetpub\media\Transform Manager\MyWatchFolder\WorkQueue\Failed>c:\Debuggers\windbg.exe "c:\Program Files\IIS\Transform Manager\TaskEngine.exe" /taskIndex 1 /manifest 20111028035216_DC0AA2A0A63146B6B0B41B34200FED69.smil

windbg

An alternate approach is to configure your Visual Studio project to launch TaskEngine.exe, using the project's properties. Here’s how:  

visualStudioProperties

From your project's properties:

  1. Click on the Debug vertical tab
  2. Under Start Action, select Start External Program and browse to the TaskEngine.exe found in the job manifest *.smil file, the iisms:program element value.
  3. Under Start Options Paste the Command line arguments found in the job manifest *.smil file in the textbox, the iisms:arguments element value.
  4. Under Start Options set the Working directory to the %Failed% directory location.
  5. If you make changes to the code and want to run again, you may consider configuring Post-Build deployment commands:
    1. Click on the Build Events vertical tab.     
    2. In the Post-build event command line: text box paste the following line
copy /Y "$(TargetPath)" "%systemdrive%\Program Files\IIS\Transform Manager"

Now you should be able to start debugging, (F5), and step through the code or catch exceptions.

Sample Exception Code

From the code you can see the obvious exception being thrown with the message “BadException”. This matches what was found in the windbg debugger session as well as what was caught in Visual Studio. 

You should now be able to debug your own custom task with real-time injected dependent objects running inside a job instance directory with all the files needed to execute your task.    

 

7 Comments

Comments have been disabled for this content.