Using a post-build event to set up a custom task
The ArcGIS Explorer project template and sample custom tasks automatically set up a custom task ready for use on the current machine by using a project build event. In this case, after building the project you should find that the task is available in the Manage Tasks dialog and ready to be added to a map. This topic describes how this process happens; it should help you to understand how your tasks are set up automatically, or help you to fix projects where this process is broken.
You can also read this topic to understand how you can set up this process for an existing custom task project which does not already have this process.
| Note | |
|---|---|
| This topic is applicable to setting up a custom task on the machine on which is it developed, for immediate testing purposes. It is not recommended that you attempt to deploy custom tasks to other machines using this process. | |
How can you set up custom tasks automatically on a developer machine?
ArcGIS Explorer stores custom tasks on a machine in a specific location, on a per-user basis. The All Available Tasks list in the Manage Tasks dialog box lists all of the tasks which are currently installed at this location. The How Explorer Loads Custom Task Assemblies topic gives you more information about how ArcGIS Explorer loads custom tasks, and the location the tasks are loaded from.
For each sample task in the SDK, building the project will automatically copy the resulting dll and required nmf file to this location, from where ArcGIS Explorer will load it. This action happens in the project post-build event, a project-level setting in Visual Studio.
Project Post-Build Events
Visual Studio allows you to specify commands to execute before and after a project is built. These commands are specified in the Visual Studio Project Designer pages. You may also be familiar with the Project Designer as the 'project properties', as these pages can be opened using the Properties item on the Project menu in Visual Studio.
Samples and templates in the ArcGIS Explorer SDK use the post-build event in order to set up a custom task on a developer machine. This is done by running a tool called CopyToTasks; this tool is installed as part of the ArcGIS Explorer SDK, and is designed to work out the correct location for a specified task assembly, and then copy that task assembly to the location. Another required parameter for this tool specifies an NMF file with details of the custom task to be set up (this is required for correct setting up of the task - if you instead deploy a task using the application, this file would be automatically created for you; the tool replicates this process on a developer machine).
| Note | |
|---|---|
| The project-level options available in the Visual Studio Project Designer might differ from what is described here depending on your active settings or edition. Specifically, Express editions do not provide a user interface to set up or edit build events, although existing events are honored. See the Express Editions section below for more information. | |
Example of a post-build event
You can see an example of a post-build event which sets up a custom task by opening any sample task, or by creating a new custom task using an ArcGIS Explorer project template. Below, each line (excluding comments) of the post-build event is explained, using the example of the post-build event of the C# Find Place sample task and assuming ArcGIS Explorer is installed to the default location on the C drive, 'C:\Program Files\ArcGIS Explorer'.
set SDK=%ArcGIS_E2SDK% |
The first 'set' command above uses a system environment variable, created when the SDK is installed, to identify the location of the Developer Kit folder. For the default location, this would be 'C:\Program Files\ArcGIS Explorer'.
set ToolPath="%SDK%\Tools\CopyToTasks.exe" |
The next 'set' line works out the full path of the CopyToTasks tool on the machine. For the default location this would be 'C:\Program Files\ArcGIS Explorer\DeveloperKit\Tools\CopyToTasks.exe'.
%ToolPath% "$(TargetPath)" "-n:$(ProjectDir)ESRI.E2SDK.FindPlaceSampleCS.CustomTaskUI.nmf" > "$(ProjectDir)CopyToTasksReport.log" |
This line runs the CopyToTasks tool, passing in two parameters. First, the Visual Studio macro TargetPath is used to identify the full path of the assembly which the project creates. For the C# Find Place sample, this would be 'C:\Program Files\ArcGIS Explorer\DeveloperKit\Samples\Explorer\FindPlaceSample\CSharp\bin\Debug\ESRI.E2SDK.FindPlaceSampleCS.dll'.
The second paramter indicates an NMF file which is part of the project and includes details of the custom task. The 'ProjectDir' macro is used, which provides the full path of the project directory which will be the directory containing the NMF file, allowing us to pass in the full path of the NMF file. For the C# Find Place sample this would be 'C:\Program Files\ArcGIS Explorer\DeveloperKit\Samples\Explorer\FindPlaceSample\CSharp\ESRI.E2SDK.FindPlaceSampleCS.CustomTaskUI.nmf'.
The last item on the line sends the output from the tool into a log file called CopyToTasksReport.log, which will also be located in the project directory. You can look inside this file to see how the CopyToTasks tool has worked. For the C# Find Place sample this would be 'C:\Program Files\ArcGIS Explorer\DeveloperKit\Samples\Explorer\FindPlaceSample\CSharp\CopyToTasksReport.log.
Bear in mind that if you change the following properties of a custom task project from those set up by the template, you may have to update the corresponding items.
| If you change... | ...you may need to update... |
| The name of the TaskUI class | The name of the NMF file in the project, the Class tag inside the NMF, and the post-build event with the new class name. |
| The namespace of the TaskUI class | The name of the NMF file in the project, the Class tag inside the NMF, and the post-build event with the new fully qualified TaskUI class name. |
| The name of the task assembly | The Assembly and DownloadLocation tags inside the NMF. |
| The public key, culture or version of the task assembly | The Assembly tag inside the NMF. |
Express Editions
The Express editions of Visual Studio are provided by Microsoft with the aim of being easy to use development environments for the hobbyist, novice, and student developer. They provide a reduced feature set compared to full Visual Studio editions.
One feature which is not available in the Express editions is the ability to add and edit build events. However, if an existing project already has a build event specified, the Express edition will honor (run) that existing build event. As the ArcGIS Explorer custom task templates create projects with a post-build event specified, this means that building such a project will run the post-build event and set up the custom task as described above.
If you change the properties of a custom task project in an Express edition, then bear in mind this may break the post-build event and your custom task may no longer be automatically set up when you build it.
More Information
See the CopyToTasks Tool topic for more information about the command line options and behaviour of this tool.
For more information about build events in Visual Studio 2005, refer to the Visual Studio 2005 help:
- Build Events Page, C# Project Designer: http://msdn2.microsoft.com/en-us/library/e2s2128d(VS.80).aspx
- Build Events Dialog Box, Compile Page, Visual Basic Project Designer: http://msdn2.microsoft.com/en-us/library/ms404762(VS.80).aspx
If you have problems setting a custom task up for use on a developer machine, you may find useful information in the Deployment Troubleshooting topic.