Working with TFS in IntelliJ IDEA via VSTS Plugin

Recently Microsoft released a plugin for JetBrains IntelliJ IDEA in order to integrate this IDE with VSTS and TFS. Although Microsoft did a good job describing on how this plugin should be installed and described some basic settings, there are many non covered questions by the documentation provided. This is especially true when it comes to TFS and HTTPS. I will show you what is necessary in order to setup a connection for both Git and TFVC repositories on TFS.

Installing the plugin

In order to install the plugin, in the main screen of IDEA, choose Plugins from Configure menu:

2016-12-23-08_29_00

Once the plugin window opens, choose Browse repositories

2016-12-23-08_31_45-plugins

In browse repositories search for Visual Studio

2016-12-23-08_32_32-browse-repositories

If the Visual Studio Team Services plugin is not found, your connection may not be setup correctly. In case you are, as I am, behind a proxy, you need to click on HTTP Proxy settings button in the same screen (bottom left) and you will be presented with the following dialog

2016-12-23-08_30_10-http-proxy

Here you need to setup the necessary parameters (Auto detect proxy settings worked for me) and test your connection by clicking on Check connection button. Once done you will be prompted to enter an address that is behind the proxy so that internet connection can be verified. I used http://www.google.com/ for my test.

2016-12-23-08_30_38-check-proxy-settings

After confirming, you should see the following message

2016-12-23-08_30_48-check-proxy-settings

Now, back to Browse repositories screen, the Visual Studio Team Services plugin now should be found. Click on install and after the procedure finishes you will be asked to restart IntelliJ IDEA. Do so, restart the IDE.

2016-12-23-08_33_59-platform-and-plugin-updates

The plugin is now installed. In case this is not sufficiently clear, you can also follow the Microsoft guide Visual Studio Team Services Plugin for IntelliJ IDEA and Android Studio.

Be also sure that you have at least version v1.111.0 installed as I encountered issues with TFVC and previous versions of the plugin.

Importing the certificate

In case you are not accessing TFS through SSL connection you can skip this part. For Visual Studio Team Services plugin to connect to the TFS via https, that is using a self-signed certificate, no matter if you do intend using Git or TFVC, you need to import the certificate in the IntelliJ IDEA certificate store. To do so, export your certificate in the Base-64 encoded X.509 format. You can read about this in one of mine previous posts, Installing self-signed certificates into Git cert store.
Once you exported your certificate and let’s say saved it in C:\temp folder under the name tfs.cer, you need to open the command prompt and position yourself under the folder containing keytool.exe application. You can find it in the IntelliJ IDEA install folder, which in my case is C:\Program Files (x86)\JetBrains\IntelliJ IDEA Community Edition 2016.3.1\jre\jre\bin.

Once there you will then execute the following command

keytool -keystore "C:\Program Files (x86)\JetBrains\IntelliJ IDEA Community Edition 2016.3.1\jre\jre\lib\security\cacerts" -importcert -alias TFS -file "C:\temp\tfs.cer"

You will be then prompted for the keystore password. If you haven’t changed it, the default password is

changeit

After typing the password you will see the details about the certificate you are trying to import, and again you will be prompted to confirm that you trust this certificate. Type yes and you are done. Your screen should look like this

2016-12-27-11_16_12-administrator_-c__windows_system32_cmd-exe

Visual Studio Team Services plugin and Git

Before we even start, we need to be sure that a Git client is installed on our machine. From the Welcome screen choose Configure then Settings.

2016-12-29-15_08_58

In the settings window move to Version control -> Git pane and test the path to your Git client

2016-12-27-10_17_37-default-settings

In case all is good you should get back the version of your Git client

2016-12-29-15_09_41-git-executed-successfully

If this is not the case, or the path is wrong (change it and try again) or the Git client is not present on your machine. You can install Git for windows and you will find the necessary here.

In case you are using the https connection with TFS and it is based on a self-signed certificate do not forget to add that certificate into the Git cert store. This is something different then adding it to the Java cert store that I described in the previous chapter. You will need to do both of these steps. As I already described this procedure in detail, you can follow my other blog post Installing self-signed certificates into Git cert store.

Once the Git client is installed and certificate is imported, we can continue setting up the Visual Studio Team Services plugin. Get back to the welcome scree of IntelliJ IDEA and in the version control drop down choose Team Services Git

2016-12-23-08_34_54-welcome-to-intellij-idea

At this point a new dialog will be presented to you.

2016-12-27-11_05_09-checkout-from-team-services

