Manage Artifacts with TFS Build vNext

Artifacts and Build vNext

Another big improvement of Build vNext in TFS and VSO is the ability to explicitly manage the content of artifacts during a build. With the term Artifacts in Continuous Integration we are referring to every result of of the build that is worth publishing together with build result, to be further consumed by consumers of the build. Generally speaking think to artifacts as build binary outputs.

The XAML build system does not give you much flexibility, it just use a folder in the build agent to store everything, then upload everything to the server or copy to a network share.

To handle artifacts, vNext build system introduces a dedicated task called: Publish Build Artifacts.

Publish Build Artifacts options

Figure 1: Publish artifacts task

The first nice aspect is that we can add as many Publish Build Artifacts task we want. Each task requires you to specify contents to include with a  default value (for Visual Studio Build) of **\bin to include everything contained in directories called bin. This is an acceptable default to include binary output of all projects, and you can change to include everything you want. Another important option is the ArtifactName, used to distinguish this artifacts from the othter ones. Remember that you can include multiple Publish Build Artifacts tasks and Artifact Name is a simple way to categorize what you want to publish. Finally you need to specify if the artifact type is Server (content will be uploaded to TFS) or File Share (you will specify a standard UNC share path where the build will copy artifacts).

Artifacts browser

With a standard configuration as represented in Figure 1, after a build is completed, we can go to the artifacts tab, and you should see an entry for each Publish Build Artifacts task included in the build.

List of artifacts included in build output.

Figure 2: Build details lists all artifacts produced by the build

You can easily download all the content of the folder as a single zip, but you can also press button Explore to explore content of the artifacts container directly from web browser. You can easily use Artifacts Explorer to locate the content you are interested into and download with a single click.

With artifacts browser you can explore content of an artifacts directly from browser and download single contents.

Figure 3: Browsing content of an artifact

Using multiple Artifacts Task

In this specific example, using **\bin approach is not probably suggested approach. As you can see from previous image, we are including binaries from test projects, wasting space on server and making more complex for the consumer to find what he/she needs.

In this specific situation we are interested in publishing two distinct series of artifacts, an host program and a client dll to use the host. In this scenario the best approach is using two distinct publish artifacts task, one for the client and the other for the host. If I reconfigure the build using two task and configure Contents parameter to include only the folder of the project I need, the result is much better.

Multiple artifacts included in build output

Figure 4: Multiple artifacts for a single build output

As you can see from previous image, using multiple task for publishing artifacts produces an improved organization of artifacts. In such a situation it is simple to immediately locate what you need and download only client or host program. The only drawback is that we still miss a “download all” link to download all artifacts.

Prepare everything with a Powershell Script approach

If projects starts to become really complex, organizing artifacts can start to become a complex task. In our situation the approach of including the whole bin folder for a project is not really good, what I need is folder manipulation before publishing artifacts.

  • We want to remove all .xml files
  • We want to change some settings in the host configuration file
  • We need to copy content from other folders of source control

In such a scenario, Publish Artifacts task does not fulfill our requirement and the obvious solution is adding a Powershell Script in your source code to prepare what you are calling a “release” of artifacts. A real nice stuff about PowerShell is that you can create a ps1 file with the function that does what you need and declare named parameters

Param
(
    [String] $Configuration,
    [String] $DestinationDir = "",
    [Bool] $DeleteOriginalAfterZip = $true
)

In my script I accepts three parameters, the configuration I want to release (Debug or Release), destination directory where the script will copy all the file, and finally if you want the script to delete all uncompressed files in DestinationDirectory.

The third option is needed because I’d like to use 7zip to compress files in output directory directly from my script. The two main reason to do this are

  • 7zip is a better compressor than a simple zip
  • It is simpler to create pre-zipped artifacts

Using Powershell script has also the great advantage that it can be launched manually to verify that everything goes as expected or to create artifact with the exact same layout of a standard build, an aspect that should not be underestimated. Once the script is tested on a local machine (an easy task) I have two files in my output directory.

Content of the folder generated by PowerShell script

Figure 5: Content of the output folder after PowerShell script ran

One of the biggest advantage in using PowerShell scripts, is the ability to launch it locally to verify that everything works as expected, instead of standard “modify”, “launch the build”, “verify” approach needed if you use Build Tasks.

Now I customize the build to use this script to prepare my release, instead of relying on some obscure and hard to maintain string in Publish Artifact Task.

Include a Powershell Task in the build to prepare artifacts folder

Figure 6: PowerShell task can launch my script and prepare artifacts directory

Thanks to parameters I can easily specify: current configuration I’m building (release, debug), DestinationDir (I’m using the $(build.stagingDirectory) variable that contains the staging directory for the build). You can use whatever destination directory you want, but using standard folder is probably the best option.

After this script you can now place a standard Publish Build Artifacts task, specifying $(build.stagingDirectory) as the Copy Root folder, and filtering content if you need. Here is the actual configuration.

Publish build artifacts taks can be used to publish Powershell output

Figure 7: Include single Publish Build Artifacts to publish from directory prepared by PowerShell script

