Dispatch for ASP.NET - Enhanced FTP support for ASP.NET projects

Displaying the Dispatch Tool Window

To Open Dispatch

Along the main menu, click Dispatch > Dispatch Tool Window

Note - the Dispatch menu item will only be visible when a compatible web project is open
- Web Project / Web Application Project / MVC Project / VS.PHP Project

Open a web project or a solution containing a web project.
Right click on the web project node and choose Dispatch. This will show the Dispatch dockable tool window.
Once the window is opened, the Dispatch Solution Tree will be displayed inside the pane.

..top..

Activating Dispatch

Before you can use Dispatch, you need to enter your license key. You should have received a license key at the email address used during registration. If you no longer have your license key, then skip this step and go here.

Once you've entered a legitimate key, the status of the license will be displayed. If you are using a trial key, the number of days remaining will be stated. If the key is valid and hasn't expired, an icon next to the key will show, signifying a valid license and successful activation.

..top..

Locating a Lost License Key

If you've misplaced your license key, it can be located and sent to the email address that was used during registration. Just click on the Lookup Key button and enter your email address. Again, this must be the same email address that was used during registration. Once you click the Send button, your license key will arrive within a few minutes.

If you are using a purchased license key and no longer have access to the email account that was used during registration, please email licensing@yellowcup.net and include the email address initially used for registration.

..top..

Deployment Modes

Similar to a VS build configuration (Debug, Release), Dispatch supports multiple deployment modes per project, allowing you to upload your code to multiple servers. String replacements are also done on a per-mode basis or can be applied to all modes.

Modes can be added, removed and cloned. Each mode must be tested independently. There is no limit to the amount of modes a project can have, but a project must have at least one tested mode before any files can be uploaded. Only a single mode can be selected at a given time.

..top..

Configuring a Web Project for Deployment

In order to deploy a Web Project, it first needs to be configured for deployment. This simply means you need to specify FTP information and some other optional settings. These settings are stored in a config file.

The deployment configuration file associated with a Web Project is always named "deploy.config" and resides in the root of the Web Project. To configure a Web Project for deployment, follow these steps:

Open the the web project in Visual Studio 2005.
Launch Dispatch (See: Displaying the Dispatch Tool Window).
Right click on the Web Project you want to deploy and select Configure for Deployment.
The Deployment Configuration form will allow you to configure this project for deployment.

FTP Settings

Mode name
The name of your deployment mode.

FTP Server
The address of the destination FTP server.
Example: "myftpserver.com" | Omit leading "ftp://"

FTP Port
The FTP port on which to connect. Default is 21.

FTP Remote Path
The remote path on the server where this project will be uploaded.
Example: "/joesblog" | Leave empty if root is destination directory

FTP Username:
The username to use for authentication.

FTP Password
The password to use for authentication. (Note: When persisted, this value is encrypted)

FTP Passive Mode
Sets the passive mode when connecting to the specified FTP server.

FTP Timeout
The amount of seconds to wait before declaring a connection timeout.

SSL Settings

Misc Settings

Import
Dispatch allows you to import a configuration from an existing configured project. This is useful if many of your projects share common settings. Importable file types are "deploy.config" as well as legacy "*.deploy" files.

Browsing the remote file system
Use the Browse... button to browse your FTP server and create new folders.
Once you've completed the form, click the Test FTP button to test the FTP settings. This test ensures that Dispatch can read, write and delete files from your server.
If the test passes, you can now click the Save button to save the configuration to disk. If the test failed, you will need to update the FTP-specific settings before you are able to save the configuration to disk.
At this point, the Web Project hierarchy should be visible in the Dispatch Tool Window. You are now able to deploy your project. (See: Uploading Files)

..top..

Ignoring Files

This feature allows you to filter out files/folders that shoudln't be deployed. The filter is a wildcard-based pattern. (Example: "*/bin/*.pdb" - this would filter out all files that end in ".pdb" in the "bin" folder)