Move to the Team Foundation Server tab and specify the address of your TFS server, then click connect. You will now be prompted for the credentials and if everything is ok, you will be show the list of available repositories

2016-12-27-11_18_08-checkout-from-team-services

You are now able to clone the repository of your choice and start working with it directly from IntelliJ IDEA.

Visual Studio Team Services plugin and TFVC

Before starting with TFVC, as for Git, we need an external tool. The tool in question is TF command line tool. It ships with the Microsoft Team Explorer Everywhere 2015 and you can download it here.
The file we are interested in is TEE-CLC-14.0.3.zip. Download it and unzip it in a folder of your choice. You should end up with something similar to this.

2016-12-27-12_15_39-tee-clc-14-0-3

Now, open the command prompt, move into the folder where you have extracted the TF command line tool and run the following:

tf eula /accept

If command succeeded and you haven’t received any error, you are good to go.

2017-01-02-09_01_28-administrator_-c__windows_system32_cmd-exe

Now back to IDEA. Open the settings panel.

2016-12-29-15_08_58

and move to Version Control -> TFVC pane. In the select path to executable field, enter the exact path to the tf.cmd command file located in TF command line tool folder.

2016-12-29-16_09_38-default-settings

Once done, press the test button and you should see the following message

2016-12-27-12_29_32-tfvc-command-line

Confirm all of the open windows and get back to the IDEA welcome page. Now you are ready to choose Team Services TFVC (Preview) version control.

2017-01-02-08_58_59-welcome-to-intellij-idea

At this point, same as for Git, you will be prompted about the connection towards your TFS. The following dialog will be shown.

2016-12-27-11_05_09-checkout-from-team-services

Move to the Team Foundation Server tab and specify the address of your TFS server, then click connect. You will now be prompted for the credentials and if everything is ok, you will be shown the list of available TFVC repositories.

2016-12-27-13_18_30-checkout-from-team-services

You can now create a new workspace directly from IDEA and start working with your TFVC repositories.

Troubleshooting

There are a couple of common issues you may encounter in following what I just described. I will tell you about the most common ones and how to overcome those.

In case you see the message in the following screenshot

2016-12-27-11_05_28-checkout-from-team-services

You are probably facing some issues with the certificate. Make sure that you exported/imported the certificate correctly.

During the test of the TF command line utility, you may encounter the following exception

2016-12-27-12_28_41-tfvc-command-line

In may case it turned out to be a problem with allocating the heap memory from TF process. I could clearly see in the log file the following:

2016-12-22 13:14:08,949 [ 17642] INFO - ugin.external.commands.Command - 167680800(ns) - elapsed time for add -noprompt -?
2016-12-22 13:15:46,592 [ 115285] INFO - lugin.external.ToolRunnerCache - getRunningToolRunner: toolLocation={0}
2016-12-22 13:15:46,592 [ 115285] INFO - lugin.external.ToolRunnerCache - getRunningToolRunner: slow version - null
2016-12-22 13:15:46,592 [ 115285] INFO - alm.plugin.external.ToolRunner - ToolRunner.start: toolLocation = C:\Utils\TEE-CLC-14.0.3\tf.cmd
2016-12-22 13:15:46,592 [ 115285] INFO - alm.plugin.external.ToolRunner - ToolRunner.start: workingDirectory = null
2016-12-22 13:15:46,592 [ 115285] INFO - alm.plugin.external.ToolRunner - arguments: add -noprompt -?
2016-12-22 13:15:46,716 [ 115409] INFO - ugin.external.commands.Command - CMD: Error occurred during initialization of VM
2016-12-22 13:15:46,717 [ 115410] INFO - ugin.external.commands.Command - CMD: Could not reserve enough space for 2097152KB object heap
2016-12-22 13:15:46,731 [ 115424] WARN - ugin.external.commands.Command - CMD: parsing output failed
com.microsoft.alm.plugin.external.exceptions.ToolBadExitCodeException: KEY_TF_BAD_EXIT_CODE
at com.microsoft.alm.plugin.external.tools.TfTool.throwBadExitCode(TfTool.java:109)
at com.microsoft.alm.plugin.external.commands.Command$1.completed(Command.java:155)
at com.microsoft.alm.plugin.external.ToolRunner$ListenerProxy.completed(ToolRunner.java:289)
at com.microsoft.alm.plugin.external.ToolRunner$ProcessWaiter.run(ToolRunner.java:327)

A workaround for this issue is to modify the tf.cmd file by specifying a lower -Xmx parameter. By default it is set to 2014MB however a 1024MB also worked well for me.