The only drawback of this approach is that we are forced to give an Artifact Name that will be used to contain files, you cannot directly publish pre-zipped file in the root source of build artifacts. If you want you can include multiple Publish Build artifacts to publish each zipped file with a different Artifact Name.

Build artifacts contains a single artifacts with all zipped file

Figure 8: Output of the build

But even if this can be a limitation, sometimes can be the best option instead. As you can see from previous image, I have a primary artifact and you can press the Download button to Download Everything with a  single click. Using Artifact Explorer you can download separate packages, and this is probably the best approach.

Artifacts browser permits you to download single zip files

Figure 9: Artifact browser shows distinct zip file in the output

If you use a Script to create one separate pre-compressed package for each separate artifacts, your publish experience will probably be better than any other approach.

Conclusions

Build vNext gives us great flexibility on what to publish as artifacts, but even if we can manage everything with dedicated task, if you want a good organization of your artifacts, using a PowerShell script to organize everything and pre-compressing in single files is usually the best approach.

Gian Maria.

Unable to debug dll source code with symbol server

I’ve blogged in the past about using a Symbol server and I recommend to all people to use symbol servers whenever possible, to helping people troubleshooting problem on dependencies. Basically with a symbol server you can reference a dll in your project, but you can debug original source code as if you have the original project linked instead of having the dll.

Sometimes this process just don’t work. Recently I’have a customer that had problem with this scenario, and the real strange stuff is: I’m able to step in dll source code without problem from any machine, but noone of the customer’s developers are able to make it work. After I’ve sent them detailed instruction it worked, and we were able to track down the problem.

Visual Studio has a nice option to cache symbols in local directory to avoid downloading each time from the server. Here are my usual settings.

Visual Studio options to use local folder as a symbol cache

Figure 1: Visual Studio symbols settings

Developers in customer sites decided to use a subfolder of %TEMP% directory and this was the cause. As soon as they moved symbol cache to something like c:\symbols everything starts working. The underling cause is probably due to long paths.

If you have problem using symbol server, try using a really short path for your Symbols Local Cache directory.

In this specific situation we are using free symbols server in conjunction with MyGet nuget package feeds. In my machine here is the location for a source file during debugging.

Z:\Symbols\src\pdbsrc\MyGet\alkampfer\11111111-1111-1111-1111-111111111111\BIGEND\GianMariaRicci\Jarvis.Framework.Kernel\2C5AB5CBD1C74688974B2DDB55F51EDA1\Jarvis.Framework.Kernel\ProjectionEngine\ConcurrentProjectionEngine.cs

Usual %TEMP% variable is something like c:\users\gianmaria.ricci\appdata\local\temp (this is my system and it is long 44 characters), so it is not a good idea to use it for symbol source cache.

Since it is really easy to have really long path for your source when you use a symbol server, it is always a good idea using a short path for symbols cache directory, something like x:\SymSrc is probably the best solution.

If this does not solves your problem, another suggestion is using Fiddler to inspect the traffic between your Visual Studio and the Source Server to understand what is happening.

Gian Maria.

Git for windows, getting Invalid username or password with Wincred

If you use Https to communicate with your git repository, Es, Github or VisualStudioOnline, you usually setup credential manager to avoid entering credential for each command that contact the server. With latest versions of git you can configure wincred with this simple command.

git config --global credential.helper wincred

This morning I start getting error while I’m trying to push some commits to GitHub.

$ git push
remote: Invalid username or password.
fatal: Authentication failed for 'https://github.com/ProximoSrl/Jarvis.DocumentS
tore.git/'

If I remove credential helper (git config –global credential.helper unset) everything works, git ask me for user name and password and I’m able to do everything, but as soon as I re-enable credential helper, the error returned. This problem is probably originated by some corruption of stored credentials, and usually you can simply clear stored credentials and at the next operation you will be prompted for credentials and everything starts worked again. The question is, where are stored credential for wincred?

If you use wincred for credential.helper, git is storing your credentials in standard windows Credential Manager

You can simple open credential manager on your computer,

image

Figrue 1: Credential manager in your Control Panel settings

Opening Credential manager you can manage windows and web credentials. Now simply have a look to both web credentials and windows credentials, and delete everything related to GitHub or the server you are using. The next time you issue a git command that requires authentication, you will be prompted for credentials again and the credentials will be stored again in the store.

Gian Maria.

Build vNext, support for deploying bits to Windows machines

One of the most interesting trend of DevOps movement is continuous deployment using build machines. Once you get your continuous build up and running, the next step is customizing the build to deploy on one or more test environments. If you do not need to deploy in production, there is no need of a controlled release pipeline (Ex: Release Management) and using a simple build is the most productive choiche. In this scenario one of the biggest pain is moving bits from the build machine to target machines. Once build output is moved to a machine, installing bits is usually only a matter of using some PowerShell script.

In Build, Deploy, Test scenario, quite often copying build output to target machine is the most difficult part

Thanks to Build vNext solving this problem is super easy. If you go to your visualstudio.com account, and choose the TEST hub, you can notice a submenu called machines.