Ignore filters are only applied to your local project only. When Remote View is being overlayed, ALL remote items will be displayed. These filters are applied globally across all deployment modes.

..top..

Replacing Strings in Files On-Upload

Dispatch can replace strings in any text file belonging to a project when that file is uploaded. For instance, before you deploy your web.config file to your FTP server, you may want to change the debug mode from true to false, or perhaps you need to use a different connection string.

Select the file that contains the string to be replaced. Specify the string to look for and the string to replace it with. Upload.

You can add as many string replacements as you'd like, creating a new list item per replacement. Replacements are done on a per-deployment-mode basis. This allows each deployment mode to have it's own set of string replacements. You can also create string replacements that are applied globally, to all deployment modes.

..top..

Additional Configuration Options

Always parse remote directories recursively
This option will parse all directories on your FTP server recursively when Remote View Overlay is enabled. By default, Dispatch will only parse the directories you choose to explore.

After a file is uploaded to the server, uncheck its node
Enabling this option will leave the node checked. This can be useful when you need to upload a file repeatedly.

Place a temporary app_offline.htm file in the root of this site
If you are uploading content to a live site, it is recommended that you enable this option to temporarily restrict users from accessing the site. This file will be deleted upon completion of the upload.

If you would like to customize the app_offline.htm file, you can specify this in the Alternate File Source field.

Clear Upload Log
Clicking this button will clear the upload log, so the next time a local file comparison is performed, Dispatch will assume no files have ever been uploaded and, therefore, recommend all files to be uploaded.

Synchronize Upload Log
Clicking this button will write an entry for each file in the site to the upload log, essentially simulating a site-wide upload. This does the opposite of the Clear Upload Log function. If a local file comparison is performed after clicking this button, no files will be recommended for upload.

..top..

Project Binding

Monitor the project directory for file system changes
Enable this option to watch the file system for changes to files and directories.

Specifying a custom project binding path
If you user pre-compilation for your ASP.NET web project, you can set the New Binding Path field to the build output location specified in your project. Doing so will let Dispatch know what directory to monitor for changes to files.

..top..

Uploading Files

There are a few different ways to upload your files.

Uploading From the Dispatch Solution Tree

Ensure the project has the correct Deployment Mode selected.
Check one or more items in the Dispatch Solution tree. (Note - Dispatch can upload files from multiple projects to multiple FTP servers.)
Click the Upload Checked Items button in the tool window toolbar. Your files will begin uploading shortly. Any directories that don't exist remotely will be created by Dispatch.
Check the status area (towards the bottom of the tool window) for the upload progress. For additional details and error reports, check the output window.
To cancel uploading, click the Stop button in the toolbar.
If you want to view the details of the upload during or after the upload, please check the output window pane and select the Dispatch option
Once the upload is complete (or aborted), a status message will be displayed in the status area w/ the results.

Uploading From Solution Explorer

Ensure the project has the correct Deployment Mode selected.
Select the file(s) you wish to upload in Solution Explorer.
Right-click and choose Upload Selected Files
Your files will begin uploading shortly

Notes about uploading from Solution Explorer

Dispatch will only upload files that appear in the Dispatch Solution Tree. Other selected files will be ignored.
If a directory is uploaded from the Solution Explorer, Dispatch will upload all content recursively.

Uploading From the Code Editor

To upload the current file you are working on in the code editor.

Ensure the project has the correct Deployment Mode selected.
Ensure that Track Active Item in Solution Explorer is checked. Tools > Options > Projects and Solutions
Press the keyboard shortcut: alt + u
Your file will begin uploading shortly

If an unsaved file is uploaded, Dispatch can prompt you to save the file prior to upload. This prompt is configurable in options.

When uploading from either the Solution Explorer or Code Editor, you have the option of being warned before your upload queue actually begins. To prevent accidental uploads, you may prefer extra confirmation before uploading. See Visual Studio Settings for more information.