Another issue with this version of Visual Studio Team Services plugin is in changing in between the Team Services TFVC (Preview) and Team Services Git, or viceversa. You can read more about it here, TfsAuthenticator hangs the IDE.

No matter the issue, you can always find more information about it in the log file. The log file is located in my case in C:\Users\majcicam\.IdeaIC2016.3\system\log. Adapt this path to your case. The log file name is idea.log.
Visual Studio Team Services Plugin settings can be found in vsts_settings.xml file under C:\Users\majcicam\.IdeaIC2016.3\config\options folder.

Useful links

On visualstudio.com you can read more about this topic and see some useful how-to video.

  1. Installing Visual Studio Team Services Plugin for IntelliJ IDEA and Android Studio
  2. Using Visual Studio Team Services Plugin for IntelliJ

With all of these information I do hope you can get on going with the plugin and boost your productivity.

Happy coding.

TFS 2015 behind a proxy

In many enterprise realities it is quite common that all of the internet access is made via a proxy server. Recently I wrote a post about a Tough life behind a proxy, you may check that for some of my rants and tips. What if your servers do also require internet access? Although it may seem it doesn’t, TFS 2015 has a need to access the web. Not having the access to web will not compromise any of it’s core functionality, however it will continue logging an error in the event log. It has to do with the News panel that is shown (or not) on your main portal page. As you can see on the following screenshot next to the Recent team rooms panel, on the right side, the usual News panel is not shown.

before

If you check your event log, you will probably find the following error:

System.Net.WebException: Unable to connect to the remote server ---> System.Net.Sockets.SocketException: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond 23.198.69.66:80
       at System.Net.Sockets.Socket.DoConnect(EndPoint endPointSnapshot, SocketAddress socketAddress)
       at System.Net.ServicePoint.ConnectSocketInternal(Boolean connectFailure, Socket s4, Socket s6, Socket& socket, IPAddress& address, ConnectSocketState state, IAsyncResult asyncResult, Exception& exception)
       --- End of inner exception stack trace ---
       at System.Net.HttpWebRequest.GetResponse()
       at System.Xml.XmlDownloadManager.GetNonFileStream(Uri uri, ICredentials credentials, IWebProxy proxy, RequestCachePolicy cachePolicy)
       at System.Xml.XmlUrlResolver.GetEntity(Uri absoluteUri, String role, Type ofObjectToReturn)
       at System.Xml.XmlTextReaderImpl.FinishInitUriString()
       at System.Xml.XmlTextReaderImpl..ctor(String uriStr, XmlReaderSettings settings, XmlParserContext context, XmlResolver uriResolver)
       at System.Xml.XmlReaderSettings.CreateReader(String inputUri, XmlParserContext inputContext)
       at Microsoft.TeamFoundation.Server.WebAccess.Controllers.ApiCommonController.GetNews(Int32 maxCount)

This is how it looks like in the log:

Event

It is pretty clear that the action called GetNews on the ApiCommonControler was unable to fulfill the Http request it made. This is because my TFS is behind a proxy server for what concerns the web access.
In order to set the access for the TFS application via a proxy, you need to locate the correct web.config file, which in may case is present in C:\Program Files\Microsoft Team Foundation Server 14.0\Application Tier\Web Services.
What you will need to do is to edit that file and under the system.net section add the following:

<system.net>
    <defaultProxy>
    	<proxy usesystemdefault="True" proxyaddress="http://swg.eu.myproxy.com:8080" bypassonlocal="True"/>
    </defaultProxy>
</system.net>

Make sure the correct proxyaddress is set and give your TFS main portal page a go. If all went as expected and your settings are valid, you should see the following:

after

That’s it. It may not be an essential setting, however it is nice to see that there are no errors in the event log and that your users do get a full experience.

Cheers

Detailing TFS configuration – IIS

One of the most annoying things when it comes to accessing the TFS portal is that you need to specify the context path /tfs. In other words, if you just type http://mytfs.com:8080 you will not get redirected to your application, which has the full path of http://mytfs.com:8080/tfs. Same if SSL is used, often and by default you are obliged to indicate the https or even worst in case SSL is made mandatory, you will get a nice 403.

Well this is a bit of shame. Many people standing behind and supporting TFS are often not keen to set this details up. This can be because of the leak of knowledge, “fear” of the unknown, negligence, character. It is such a simple operation that shows that you do care. So let’s check a couple of things you can do in order to make this happen.

The Beauty Is In the Details

