ElectricCommander version 3.5 or higher Technical Notes MS Visual Studio Add-in Integration version 1.5.0 October 2010 This document contains information about the ElectricCommander integration with the Microsoft Visual Studio Add-in, versions 2005, 2008, and 2010. Topics include: Overview... 2 Prerequisites... 2 Installing the MS Visual Studio Add-in... 3 Configuring the MS Visual Studio Add-in... 5 Using the MS Visual Studio Add-in... 11 Uninstalling the MS Visual Studio Add-in... 13 Enterprise Administration for the MS Visual Studio Add-in... 13 Troubleshooting and Getting Help... 14 1
Overview Overview ElectricCommander integrates with Microsoft Visual Studio versions 2005, 2008, and 2010. Visual Studio, an Integrated Development Environment (IDE), is used to develop console and graphical user interface applications along with Windows Forms applications, web sites, web applications, and web services in both native code as well as managed code for all platforms supported by Microsoft Windows, Windows Mobile,.NET Framework,.NET Compact Framework and Microsoft Silverlight. Supported capabilities in ElectricCommander s Visual Studio Add-in include: Initiate a pre-defined Preflight Build, which allows users to "snapshot" code and run a build to test new code before their changes are committed Initiate a typical ElectricCommander procedure Monitor the status of a running or completed ElectricCommander job Initiate a connection to the ElectricCommander web server and perform any user or administrator task This document describes the features, installation, configuration, and use of ElectricCommander s Visual Studio Add-in. Note: Installation and configuration instructions for each Visual Studio version (2005, 2008, or 2010) is the same, but the Visual Studio installation screens may be slightly different. Prerequisites ElectricCommander s Visual Studio Add-in requirements for the client machine: Access to an ElectricCommander v3.5 server or higher MS Visual Studio 2005, 2008, or 2010 Windows XP, Vista, or Windows 7.Net Framework v3.5 (installed automatically by the ElectricCommander Visual Studio Add-in setup.exe file) For Preflight build functionality, you must use one of the following Source Code Management Systems: Perforce, Subversion, AccuRev, or ClearCase. 2
Installing the MS Visual Studio Add-in Installing the MS Visual Studio Add-in Installing the Visual Studio Add-in The ElectricCommander Visual Studio Add-in Integration is available on the Electric Cloud FTP site. 1. Log into the FTP site and go to: Commander/release_3.7 (3.5 or higher) /<commander_release>/integrations /visual_studio_1.5.x 2. Select two files for download (into the same directory or folder): a. ElectricCommander_Visual Studio_Addin_setup.msi (an md5.text file is included) b. setup.exe 3. Double-click the setup.exe file. This file looks for what the Add-in needs and prompts to install the ".Net Framework"on the client machine if it is not already there. Note: To execute the setup.exe file, you must have "Read & execute" permission. You should begin the installation by double-clicking the setup.exe file so the necessary file checks are run. After this setup file completes its checks, it will use the.msi file and open the Visual Studio Add-in Install Wizard or double-click the.msi file to begin installation immediately. Click Next to continue. 3
Installing the MS Visual Studio Add-in ElectricCommander selects the folder for installing the Visual Studio Add-in. Click Browse... to select a different folder if necessary. Click Disk Cost... if you need to make sure you have enough space to install the Add-in. Click Next to continue. Click Next to continue or Back if you need to make any changes. 4
Configuring the MS Visual Studio Add-in Your Visual Studio Add-in installation is complete. Click Close to continue and go to the "Configuring Visual Studio..." section. Configuring the MS Visual Studio Add-in After successfully installing the ElectricCommander Visual Studio Add-in, your Visual Studio IDE has the following features: A new toolbar drop-down box named Commander, with options to Run Defaults or Run Custom... Select Run Defaults unless you need to customize "Commander Connection Settings" for your preflight build. 5
Configuring the MS Visual Studio Add-in A new Tool menu item: ElectricCommander Settings... The ElectricCommander Visual Studio Add-in is configured on a "per solution" basis. This means all projects in a solution share the same configuration and a Microsoft Solution File must be opened to enable configuration to occur. Note: Instructions for creating a Microsoft Solution File is beyond the scope of this document. Open an existing Solution at this time or create a new one to open before continuing. From the Tools menu, select ElectricCommander Settings to see the following window illustrated in the next screen example. Connections tab The first tab, Connections, displays all server options for the ElectricCommander server you are using. You may need to see your ElectricCommander administrator for assistance with supplying these values. Fill-in the fields as follows: Username/Password: The user name and password to access the Commander server. Hostname: The Commander server host name. 6
Configuring the MS Visual Studio Add-in Base URL: The web address for the Commander server. Port: The default port (8000) for the Commander server. Secure Port: The default secure port is 8334. Connection Timeout: By default, this is 180 seconds, but you may adjust this time if necessary. Use Secure Port (checkbox): Check this box if you want to use the secure port indicated above. Source Control System: You have the option to select your source code management system. Click the down-arrow to select Perforce, Subversion, AccuRev, or ClearCase. Default is "None". Selecting a source control system creates an additional configuration tab at the top of the screen. Note: If you do not select a source control system at this time, you can run regular Commander procedures, but you cannot use the Commander Preflight Build functionality. Click OK after all fields are filled-in. Procedure tab The second tab, Procedure, allows you to specify the Commander project and procedure you wish to run every time Run Defaults is selected from the Visual Studio Add-in toolbar. In addition, you may pass parameters to the Commander procedure by specifying parameters in the Parameter list box. The next screen example displays the Procedure tab screen. Project: The name of the Commander project to use as the default project. Procedure: The name of the Commander procedure to use the default to run. Job Timeout: The number of seconds to wait for the job to complete when auto-committing changes. Defaults to 3600 seconds (1 hour). Parameter list: The space-separated list of parameters for this procedure. 7
Configuring the MS Visual Studio Add-in Click Add to see a popup box with existing available parameters to add. Click Edit to make changes when the Parameter list box is populated. Click Delete to remove an entry in the Parameter list box. Display job outcome (checkbox): Check this box to see a success or failure notice when the job completes. Click OK after all fields are filled-in. Source Control tabs Auto-commit checkbox On the Server Settings screen, if you selected a value for the Source Control field, you have an additional tab whose name matches your Source Control system Perforce, Subversion, AccuRev, or ClearCase. On Source Control screens, you are prompted to input your particular Source Control settings (such as location, user name, and so). Configuring your Source Control workspace is beyond the scope of this document. Contact your Source Control administrator if you need assistance. Select the Commit changes on successful preflight checkbox only if you have specified a Perforce or Subversion SCM on the Server Settings screen. When you run a build, the Visual Studio Add-in uses the configuration information you provided and calls a script named ecclientpreflight. When the "Commit..." checkbox is unchecked (the default), ecclientpreflight communicates with the ElectricCommander server for the sole purpose of retrieving a "job ID" to allow you to manually monitor build status. After the job ID is retrieved, a hyperlink is displayed in the job console window and the ecclientpreflight script ends. If the "Commit..." checkbox is checked, the ecclientpreflight script does not immediately exit. Instead, ecclientpreflight continues to run in the background and monitors the status of the submitted job, waiting for it to complete. If the ElectricCommander job completes successfully, the ecclientpreflight script executes the appropriate commit message on the developer's workstation. If the commit is attempted, certain configuration options in your SCM configuration may be required. Important: If a job with Commit is set, Commit will not occur in the following circumstances: The ElectricCommander job fails The developer severs the connection to the ElectricCommander server from their local workstation The developer "kills" the ecclientpreflight script The SCM rejects the submission Click OK after filling-in the fields. See the following examples of Source Control screens for the information you will need. 8
Configuring the MS Visual Studio Add-in Perforce tab example:. Subversion tab example: 9
Configuring the MS Visual Studio Add-in AccuRev tab example: ClearCase tab example: 10
Using the MS Visual Studio Add-in Using the MS Visual Studio Add-in After opening a Visual Studio Solution, you can begin using ElectricCommander capabilities within your Visual Studio IDE. Running the default procedure Select Run Defaults from the Commander drop-down menu and a script runs [in Visual Studio - in the background], to instruct the Visual Studio Add-in to start a Commander job. Output is sent to the Visual Studio output window. After the job is submitted successfully, a link to the job is displayed in the output window along with the output from ecclientpreflight. The following example illustrates a Visual Studio output window: Checking job status After a job is submitted, you can monitor the job in the Visual Studio output window. A link is created for you to open the Commander Job Details web page. After clicking this link, the Commander web page is opened in your Visual Studio IDE so you do not have to switch applications. See an example of the Commander Job Details web page on the next page. 11
Using the MS Visual Studio Add-in An example of a Commander Job Details web page as viewed with the Visual Studio Add-in: Running a custom procedure If you decide to change the default Commander settings associated with your current Visual Studio solution, the Project, Procedure, Parameters, and Auto-commit options can be input for a "one time" run. To perform this action, select Run Custom... from the Commander dropdown menu in the Visual Studio toolbar.. Except for the Password field, all values in the dialog are the values from the currently configured procedure. You can modify any of these values and these modifications will not persist in your configuration. 12
Uninstalling the MS Visual Studio Add-in Uninstalling the MS Visual Studio Add-in To uninstall the ElectricCommander Visual Studio Add-in, select: Start > Control Panel > Add or Remove Programs For older Visual Studio Add-in versions - prior to v1.5.0: If you have difficulties starting Visual Studio after uninstalling the ElectricCommander Visual Studio Add-in, perform the following cleanup steps: 1. Select Start > Program Files > Microsoft Visual Studio (version) > Tools > Visual Studio Command Prompt 2. In the new window that opens, type the following command: devenv /resetaddin com.electriccloud.integrations.vside.connect Visual Studio should start normally now. Enterprise Administration for the MS Visual Studio Add-in The ElectricCommander Visual Studio Add-in was architected to simplify central management for a large workgroup or enterprise. The ElectricCommander Visual Studio Add-in contains the following components: "%COMMON_APP_DATA%\ElectricCommander Add-in" This directory contains the following configuration and run files: ecclientpreflight.exe This file provides the intelligence for starting a Commander procedure. ecclientpreflight.exe is called by the Visual Studio Add-in when a Commander job is initiated. "%APPDATA%\ElectricCommander Plugin" Note: "Plugin" is used for legacy installations <project name>_ec.xml This file contains an XML serialization of all data configured in the "setup" windows. This file is NOT deleted during an uninstall so you will have it when you reinstall the Visual Studio Add-in. Delete this file manually if you discontinue Visual Studio use. Also, to ensure consistency, this file can be replicated to additional workspaces and used as a template for multiple developers working on the same project. run<project name>_ec.xml This file is passed to the ecclientpreflight.exe script as a parameter (ecclientpreflight -c <config name> ) and is overwritten before every project run. "%APPDATA%\\Microsoft\MSEnvShared\Addins" This is the typical location for Visual Studio Add-in files 2 files: ec.dll, which contains the logic for the add-in, and ed-vs08.addin, which contains loading instructions used by Visual Studio. If these files are ever corrupted, remove the file manually and run the following command to restore Visual Studio: Select Start > Program Files > Microsoft Visual Studio (version) >Tools > Visual Studio Command Prompt Note: you path may be slightly different depending on your version of Visual Studios. In the new window that appears, type the following command: devenv /resetaddin com.electriccloud.integrations.vside.connect 13
Troubleshooting and Getting Help Troubleshooting and Getting Help Contacting Technical Support: Before you contact our technical support staff, please have the following information available. Your name, title, company name, phone number, fax number, and email address Operating system and version number Product name and release version Problem description Hours: 8AM - 5PM PST (Monday-Friday, except Holidays) Phone: 408-419-4300, Option #2 Email: support@electric-cloud.com Copyright 2006-2010 Electric Cloud, Inc. All rights reserved. Electric Cloud believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. ELECTRIC CLOUD, INC. MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any Electric Cloud software described in this publication requires an applicable software license. Trademarks Electric Cloud, ElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Make are registered trademarks of Electric Cloud, Incorporated. Electric Cloud products ElectricAccelerator, ElectricCommander, ElectricInsight, and Electric Make are commonly referred to by their "short names" Accelerator, Commander, Insight, and emake throughout various types of Electric Cloud product-specific documentation. All other trademarks used herein are the property of their respective owners. 14