..top..

Displaying the Linear View

With the nature of nested hierarchies, it may not always be clear what files are checked when nodes are collapsed. In order to prevent unwanted, checked files from accidentally being uploaded to the server, a flat, linear view of checked files is available. This view can be toggled on and off using the Toggle Linear View button in the tool window toolbar. This view makes it easier to see what files are checked. It is recommended to review all checked files PRIOR to performing an upload.

..top..

Comparing Files

Typically, only files that have changed since the last upload need to be uploaded to the server. Dispatch can determine which files should be uploaded by comparing the last-write-time of a file. Dispatch offers two forms of comparing files: local comparison and server comparison.

Compare Against Local
Dispatch manages a log of files that are uploaded. Project files are compared against that log to determine which files have been updated since the last upload. This comparison method is very fast and works in a disconnected state, but relies on the log which may not be accurate if files are uploaded outside of Dispatch. This method makes use of checksums to determine if the file has changed.
Compare Against Remote
Dispatch will crawl the Project's remote directory on the FTP server and compare all existing files against the local file system. This method is slower but is more accurate because it does not rely on a local log. This method is suggested if Dispatch is not the only file-upload-client. If your FTP server supports file checksums, Dispatch will compare the content of files using a checksum. If not, the last modified time will be used for comparison.

Files can be compared both locally and remotely at the Solution, Project and directory level. Comparisons on individual files are not supported.

..top..

Displaying the Remote View Overlay

The Remote View Overlay feature allows you to see the remote file system (relative to your project) on the respective FTP server.

Once the Remote View Overlay is initially displayed, it is cached and can be hidden and shown quickly. Moreover, one can flush the cache and force another refresh.

Files and folders that exist locally and remotely will not appear any different.
Files and folders that exist locally but not remotely will be noted with green text.
Files and folders that exist remotely but not locally will be faded and noted with red text.
Files that have changed since the last upload will be noted with purple text.

Items that exist remotely can be diffed, deleted, downloaded and renamed.

Items that exist locally but not remotely should be uploaded in the typical fashion (by checking their box and invoking an upload).

Folders are downloaded recursively, as are files that are grouped (.aspx -> aspx.cs; etc). When grouped files are renamed, both files are renamed accordingly.

Ignore Filters are... well... ignored in Remote View - they have no effect. This is by design and is meant to give you a 100% view of all files and folders regardless of what is ignored locally.

If you are certain that a local file exists on the server, you can access the diff, download, delete commands by holding down the shift key.

..top..

Uncheck Successful Uploads

By default, when a file is uploaded, its associated checkbox is unchecked since you typically only need to upload a file once until it changes again. In certain cases, you may want to continuously upload a file despite whether it has changed. Uncheck this option and Dispatch will not uncheck uploaded files.

..top..

Refreshing the Solution

Click the Refresh button in the tool window toolbar to force a refresh of the open solution. Dispatch will re-parse the solution and update the Dispatch Solution tree accordingly.

..top..

Diffing local and remote files

Dispatch includes a file-diffing feature allowing you to compare the local & remote versions of the same file. Since you can only diff files that exist both locally and remotely, the option won't be available unless Dispatch is aware the remote version exists. This can be accomplished by enabling Remote View Overlay for the parent directory.

If you are sure that the remote version of the file exists, holding down the shift key while right-clicking on the node will enable the option as well.

..top..

Keyboard Shortcuts

alt + u

alt + shift + u

alt + w, alt + d

While not techincally a keyboard shortcut, you can check/uncheck multiple items at once by selecting them all, then with the ctrl key pressed, check or uncheck the box. All selected nodes will follow suit.

..top..

Visual Studio Settings

Most settings in Dispatch are on a per-project basis. However, there are a few settings that are not specific to a project. These options can be set in the Visual Studio Options menu. To get there, click Tools > Options > Dispatch or select the Dispatch > Dispatch Options.