image

Figure 1: Machines functionality in Visualstudio.com

This new menu is related to a new feature, still in preview, used to define groups of machine that can be use for deploy and testing workflows. In Figure 1 you notice a group called Cyberpunk1. Creating a group is super-easy, you just need to give it a name, specify administrative credentials and the list of the machines that will compose the group. You can also use different credentials for each machine, but using machine in Active Directory domain is usually the simplest scenario.

image

Figure 1: Editing of machine groups

Actually this feature still does not support Azure Virtual Machines, but you can easily target machine in your on-premise infrastructure. You just need to be sure that

  • All machines are reachable from the machine where the build agent is running
  • Check your DNS to verify that the names resolution is ok
  • All target machines should have Powershell remoting enabled
  • All target machines should have sharing of file system enabled
  • Firewall port are opened.

I’ve tested with an environment where both machines are running Windows Server 2012 R2, with latest update and file sharing enabled. Once you defined a machine group, you can use it to automatically copy files from build agent to all machines with a simple task of build vNext.

SNAGHTML3b78ea

Figure 3: Windows machine File Copy task

Thanks to this simple task you can simply copy files from build machine to destination machine, without the need to install any agent or other components. All you need to do is choose the machine group, target folder and source folder.

If you get error running the build, a nice new feature of build vNext is the ability to download full log as zip, where all the logs are separated by tasks

image

Figure 4: All build logs are separated for each step, to simplify troubleshooting

Opening the file 4_Copy … you can read logs related to the copy build step, to understand why the step is failing. Here is what I find in one of my build that failed.

Failed to connect to the path \\vsotest.cyberpunk.local with the user administrator@cyberpunk.local for copying.System error 53 has occurred. 
 2015-06-10T08:35:02.5591803Z The network path was not found.

In this specific situation the RoboCopy tool is complaining that the network path was not found, because I forgot to enable file sharing on the target machine. Once I enabled file sharing an running again the build everything was green, and I can verify that all files were correctly copied on target machines.

As a general rule, whenever a build fails, download all log and inspect the specific log for the task that failed.

image

Figure 5: Sample application was correctly copied to target machines.

In my first sample, I’ve used TailspinToys sample application, I’ve configured MsBuild to use StagingDirectory as output folder with parameter OutDir: /p:OutDir=$(build.stagingDirectory) and thanks to Windows Machine File Copy task all build output is automatically copied on target machines.

Once you got your build output copied on target machine, you need only to create a script to install the new bits, and maybe some integration test to verify that the application is in healthy state.

Gian Maria

Build vNext and continuous integration on GitHub

One of the great news of build vNext is the ability to create a build that targets source on GitHub project, not only on Git or TFVC repositories that are in current TFS or VSO instance. Given this, plus the fact that VSO has a 5 basic user license for Free, and you can use VSO as Continuous integration Engine for your GitHub projects.

To create a build that targets GitHub source code, you should simply login into your GitHub account, then navigate in your personal settings and finally choose “Personal Access tokens”

image

Figure 1: Personal access tokens in GitHub

I do not want to cover how GitHub tokens works, but basically each token has a set of capabilities associated with it, so you can decide the level of access bounded with each token. This is particularly important if you want to use that token to access only your public repositories and not the private ones.

image

Figure 2: Access levels associated to your token

Once you have a valid token you should write it down securely in some tool (I use KeePass) because the UI of GitHub will not give you way to easily retrieve that token. Once you have the token you can instruct VSO to create Continuous Integration build.

The first step is having a VSO account and create a Team Project, I’ve called my team Project GitHub, then navigate to the Build Tab. Once you press the Green Plus Button you are asked for the type of the build, I choose Visual Studio for this example because my GitHub Project contains Visual Studio solution.

Once the build editor is opened, you can go to Repository tab, then choose GitHub as repository type, and insert previously generated Access token. If the token is good, just wait for few seconds, and you should be able to see the list of GitHub repositories you have access to.

image

Figure 1: Configure the build to take sources from GitHub

Thanks to the access token, VSO build infrastructure can check if the repository gets new push, if you go to the Triggers tab you can ask VSO to trigger a build for each push in all the branches you want to monitor.

image

Figure 2: You can use CI even if the repository is on Git Hub

This is all you need to create a build. To verify that everything is ok you can simply trigger a new build, and, if the build has no specific requirement, you can use the Hosted Agent offered by VSO to build your project.

You can safely remove the Index Sources & Publish Symbols, because VSO cannot index source code outside your account. If you leave this task on the build, you will have warning during build.

image

Figure 3: Remove Indexing Sources task from your GitHub build.

Finally, in the General Tab, you can ask VSO to generate a Badge for the build.

image

Figure 4: Badge build

A badge is a simple url that renders an image that specify if the latest build succeded, failed or partially succeeded. Once you have a badge, you can include on the wiki page of your project in GitHub, simply including in the Readme.MD file in project root.

image

Figure 5: Build badge in action.

Et voilà, with few clicks you have Continuous Integration for GitHub Project using Visual Studio Online.

Gian Maria.