There are several improvements that we can make on IIS that is running our TFS instance. I will try to make you a couple of suggestion, if some of them can’t apply on your case by any reason, it is not mandatory to set them. Following are just suggestions on how to tide up your default TFS installation.

The cleanup

Often I do see on the IIS of TFS server a Default Web Site. In 99,9% of the cases it is not used. If that is also your case (running only TFS on that machine) you are safe to remove it.

iis-initial

As you can see, aside of the Team Foundation Server site, there is the Default Web Site in my case. I will just right click it and choose Remove.

remove-default

After you removed the Default Web Site, you can do the same for all unused Application pools.

app-pool-remove

As from the image, get to the Application Pools and remove all of the pools which name doesn’t start on per Microsoft Team Foundation.

The redirect

It will be handy that in the browser you do not need to type over and over the context path of /tfs. In order to set this up we can leverage the Http Redirect feature of IIS. By default it is not installed thus we will need to add it. Open Server Manager and choose Manage -> Add Roles and Features.

server-manager-add-role

Now get to the Server Roles and under Web Server (IIS) – Web Server – Common HTTP Features select the HTTP Redirects.

add-roles-http-redirection

Conclude the installation procedure and restart the IIS Manager.
Now after selecting your Team Foundation Server site, you will see the HTTP Redirect feature.

http-redirect

Select this option by double clicking it and enable the Redirect Requests as set on the following image.

set-redirect

In the text box you will need to enter the full URL of your TFS comprehensive of the context path. Now, once the IIS recieves a request towards the root of your application it will redirect it towards your TFS application, called tfs. Make sure before Applying these settings that the Only redirect requests to content in this directory (not subdirectories) is selected, otherwise all of your calls will result in an recursive redirect. Apply these settings and try calling your server without the context path. If you are monitoring your web calls with tools like Fiddler, you will see that your first call is redirected by the server towards the URL we specified under the Redirect request option.

This technique is only working with your portal and browser. You will always need to specify the full URL in your Visual Studio or any other tooling that requires the TFS path. This is because they are not able to understand the redirect and act in the way your browser does. Keep this in mind.

Connecting people

By default TFS will set it’s default port to 8080. Again if it is the only application on your server it is a shame being in need to specify the port for the each call. What about letting it replay also to a port 80, which is the default http port and doesn’t need to be specified?
Welcome bindings. Select your Team Foundation Server and chose in between the available actions the one called Bindings. You will be presented with the following screen.

site-bindings

Make sure that aside the http binding to port 8080 there is the one that binds the requests to the port 80. If it is not there, first edit the current binding of port 8080 and change it to port 80. Then add a new one and make it replay to port 8080. Click close and try calling your TFS without specifying the port 8080. Your IIS should replay correctly.

The result of this change will work with all of the tooling accessing TFS, like Visual Studio. You are now not anymore obliged to specify the port 8080.

Talking under four eyes

It may be a good idea or a necessity to use transport layer security. Enabling HTTPS on you web site is fairly simple. How to create and import a certificate is out of the scope of this post. Given that you have correctly imported a certificate into the IIS certificate store, open the site binding and add a new one.

add-site-binding-ssl

As a type choose https and select the certificate that you intend to use for TFS.
From now on, you can point to https://yourTFS/tfs and you will be using a secure connection. In case you omit the context path, you will end up on a non protected connection. To sort that out, change your redirect and make it point to the secure version of link.

Also you may desire to make the HTTPS mandatory. If that is the case, you could simply enable Require SSL option under SSL Settings for your TFS Web Site.

require-ssl

If you do so, pointing to a non SSL version of your site will result in a 403 Forbidden response. Although it is self explanatory as a message it is not nicely handled. It would be nicer if you would be redirected to the https version of your request. For that, we can use a trick. Open Error pages pane and edit the 403 page.

custom-error-403

Set the Respond with a 302 redirect and set your desired https URL. Now, instead of showing a Forbidden message, your browser will be automatically redirected to a correct link.

Note that in case you set the SSL mandatory, you need to do it for both the WebSite and the Virtual folder usually called tfs. After you set both of them to be required, you will need to open the TFS Administration console and on Application Tier screen, choose the Change URL’s action:

change-urls2

Make sure that Notification and server URL are correctly set to point to the new link, otherwise you may experience some issues with TFS Administration console and some other local tooling.

Conclusion

I showed you a couple of tips on how to set you TFS IIS in order to be more friendly in responses and to remove the unnecessary things. There are other tips I may have on this argument, however they do fall in a maintenance domain, such as managing log files, etc. Soon I will publish a separate, more detailed blog post about this argument.

Cheers