General Settings

Automatically show Dispatch when a web project loads
When true, the Dispatch tool window will load when a web project is loaded. If docked alongside the Solution Explorer, Dispatch will not steal focus.

Automatically show/hide the linear view on-check
Checking this box will let Dispatch choose when to show and hide the linear tree view. When at least 1 node is checked in the solution tree, the linear view will display. When no nodes are checked, the linear view will be hidden from view.

Focus Dispatch tool window on upload
This setting will auto-focus the Dispatch tool window whenever an upload is triggered. This is typically useful when uploading from a keyboard shortcut (alt + u).

Display the Dispatch button in the Solution Explorer toolbar
This provides a convenient way to access the Dispatch tool window directly from the Solution Explorer's toolbar.

Match Solution Explorer's active item
When this box is checked, Dispatch will auto-select whatever node is selected in Solution Explorer. This setting DOES NOT change the selection of the Solution Explorer.

Check for updates daily
When this box is checked, Dispatch will check once (and only once) a day to see if a newer version is available for download.

When checking for updates, check for pre-release versions
If you like to live on the wild-side, check this box and you'll be notified when a pre-release version becomes available. While often very stable, pre-release versions may contain features and fixes that need further mass testing before being deployed in public release.

If an error occurs, automatically submit a error report
Anytime an error occurs, we'll give you the opportunity to submit a pre-filled report (just takes one click). If you're a busy samaritan, check this box and Dispatch will send the report on your behalf without prompting for that click.

Alerts

Warn me when uploading from the Solution Explorer or code editor
While keyboard shortcuts make uploading easier and more convenient, there's always a possiblity that something might accidentally get uploaded that shouldn't have been. Check this box if you want to be warned when uploading from the keyboard.

Prompt to save when uploading dirty items, otherwise just save
When checked, you will be prompted to save the file(s) before uploading. If this box is left unchecked, the file will automatically be saved prior to uploading.

When deleting a remote item, prompt me to type "yes", just to be safe
Safety first. Sometimes a confirmation dialog just won't cut it. So when you're about to do something risky like deleting a remote file, we'll make extra sure that's what you really want to do.

Alert me when changing deploy modes
By default, you'll be asked to confirm when you change deploy modes. This is another safety feature to keep accidental mode changes from happening. Uncheck with caution.

Logs & Output

Display the Dispatch output pane when any FTP activity takes place
Feel free to follow along as Dispatch does its thing. All FTP activity is traced to the output pane. Check this box if you'd like Dispatch to focus the output pane automatically.

Display the Dispatch output pane when any error occurs
Dispatch will focus the output pane when an FTP error occurs, bringing the issue to your attention.

Enable verbose tracing (for debugging purposes)
If you are running into issues (and we hope you don't), enable this option to create a detailed trace log of your activity. This will help us fix any bugs that may arise.

Display time stamps in the output log
The output log is a great way to see what Dispatch is up to. Setting this to true adds time stamps to each line of the output log.

Log trace output to file
While Dispatch traces data to the output pane, you can optionally have Dispatch trace this information to a text file on disk. This may be helpful when the output pane is unavailable.

Log FTP activity to files in this directory
Dispatch will log all commands sent to your FTP server in an external text file under the specified directory.

FTP

Default upload buffer
If your connection can be optimized by altering the upload buffer, you can specify it here. The default value is 4 KB.

File Comparison Mode
Dispatch will use either the last modified date or a checksum of a file to determine if the file is out of sync. You can specify which mode to use on both local & remote comparsons. Note - if your server does not support checksums over FTP, the last modified date will be used.

Disconnect FTP connection timeout
Each FTP session will be automatically disconnected after a specified interval expires without any FTP activity. The default is 20 seconds.

Misc

File Diff Viewer
Dispatch ships with a file diff viewer but supports the ability for you to choose your own diff viewer.

..top..