Dangl.Blog();

Signing Electron Apps before Bundling with Azure Key Vault and EV Code Signing Certificates

Wed, 18 Aug 2021 20:42:54 Z

Just a few days ago, I've blogged about running E2E tests for an Electron app. But, once tested and verified, the next step is deployment.

If you've ever shipped an application for Windows users, you might be aware of the Windows SmartScreen filter. It's basically a check that might pop up and warn your users in case Microsoft doesn't have any data on your app being trustworthy. That's actually a great feature, since it encourages application developers to sign their programs and therefore increase overall app security. Except for when your build pipeline becomes compromised, as in the recent SolarWinds attack...

However, I'd like to focus on the technical aspects. For code signing certificates, there are two options available: Either a regular certificate, which has quite a low bar for verification and is available for less than 100,- € per year, or an Extended Validation (EV) certificate. The EV ones are much pricier, and do require the certificate issuer to perform a more in-depth check before handing it out. You pay more, but you get more: In contrast to regular certificates, which require a certain number of installs until Windows SmartScreen recognizes them as trustworthy, EV certificates work out of the box and don't show any warnings to your users. So, for anything commercial, you probably want to go with an EV certificate.

But it also comes with a catch: You usually need some hardware device to secure it, often an USB dongle or a Hardware Security Module (HSM). That's just a requirement for the heightened security about EV certificates, but this also means that it's harder to integrate it in automated build workflows. You don't want to be in a position where you need a dedicated build computer in your office where you manually need to insert some USB dongle to generate a release.

Here comes Azure Key Vault: It's a service available in the Azure Cloud which just kind of does everything around securing stuff, hence the name. It's typically used for things like secret management, e.g. to handle configuration for cloud services and the like, or just for plain SSL certificate management, e.g. with Let's Encrypt management via shibayan's key-vault-acme-bot. The part that's interesting for us in this article, however, is that the premium tier of Azure Key Vault allows you to store certificates on a HSM, securely on Microsoft infrastructure.

When going that way, you give up the option of exporting the certificate, e.g. temporary to your build server to sign applications. That would introduce too much of a security risk, so you need to remotely use the signing feature of Azure Key Vault to sign your apps.

And this is where this blog post is headed: When building an Electron app, you've got two steps. First, you build & publish the app, then it's getting packaged. Now, you want to sign both outputs, the actual *.exe files in the bundle as well as the installer itself. So, I'll show you some code that performs the build, calls a hook between the publish and package step to sign everything, and then finally signs the installer itself. All done via remote signing in Azure Key Vault.

I'm a big fan of the NUKE build system, so I'm using that for the actual build automation. The concept should be easily translatable to whatever system you're using. So, let's look at the code finally!

First, we're starting with this build script:

The part above is the target in NUKE that generates the Electron bundle. In this specific example, we're even using Electron.NET, since the app itself is really just a website that some customers want to use as a desktop application. I won't go into too much detail here, since the build process should be pretty straightforward. It's really just a wrapper around electron-builder with something injected here and there.

This second part is a bit more interesting here. The electron.manifest.json is your app definition, we're configuring, for example, that the Windows target should use the nsis installer. But the real fun is on line 11: We're defining a JavaScript file that is called during the build, in our case right after the built-in signing task is completed.

electronAfterPackHook.js, again, is a simple script. It's really just calling back out to the NUKE build system to run the SignExecutables target and passes the current output directory as an argument. The magic here is that this is now called during your build, after the executable has been created and patched with the icon, but before it's being bundled up by the installer.

Finally, we're using the AzureSign package to sign our executable with the certificate in Azure Key Vault.

After everything's done here, the build continues. At the end, the parent NUKE process just signs the installers and we're done. The next step would be publishing, for us that means generating the documentation and deploying the artifact.

So, you've seen we're really doing something like in the movie Inception: We're calling our build system from a hook from a build process initiated by the build system itself. It feels a bit Rube-Goldberg-y, but it works fine and is pretty simple to setup & understand.

Happy signing!

Running Fully Automated E2E Tests in Electron in a Docker Container with Playwright

Thu, 12 Aug 2021 07:03:26 Z

If you've read some of my previous articles, you probably know that I'm kind of obsessed with rigorous testing - I'm advocating for having a good, automated quality control for every project I encounter. It's probably one of the biggest time savers there is in software development, whether it's because you catch regressions early or you've got lots of infrastructure set up so that reproducing bugs is a matter of minutes instead of hours.

For one of our apps, we've got a bit of a complex setup. The backend is a traditional ASP.NET Core application with the usual moving parts, a relational database, some blob storage and the compute part of the app itself. That's easy to test on its own.

The frontend part deviates a bit from our regular architectures. Due to the nature of the app, it's built and deployed as an Electron application. Electron is a great tool that I've blogged about previously, but it comes at a cost. It gets the most flak for being inefficient, whether it's due to it having a large memory footprint (both in storage and memory), or being less fast than native applications. However, the upsides are great - since Electron is really just a wrapper around Chromium, it allows you to build desktop applications with all tried & tested web technologies. This makes it a natural choice when your team is building web applications usually and can therefore transition seamlessly to an Electron project.

However, Electron feels sometimes a bit like building on sand - it works really well, but there are a lot of moving parts under the hood. One obstacle we've encountered was around testing the full application in an end-to-end (E2E) way. To ensure such tests run in a controlled environment, independent of whatever host is currently executing, we're using a small Docker setup to spin up the entire infrastructure, test it and then tear it down again. That works pretty well with regular web apps, but not so much with Docker.

When we first started setting this up, we've ran into lots of problems. The biggest maybe was a lack of community information around this issue - it just seemed like not a lot of people are executing such tests, so there was not a lot to be found except small bits here and there. We've finally managed to get it up in the end, but even an external consultant specializing in that area was struggling to set it up. One of the major hurdles was that while there are lots of tools for automating browsers that work fine in Docker, there are not a lot of options when it comes to Electron.

Then came last week, when we updated the Electron version. That immediately broke our build. It turned out that Spectron, the test runner for Electron, doesn't have any active maintainers left. And it also looked like we're not the only ones affected by this.

Luckily, there's a new player around, trying to offer a modern and stable way for browser automation: Playwright by Microsoft. It does have official Electron support, is actively maintained and, due to it being just a bit over a year old, was able to use a modern and easy to use API approach.

After spending some hours on trying to get the original test setup fixed, we've decided to give Playwright a try. To our amazement, it just worked! It took just about an hour to set everything up and migrate the tests. And, our E2E tests started being green again🚀

I'll try to give you a condensed summary of what we did to get it running, and how it was set up. In reality, we're also spinning up the other services, like backend, database and blob storage, put all the Docker containers in the same network and therefore simulate the app as close to the production environment as possible. But, let's take a look at it file by file:

We start with a Dockerfile. That's a rather simple one, the few things worth mentioning are:

We're building from the node image, since a lot of dependencies are already present there
Some tools need to be installed around display drivers, most importantly xvfb which will act as a virtual display inside the Docker container
A custom entrypoint for the container is provided to execute a script at container start

The entrypoint itself isn't complicated, either. When looking around for running xvfb in Docker, you'll often find similar snippets. Ours was, in fact, also mostly copied from various sources. Its really just making sure that a virtual display is available before the actual command is run

The common-setup.ts file is a base for all our tests. Here, we're using playwright and launch a new instance of the app for every test. As you can see, the API could probably not be simpler here, yet it works flawlessly.

Finally, some tests. They're shortened, but give you a small indication what's possible with playwright, or automated E2E tests in general.
We do usually aim for two things with such tests:

We want to get quick feedback to see if the app is generally running, is it able to start, do we get any script errors in the console, can users log in and such
Additionally, we usually have full E2E tests for the critical paths in our applications. For example, can new users register, confirm their email, login, start a trial and then upgrade to a paid subscription? Generally, things a QA department would do but that are easy to automate

It's sometimes tedious to write such tests, and you most likely won't ever have your full app covered with them. But they're a huge confidence boost, especially when your pipeline automatically deploys right into production.

Finally, to actually run the tests, we're just spinning up the Docker container with a script like the one above. The important part here is that we're now calling docker run to execute end to end tests in the container. We're doing some more optimizations, like using tmpfs for the node_modules folder and mounting the app directory into the container. But in the end, the tests run and we're getting a test results file out that can be processed in CI systems.

So, happy testing!

Let's use NUKE to Quickly Deploy an App to Azure via Zip Deployment

Mon, 12 Oct 2020 20:15:01 Z

It's no secret I'm a big fan of the NUKE build system, it's making my life just so much more convenient! So here's a small real world example that demonstrates how easy it is to deploy a static website to an Azure App Service using NUKE and Kudu Zip Deployment. You can check out the repository here if you want to see it all.

Recently, I was going through some old repositories on my GitHub account for the occasional cleaning - just checking if something needs an update, or is no longer working. My antlr-calculator project hadn't been updated in a while, and the demo site was still hosted on a virtual server. So, a great task to kill an evening was found! I decided to update the build system from just some CLI commands to use NUKE and to additional move the hosting to an Azure App Service.

Many think that for using NUKE to automate your build, you need a .NET project. But while NUKE leverages C# to set up your build, you can actually use it to automate any task you want. For example, here's how you build an NPM package:

Or, in this case, build & deploy a static website to Azure. Let's go through this step by step. First, we define the Target DeployDemo in Nuke. It's set up to invoke the Clean target and specifies some required parameters:

Next, we use NPM to build the site and update a placeholder in index.html for the version:

Then we get the Base64 encoded authentication header value to deploy to Azure and zip the output into a Zip file:

Finally, we POST this zip file to the Kudu API and wait for a response:

That's it! Now you've deployed a small websites to Azure. With build automation servers, like Jenkins, GitHub Actions or Azure Pipelines, you can configure your build scripts to run on every commit.

Happy automating!

Running SQL Server Integration Tests in .NET Core Projects via Docker

Tue, 22 Sep 2020 19:51:36 Z

I'm a huge fan of test driven development. It helps me deliver fewer defects in my apps and gives me confidence that my changes don't break any existing features.

While I write mostly unit tests that run quickly, I try to also have lots of integrations tests for all API endpoints in my web applications. This typically involves code that hits a database, so I had to find some way to easily spin up database instances for my tests. I'm a firm believer that running tests should only involve a single command, so relying on any existing database on the build agent was a hard no for me. Additionally, multiple instances might run in parallel on the same machine, e.g. when different branches are built at the same time.

My initial approach has always involved using a SQLite in memory database, actually a fresh one for every single test. This worked well, was fast enough and dead easy to set up. However, it had one huge problem: I'm not running SQLite in production, so I wasn't really testing the system under the same circumstances and additionally, I could not test features that involved database specific behavior.

Typically in such a situation, most developers would use a containerized database, such as Microsoft SQL Server. But most approaches like this that I've seen were a bit ugly: the database usually had to be spun up manually before running tests, or at least via a build script. But I wanted a way that works independently of how the tests are run - whether via my build script, by running dotnet test or just by clicking Run in the Visual Studio Test Explorer.

Luckily, I've found the great Docker.DotNet library which allows you to access the Docker Daemon directly in your C# code, e.g. during test setup and teardown methods. The integration & setup for such integration tests is then pretty straightforward, but requires a bit of code to get it reliably working. Just follow the snippets below and you should be able to set up something similar!

The class DockerSqlDatabaseUtilities is where Docker.DotNet is referenced - it's purpose is to ensure that a Microsoft SQL Server Docker image is running and ready for connections.

Next, SqlServerDockerCollectionFixture is a test fixture that essentially just orchestrates the Docker setup and implements XUnit's IAsyncLifetime interface.

Further down, we're specifying a custom TestFramework in AssemblyInfo.cs, since we'll be running the test setup from the previous fixture class only once per assembly, and that's not supported out of the box in XUnit. You could refactor the code to internally track if the setup has already been performed, or simply use the Xunit.Extensions.Ordering as test framework😀

Another class I'm using is TestHelper. You can guess from the name that it's offering supporting methods during testing, such as providing an in memory instance of our OpenID Service Dangl.Identity and performing the actual setup of our in memory ASP.NET Core backend, which is what we actually want to test.

Finally, we've got an abstract base class IntegrationTestBase that all our tests inherit from. TestHelper is actually provided as a dedicated instance per test, which means that we can run all tests in parallel yet still fully isolated from each other.

Does this approach work for you? Tell me in the comments!

Happy testing!

Simple and Quick Way to Backup Jenkins to Azure Blob Storage

Sun, 14 Jun 2020 14:52:13 Z

For years, I've been a happy user of Jenkins to automate all our Continuous Integration & Continuous Delivery CI/CD steps. Just recently, I've been evaluating some other, more modern platforms. While trying out GitHub Actions and Azure DevOps, I've been generally satisfied, but found that both don't fit perfectly for what I want. GitHub Actions is still in it's early stages and lacks many features, and with Azure DevOps I've felt the setup to be a bit too complicated and tightly integrated with Azure services. Jenkins just could do everything quite well while giving you lots of freedom.

These findings resulted in me not changing the existing setup too much - two servers, one running Windows and one on Linux worked fine so far. However, I've been a bit unsatisfied with the server's performance characteristics. The instances were on some virtual servers that were approaching their 4 year mark, so I decided to switch to two up to date, dedicated machines.

This led me to rethink the backup process. Previously, a cronjob just backed up all the Jenkins data daily to a network share that was provided by the server hosting company, and that felt a bit too outdated and makes accessing backups actually more complicated than necessary. So I decided to just Backup the data to Azure Blob Storage. However, there was no ready made solution that I could find, so I had to roll my own.

Luckily, Jenkins uses just file storage in it's JENKINS_HOME directory for all configurations, from users to jobs to plugins, so backing up the configuration is actually pretty easy - just copy the parts you want to be backed up. For this, I decided to directly leverage Jenkins itself to run the backup jobs, with a simply script that backs up the data to a Zip file and uploads it to the cloud.

Essentially, it boils down to two parts, all of them are available directly on GitHub. First, the Jenkinsfile which configures the job itself:

It's really just doing two things: Specify a trigger that runs once a month and then invoke the actual backup script. If your master is not a Windows machine, just call build.cmd BackupInstance instead of the PowerShell version.

The script itself leverages the NUKE build automation tool, which itself is an awesome asset that I've blogged about previously. It's an engine that lets you write build scripts in .NET and execute them anywhere. This backup script is a great example - it doesn't require anything preinstalled, you just run build.cmd and it works! You can view the full script here.

Happy Automating!

Set Up Private NuGet Feeds with ProGet v5

Fri, 16 Feb 2018 10:27:19 Z

I've previously blogged about setting up ProGet and then written about the changes in ProGet Version 4. This post is a small update to them. While nothing from the setup side has changed, there have been updates to the way feeds work and you have to migrate legacy feeds to the new format.

Previously, I've recommended to configure an API key that is used for pushing changes. Having had such a key made unauthorized operations on the feed impossible, and hence required either the key itself or user credentials. Requests using the API Key were considered to be from the Anonymous, meaning unauthenticated, user. This should still be the case when you upgrade and don't migrate legacy feeds, but you have probably configured package publishing permissions for the "Anonymous" user when you've worked with API keys.

This becomes a problem once you do upgrade! Feeds no longer have a dedicated API key, but the permission for Anonymous to publish packages stays in place. I've found no mentioning of it in the docs, so please be careful when you migrate feeds from the legacy format to check if you have any open permissions left.

With the latest feeds, I also no longer recommend using an API key but instead to create a dedicated user with push access. ProGet stores API keys in plaintext, which is something you should avoid to use if possible. With an user account, you can use it's username:password instead of the key. To do so, create an user via the admin interface and then switch to Tasks where you should assign both Publish Packages and View & Download Packages permissions to the user:

The View & Download Packages permission is not required in all cases, but some (older) NuGet clients do make a GET request to the feed before they publish a package and hence may need permission to view packages.

Happy publishing!

Integration Testing In Memory Compiled Code with Roslyn - Visual Studio 2017 Edition

Sat, 03 Feb 2018 16:12:43 Z

Have you ever written code to generate code? Probably.

Have you ever written proper integration tests for that? Probably not.

This is a follow up post to last years article, which was still about the now deprecated project.json format

Everyone's done it - write code that writes code. Be it for converting from an esoteric Domain Specific Language, generating from a set of known data or for any other reason. It happens a lot, it's useful a lot, but it's not tested a lot. Testing such code has always been inconvenient, did involve a lot of disk IO and quite often relied on scripts and manual work. Luckily, with dotnets Roslyn compiler, there are NuGet packages for code analysis and compilation available that make all of this so easy!

The complete sample repository is available at GitHub. Here are the interesting parts:

It starts with the CodeGenerator which does what it's name implies - it creates code. In this case, it's a simple class that has one method: AddIntegers().

This InMemoreCompilation.Tests.csproj is a regular, xUnit enabled, project configuration file. There is a reference to the Microsoft.CodeAnalysis.CSharp package. That one will bring the Roslyn API to your project.

The actual integration test class is quite big, so let's break it down into it's functional units:

GenerateCode() does just that - it gets the string representation of the sourcecode
CreateCompilation() takes the sourcecode, adds assembly references and turns it into a CSharpCompilation object
CompileAndLoadAssembly() now invokes the Roslyn API to compile onto a MemoryStream, then loads it and makes the content available
Finally, CallCalculatorMethod() uses reflection on the newly generated assembly and invokes the AddIntegers() method

This is a really interesting approach on tackling code generation. While I got the initial bits to set this up from Tugberk Ugurlus blog, I've had a project of my own where I did some heavy code generation (for correcting Xml documents) where I needed that. There's also code that works both in .Net Core and the full .Net framework.

Happy compiling!

Using WebDeploy via Nuke Build Scripts

Sat, 27 Jan 2018 19:04:11 Z

Some days ago, I read about NUKE, which is kind of like Make, Cake and FAKE. Besides breaking the rhyme, it's looking really promising and takes an interesting approach for build configuration.

Update: I've now published the package on NuGet: Nuke.WebDeploy

I'm mostly using PowerShell scripts for all my automation, and have also tinkered a bit with dotnet script. PowerShell scripts are really easy to use, but complex tasks have a tendency to become brittle and, since I'm no where near being an expert, always require a bit of trial and error. Scripting with C# is great, but is often not easy to set up. Now there's NUKE, which lets you write build scripts in regular .Net projects. Overall, the experience with it was quite good for me, and I've migrated one of our projects at work already.

One of the missing bits in NUKE is the support for Microsoft WebDeploy. I'm using it a lot, both for deploying to Azure as well as IIS. Unfortunately, there's no NuGet distribution available for the command line utility, it must be installed on the machine executing the build. However, there's a Microsoft.Web.Deployment package on NuGet which exposes the complete WebDeploy API. I'm working on releasing a NuGet package for NUKE, based on Cake.WebDeploy. In the meantime, you can simply use the code on this Gist to deploy to Azure or IIS with WebDeploy using NUKE. This snippet shows a shortened build config. The Deploy target is executing WebDeploy:

You can simply build, publish and deploy your website with PowerShell, for example in a Jenkins build:

Happy building!

Creating Correct Source Code Links with DocFX in Jenkins

Sun, 12 Nov 2017 22:06:50 Z

If you haven't used it yet, you should check out DocFX to automate your documentation generation. It's working great with .Net Core projects, is simple to use and easily customizable. It's also got a feature to link directly from your documentation to source code on GitHub, but this comes with a small catch: When running the build in Jenkins, DocFX uses an environment parameter GIT_BRANCH set by Jenkins. This leads to broken links, since the variable is, for example, origin/dev when it should only be dev. This also prevents the links from being versioned, so documentation of old versions won't have the historic source code available.

But since this being Jenkins, there's nothing we can't do to solve this! In every build, there's an environment variable GIT_COMMIT provided which, as the name suggest, is the full hash of the checked out commit.

All you need to to is run this small PowerShell script to fix links in your generated Html files:

If you're looking for a bit more info on automating documentation generation, have a look at these two points:

The LightQuery package is configured to generate docs on build. Most importantly, there's a GenerateAndDeployDocs.ps1 script at the root doing all the work.
For publishing, I've created WebDocu. It's an Asp.Net Core app that lets you host online documentation with versioning and user management for non-public projects. You can take a look at it right here, a few of my projects have their docs publicly available.

Happy documenting!

Publish Azure Functions via Jenkins CI Continuously to Azure

Mon, 06 Nov 2017 17:13:21 Z

We're not exactly heavily oriented towards a microservice architecture, but we do use them a fair bit for some resource intensive methods. I'm pretty happy with Azure Functions, especially with the parts that I can automate: I'll describe how to setup a simple Jenkins job that builds your function and deploys it automatically to Azure Functions.

In your projects repository, you need a build script to compile your function, like this:

It's not too complicated, but I want to highlight these points:

Following best practices, $deployUsername and $deployPassword are passed as parameters to the function so we're not storing any sensitive date in source control
dotnet build doesn't yet work with Azure Functions, so the script is using MSBuild. It's easiest to get by simply installing the Visual Studio 2017 Community Edition on your CI server (which I recommend anyways, since it comes with all the SDKs you ever need)
You have to insert your own values for the placeholders, <ProjectFolder> and <FunctionName>. This could also be parameterized if you intend to have a more complex deployment scenario

In Jenkins, you simply call this script and provide the required parameters:

I really encourage you to use something like the Credentials Binding Plugin to provide your secrets. Otherwise, it's as simple as a setup can be. You can set up Git Hooks or use the GitHub plugin to automatically build whenever you push new code.

If you're wondering where to actually get your deployment credentials, they're included in the Publishing Profile that you can download for the function in the Azure portal.

Happy deploying!

Publish and Deploy Asp.Net Core Applications from Jenkins to IIS - 2017 Edition

Sun, 22 Oct 2017 14:11:38 Z

If you have an Asp.Net Core application that you want to continuously deploy to either Azure or IIS on a Windows Server, you should follow the following, simple steps.

This is a follow up post to last years article. It's updated for the Visual Studio 2017 project format.

Get the Required Tools on the CI Server

Just like with unit testing in a CI environment, you’ll need the .Net Core SDK to be available to Jenkins. It’s available at the official download site. Make sure you've got matching SDK and runtime versions, as you might encounter issues with xUnit if you have a later SDK installed with no matching runtime.

Additionally, if you're using IIS instead of an Azure Web App, you need the .Net Core Windows Server hosting bundle on the hosting server, available on the same site. See the official documentation for how to install it.

You will also need to install Node.js and npm on the server that is hosting Jenkins so you can run all the prepublish commands for an Asp.Net Core application. To install Node.js, go to its download site and grab the latest Windows installer. When installing, make sure that Add to PATH is enabled in the install options (it is by default), so that the npm command is added to the PATH environment variable and therefore directly recognized in the command line interface.

Make sure to restart Jenkins after you've added the tools, as the PATH variable is only read at startup and not watched for changes!

Tip: It's not required to globally install node modules like bower or gulp on the build server. That should be handled by node.js’ devDependencies and proper pre- and postpublish scripts in your deployment process.

Finally, the Web Deploy tool should be installed on your server to easily deploy to IIS and Azure from the command line.

Configure Jenkins to Build the Project

In Jenkins, just create a new project and configure the source code management, for example by pulling from a Git repository. To build, publish and deploy, the following commands are necessary. They're explained in detail in the next section.

Windows Batch
cd src\<ProjectFolder>
dotnet publish -c Production -o publish
The dotnet publish command restores, builds and publishes the web application. With -o publish, we're specifying the output folder to be /publish, relative to the project directory.
Windows PowerShell (optional)
cd src\<ProjectFolder>
./TransformWebConfigForProduction.ps1
There's no built in support in the dotnet CLI currently that allows the transformation of web.config files, so we're calling a custom PowerShell script to do it for us before deploying.
Windows Batch
"C:\Program Files (x86)\IIS\Microsoft Web Deploy V3\msdeploy.exe" -verb:sync -source:IisApp='%WORKSPACE%\src\<ProjectFolder>\publish' -dest:iisapp='<SiteName>',computerName='<WebDeployEndpoint>/msdeploy.axd?site=<SiteName>',authType='basic',username='<DeployUsername>',password='<DeployPassword>' -enableRule:AppOffline
Uses Web Deploy to copy the publish folder to the server. You might have to adjust the path to msdeploy.exe if it's different on your machine.

Publish the Project

The first build step switches to the project directory and then calls dotnet publish -c Production -o publish.

To make sure your pre- and postpublish scripts run, include them in your package.json (for npm) and project.csproj (for dotnet) files, for example like this:

This combination would effectively run the npm install command first, followed by bower install, gulp clean and gulp min, then compile and publish the application via dotnet CLI. This example is from the WebDocu project, a very simple MVC website. You can get a bit more creative for your apps, for example by using the Angular CLI to build your Single Page App front end bundles and copy them into your wwwroot folder before publishing.

The WebConfigTransformRunner dependency is optional. It's to get the console tool via NuGet if you intend to run web.config transformations in the next step.

Run web.config Transformations (optional)

To run web.config transformations from the command line, make sure the WebConfigTransformRunner tool is referenced in your project and call this script in your project directory:

If you want to read more about manually running web.config transformation, see here.

Publish to IIS with Web Deploy

For the next step, you should have set up Web Deploy on both the source and target server. There’s only one step needed, and that is calling msdeploy.exe to publish the app to IIS or Azure.
When doing that, you must supply valid credentials for the user that has publishing rights in IIS. In Azure, you can simply download the publish profile in the Web App settings and extract the deployment username and password.

Since it’s never a good idea to include plain text user credentials in a script or build step, you should set up credentials in Jenkins and use these as variables in your build step.

The command for web.deploy is rather long:

"C:\Program Files (x86)\IIS\Microsoft Web Deploy V3\msdeploy.exe" -verb:sync -source:IisApp='%WORKSPACE%\src\<ProjectFolder>\publish' -dest:iisapp='<SiteName>',computerName='<WebDeployEndpoint>/msdeploy.axd?site=<SiteName>',authType='basic',username='<DeployUsername>',password='<DeployPassword>' -enableRule:AppOffline

ProjectFolder
That's simply where the project is inside your Jenkins workspace.
SiteName
The name for the site. This is rather important since the WebDeploy service will determine whether or not the user has access to the service depending on the site name that is specified here.
WebDeployEndpoint
You should just specify the Url endpoint for the WebDeploy service. You either configure it manually in IIS or just download the publish information for an Azure Web App. Here's a post about configuring Web Deploy on IIS.
DeployUsername
The username for the user who you gave access to WebDeploy. You should really use Jenkins credentials for this instead of pasting the actual username and password in your Jenkins job.
DeployPassword
Should be clear – Provide the user accounts password

Specyfing -enableRule:AppOffline means that your app is taken offline during the deployment process to avoid file locks.

verb:sync makes sure to sync our publish folder with the server, so this is the operation (“verb”) to perform

If you want to dig further into msdeploy, these three links from the technet contain a lot of info:

Summary

Now you should be able to click on “Build now” and let the magic happen, continuous deployment for your .Net Core website. It's good practice to configure triggers for your job. I often use branches for workflow control, e.g. I have a job that deploys a website to a staging (or testing) environment whenever a push happens to the develop branch.

Happy Deploying!

Publish .Net Core Code Coverage Results with ReportGenerator in Jenkins

Wed, 11 Oct 2017 16:24:11 Z

I've blogged before about automating your .Net Core test, deploy and coverage work flow with Jenkins. When visualizing coverage reports, I'm usually sticking to what's built into Jenkins. I've dabbled with the ReportGenerator before, but was content with the well-known Cobertura Plugin.

The only working solution currently that supports both .Net and .Net Core for capturing code coverage, OpenCover, doesn't output the Cobertura format by default and thus needs the OpenCoverToCoberturaConverter. Recently, it's author, Daniel Palme, suggested I could try out the ReportGenerators new version. Since he's the author of a library I use in literally every single project, both private and at work, I was excited to check the ReportGenerator out again. In short: It's great! The visualization looks modern, chic and it's enriched with additional metadata such as cyclomatic complexity and the famous CRAP score.

It's also really simple to set up. Please check out this sample project, which you can either clone or download directly, to have a basic starter for a .Net Standard library with .Net Core unit tests, including code coverage. It's fairly simple to get started and have a great foundation for expaning your code base. You only need to know these steps to get more confidence in your code evolution:

A PowerShell script, TestsAndCoverage.ps1, which runs the tests, gathers coverage data and builds the Html report:

A Jenkins instance configured to check out your code, run the script and publish both your test results and the generated report:

After your first run, there'll be a Code Coverage Report entry in your Jenkins job that gives you a detailed breakdown of your coverage. You can even easily configure additional features such as keeping a history with ReportGenerator.

As always, spend some minutes at the beginning of your project to configure automatic testing, coverage and reporting on every code push and you'll save future-you a ton of trouble later when you've already acquired a lot of technical debt.

Happy Analyzing!

Target and Visualize Results of Multiple Frameworks in .Net Unit Tests with Jenskins CI

Mon, 02 Oct 2017 10:56:30 Z

In the example project, the unit test project is configured with multiple TargetFrameworks. This is to ensure that tests are being repeated on all target platforms and catch differing runtime behavior early. There are a few cases where there are differences, so it should be best practice for you to run your tests in as many configurations as possible. See the project file below how to set up such a project.

With xUnit and Jenkins, you ideally have a configuration that tests your code on every commit, so you'll have test results available that look like this:

When you take a look at the detailed results, you see that your tests are repeated for every target framework. This is great, since it means that all tests are actually run, but you're not getting information about the framework in which a failure occurred. You've just got the same test repeated, with the exact same name. Luckily, if you launch dotnet xunit and don't specify an explicit framework, it will by default run tests across all specified frameworks and amend the output files with the framework name.

This makes it easy to add information about the test framework before publishing in Jenkins with the xUnit plugin: Get the framework name from the test results filename and prepend it to the type attribute of every run test case. The above test script calls into a second helper script to do just that:

Suddenly, you have detailed information about every run test case and can much easier identify problems and reproduce them when they arise:

Happy testing!

Continuous Deployment from Jenkins to a NuGet Feed

Fri, 01 Sep 2017 20:18:48 Z

Code sharing via separate assemblies is an ideal way of separating concerns and benefiting from code reuse. For this, it's great to have continuous deployment of development builds when you're iterating fast and only creating manual releases when deemed necessary.

Personally, I'm hosting my private projects on a ProGet instance and the public ones are either on NuGet, or for dev releases on MyGet. Configuring your project is easy:

Instead of using the Version attribute, you're setting the VersionPrefix to the next higher one since your last release. Additionally, a conditional VersionSuffix is appended if the current branch is origin/dev (or whatever development branch you're using). This means your package version will be something like 1.4.1-build-19 in development and when you finally merge to master, it's 1.4.1. Both BUILD_NUMBER and GIT_BRANCH are environment variables provided by Jenkins.

Having a project like this requires then a bit of configuration in Jenkins to deploy to your package feed, MyGet in this example:

I'm using the Credentials Plugin to inject my MyGet API key into the build. The project is configured to auto-package when built in the Release configuration. Then, the package is searched and publish via the NuGet command line utility to my feed. Now on every build, I get a new package pushed to my feed that's available for consumption downstream right away.

When you push to master and want to make your package available directly via NuGet, just download the package from MyGet and release on NuGet. It's not getting any easier!

Happy deploying!

Unit Testing and Code Coverage with Jenkins and .NET Core - 2017 Edition

Sat, 19 Aug 2017 18:14:42 Z

Last year, I've blogged about setting up Jenkins with the then just released .Net Core ecosystem. This is an updated post to target the latest dotnet CLI and MSBuild-based csproj format that was introduced with Visual Studio 2017.

This post shows you how to use Jenkins as your Continuous Integration system, a project that supports netstandard, .Net Core or the full .Net Framework, xUnit as test runner and OpenCover to generate the coverage reports. Jenkins will also report any compiler warnings and open tasks you may have in your project (such as // TODO comments). You will need a Windows environment on your CI server, otherwise check here for instructions on Linux.

Required Tools

Obviously, you have to install the .NET Core SDK. It is available at the official dot.net site and installs the dotnet CLI tool and registers it globally for all users on the PATH variable. If you intend to run tests for the full .Net Framework, you have to install the right SDKs for that. I found just installing Visual Studio 2017 with all the .Net SDKs quite simple for that.

In Jenkins, four plugins are required:

xUnit Plugin to evaluate test results
Cobertura Plugin for the code coverage data
Warnings Plug-in to scan for compiler warnings
Task Scanner Plugin to scan for open tasks

Since we're using OpenCover, the code coverage results must be transformed to the Cobertura format before they're published in Jenkins. The OpenCoverToCoberturaConverter NuGet package should be included as a build-time dependency (<PrivateAssets>All</PrivateAssets>) in your test project. OpenCover works both for .Net Core as well as the full .Net Framework. It's slowing the process quite a bit down, though, so consider splitting larger projects into unit test jobs with code coverage and plain integration or acceptance test jobs without OpenCover.

You TestProject.csproj should look like this:

The xunit, xunit.runner.visualstudio and Microsoft.NET.Tests.Sdk packages are required for xUnit, while the dotnet-xunit CLI tool allows us to run tests directly with dotnet xunit and supply xUnit parameters instead of going through dotnet test. OpenCover and OpenCoverToCoberturaConverter are build time dependencies, both are included in the project. During package restore, the tools are copied to your local .nuget folder. The TargetFrameworks are set to whatever frameworks you want to test. I suggest to always test .Net Core and the full .Net Framework if your project targets netstandard, since sometimes there are slight differences that may crop up by testing against multiple supported platforms. For example, the System.Text.Encoding package behaves different between these two.

Configure your Project under Test

To allow OpenCover to record coverage, it needs to have access to the actual source code. This is easiest done by configuring your project under test to output debug symbols (pdb files) when compiling for debug. This is only required in your actual project, not in your test projects. If your Code Lens support in Visual Studio seems broken and you can't navigate to test cases from the Test Explorer, you might accidentally generate symbols for your test projects, too. This currently messes with xUnit / the Visual Studio test discovery engine and inhibits Code Lens support and mapping from reported test cases to actual code. Configure your project under test like this:

At the root of your project, you need a PowerShell script to run your tests. I like the script approach, since it gives me a reproducible, single-click way (#2 on the Joel Test) to test my project.

Tip: Here's a simpler script if you only want to run tests and no code coverage.

It's doing three things:

Locate the OpenCover tools via the NuGet cache
Run xUnit tests with attached OpenCover
Convert OpenCover results to Cobertura for later processing

Configure the Job in Jenkins

In Jenkins, there's only one simple Execute Windows Batch Command step required:

powershell.exe -NoProfile -ExecutionPolicy Bypass ./TestsAndCoverage.ps1

After the nuget packages have been restored, the dotnet xunit command is available and your tests can run. Every configured test project is tested against all targeted frameworks while the coverage is being recorded. It's not strictly necessary with this script, but it's good advice to configure a job to clean the workspace before each checkout whenever results are written to disk, to be sure no previous runs contaminate your results.

Evaluate Results in Jenkins

In total, four post build actions are required to evaluate all results in Jenkins. Add and configure the tasks as shown below for a great CI experience.

Scan Workspace for Open Tasks

This is great for finding all those // TODO and // HACK things that accumulate in every project. It is part of measuring technical debt and allows you to visually track when you should commit to your backlog and chose refactoring over new features. Or, at least, it gives you a bad feeling when the graph rises...

Scan for Compiler Warnings

Similar to Open Tasks, but usually more severe. This task captures all warnings reported during the dotnet build (or MSBuild) process. I'm a big fan of a zero-warnings tolerance, and this report certainly shows you when it's out of hand. In my experience, a lot of compiler warnings directly translate to a lot of bugs and runtime errors, so treat these seriously.

Publish Cobertura Coverage Report

The PowerShell script generates these *.coverageresults files in the workspace directory, you just need to pick them up. But be wary of too strict metrics on code coverage, as I've often seen goals of having a certain percentage of coverage required. In my experience, the most important thing is to have a solid base from where you start and to not have the coverage decline when the code base grows. This makes sure that your changes and additions are properly covered by tests, but you don't have to waste your time writing tests just to have every conditional hit.

Publish xUnit Test Result Report

Probably the most important task, checking if the code actually does what it's supposed to do. You can configure custom thresholds for when a build is considered a failure, but I can't imagine a case where more than zero would be an acceptable answer here.

Don't forget to add an E-mail notification action at the end, being informed in detail and on time is the most important aspect of CI!

View the Results in Jenkins

Your job view in Jenkins will now display four graphs on the right side for a quick visual overview of your project's health, with more information being available via the menu options. This configuration has been working good for me for all project's I've encountered, and if you want, you can even easily integrate your front end JavaScript (or TypeScript) tests into your job if what you're building is a web project.

Happy Testing!

.Net Core and TypeScript Continuous Integration Testing with Jenkins on Linux

Mon, 29 May 2017 20:52:08 Z

I've previously blogged about the NetCoreHeroes project, an Asp.Net Core demo app that features an Angular frontend. It's been my learning project for getting a nice WebDev experience in Visual Studio and Jenkins, and recently there's been interest in getting it to work in Linux.

Being a traditional Windows and .Net guy, I've never done a lot with Linux, but I wanted to see how easy it actually is. It actually is pretty easy and took me only two evenings of getting everything up and running on Linux. I've used a Hyper-V virtual machine with Ubuntu Server 16.04, but results should be comparable across distributions.

Install Hyper-V

On a Windows host system, you've got to install the Hyper-V role. I'm running it on an Intel NUC with an Atom processor. It sits somewhere behind the TV in the living room, is ridiculously slow, but gets the job done and costs about 300,- €.

From the Server Manager, go to Add Roles & Features, select the Hyper-V role, confirm the GUI and PowerShell management tools and click on next until you’re in the configuration tab for Virtual Switches. Since the VM will need internet access, you’ll want to select a network interface through which you’ll connect the virtual machines to the outside world.

In an ideal world, your virtualization host has multiple LAN ports, with a dedicated one for the virtual machines. However, the NUC behind the TV doesn't have that, so we’ll accept the risk and move on. This is mostly a problem for connectivity, since misconfiguration might make your machine unavailable.
You don’t need to add support for Live Migrations for this example and can go with the default storage locations for VM configuration and hard disks.

Setup the Virtual Machine

Download Ubuntu Server

Go to https://www.ubuntu.com/download/server and download the current Long Term Support (LTS) version of Ubuntu Server. At the time of writing, that’s 16.04.2.

Provision the VM

In the Hyper-V manager, create a new virtual machine. I've assigned it 2GB of RAM and a 20GB Hard Disk, this should be plenty for a simple Jenkins instance and one Asp.Net Core demo site. Generation 2 VM have the newer features with the drawback of not being compatible with any hosts pre Windows Server 2012.

Install Ubuntu Server & Jenkins

When provisioning the VM, I’ve selected to install an operating system from an image and chose the *.iso that was downloaded earlier for Ubuntu Server. After the VM has been provisioned, you need to change its firmware settings to deactivate Secure Boot since that’s not compatible with Ubuntu Server. After that, simply connect to it and power it on.

This tutorial doesn't cover how to install & setup Ubuntu Server itself. The setup is quite self explanatory (which I would not have expected from Linux if you had asked me a week ago).

For the Jenkins installation, DigitalOcean has a great tutorial that you should follow. However, I configured the firewall to only allow incoming traffic to Jenkins for my private home networks IP range: sudo ufw allow from 192.168.1.0/24 to any port 8080. In case your firewall is disabled in Ubuntu (ufw status returning inactive), run sudo ufw enable to activate the firewall. After the initial setup, Jenkins is running in your Linux VM:

Install Development Environment & Tools

On the build server, you’ll need dotnet and npm available.

First, follow the official Microsoft .Net Core Linux installation instructions to enable dotnet support. To install npm, run these commands:

curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
sudo apt-get install -y nodejs

Jenkins Plugins

This one is easy. There’s already support for jUnit test results in Jenkins, meaning the TypeScript tests are already supported. For the xUnit based dotnet tests, install the xUnit plugin in Jenkins and you’re good to go.

Configure Jenkins

The NetCoreHeroes project has both .Net and Angular unit tests that are going to be run in Jenkins.

The project's SCM git repository is located at https://github.com/GeorgDangl/NetCoreHeroes/. You can take a look at the project to get a starting point for your own CI builds. For Linux, I've had to deviate a bit from my standard configuration. The awesome Chutzpah JavaScript test runner is only available for Windows, so I had to switch to Karma for the Linux environment. I get that the Karma runner is actually much more used, but it doesn't integrate as seamlessly in Visual Studio. In the NetCoreHeroes posts series, I've described the complete way from setting up the project to a fully automated testing and deployment scenario with Windows.

Back to Linux, here's the Jenkins build configuration:

And the post build actions to publish the test results:

Save the config, click on Build Now and take a look at what your unit tests have to tell you:

HeroService.HeroService getHeroes should have expected fake heroes (from PhantomJS 2.1.1 (Linux 0.0.0))

.Net Core and Linux really IS easy!

Happy platform-independant testing!

Integration Testing In Memory Compiled Code with Roslyn

Fri, 07 Apr 2017 19:20:49 Z

Have you ever written code to generate code? Probably.

Have you ever written proper integration tests for that? Probably not.

There is now a follow up article that uses the latest .Net project format in Visual Studio 2017. This post is still displaying the now deprecated project.json configuration

The complete sample repository is available at GitHub. Here are the interesting parts:

It starts with the CodeGenerator which does what it's name implies - it creates code. In this case, it's a simple class that has one method: AddIntegers().

This project.json is a regular, xUnit enabled, configuration file. There is a reference to the Microsoft.CodeAnalysis.CSharp package. That one will bring the Roslyn API to your project.

The actual integration test class is quite big, so let's break it down into it's functional units:

GenerateCode() does just that - it gets the string representation of the sourcecode
CreateCompilation() takes the sourcecode, adds assembly references and turns it into a CSharpCompilation object
CompileAndLoadAssembly() now invokes the Roslyn API to compile onto a MemoryStream, then loads it and makes the content available
Finally, CallCalculatorMethod() uses reflection on the newly generated assembly and invokes the AddIntegers() method

Happy compiling!

Set Up Private NuGet Feeds with ProGet v4+

Thu, 20 Oct 2016 20:27:09 Z

In an earlier post, I described how to get started with Inedos ProGet. It's a nice tool that lets you self host your own packages with a lot of supported repository types, like NuGet or npm. Lately, they've transitioned to version 4 with big changes to the UI so I thought I could post a small update, focusing on what has changed.

Install & Configure ProGet

Installation and initial configuration is nicely covered by their documentation, so I won’t go into much detail here. There was just one bit missing in the documentation that caused some troubles for me: When you’re using MS SQL Server, it’s possible that your default collation is different to the one ProGet will try to set during the database initialization, so make sure to create the ProGet database with SQL_Latin1_General_CP1_CI_AS collation and you’ll not run into issues, otherwise ProGet might fail to apply its database schema during installation.

To keep your feeds private, go to the settings page, then navigate to Manage Users & Tasks, select the Tasks and remove the Anonymous group from View & Download Packages. I've not yet discovered how to completely lock down v4 of ProGet, but this settings disables any access for non-authenticated users.

To access feeds, I'd recommend creating a regular user and then adding a permission for this user to View & Download Packages. This way, you'll have a login that works to privately access your repository feeds.

Enable NuGet Package Publishing with an Api Key

Usually, you can simply set an Api Key for NuGet package publishing in the feeds options according to the documentation. You do need to allow the Anonymous user the package publish right then, however. Since the built in task comes with quite a lot more privileges (like viewing the feed and pulling packages), it's best to create a new task that only has the Add Package privilege for publishing. Some NuGet versions, however, do have a quirk where before doing a push, they're making a GET request and run into authentication issues. For example, NuGet 3.3.0 does have this behavior while 3.4.4 does not. If there's some reason you can't upgrade the NuGet version you're using for publishing, you'll have to create a user for publishing and additionally grant him the View Feed rights and then use default NuGet authentication in addition to the api key when publishing packages.

To create the task, click on Customize Tasks in the tasks menu and select the Add Package and View Feed (if you're using a designated user for publishing) privilege under Feeds, then save the task and assign the Anonymous user to it (or your publisher!).

Tip: Use this command to locally save user credentials in NuGet: nuget source add -Name <NameOfTheStoredCredentials> -Source <YourNuGetFeedUrl> -User <Username> -Pass <Password>

If you want to continue reading, the old post covers a bit more about creating packages and deploying them via a Jenkins CI solution.

Publish and Deploy Asp.Net Core Applications from Jenkins to IIS

Thu, 23 Jun 2016 20:42:58 Z

Update: There's a follow up post that's using the new Visual Studio 2017 project format.

Get the Required Tools on the CI Server

Just like with unit testing in a CI environment, you’ll need the .Net Core SDK to be available to Jenkins. It’s available at the official download site. Additionally, on the hosting server, you need the .Net Core Windows Server hosting bundle, available on the same site. See the official documentation for how to install it. You will also need to install Node.js and npm on the server that is hosting Jenkins so you can run all the prepublish commands for an Asp.Net Core application.
To install Node.js, go to its download site and grab the latest Windows installer. When installing, make sure that Add to PATH is enabled in the install options (it is by default), so that the npm command is added to the PATH environment variable and therefore directly recognized in the command line interface.

Make sure to restart Jenkins after you've added the tools, as the PATH variable is only read at startup and not watched for changes!

Tip: It's not required to globally install node modules like bower or gulp on the build server. That should be handled by node.js’ devDependencies and proper pre- and postpublish scripts in your deployment process.

Configure Jenkins to Build the Project

In Jenkins, just create a new project and configure the source code management, for example by pulling from a Git repository. To build, publish and deploy, the following Windows batch command steps are necessary:

dotnet restore
Restores NuGet packages for all projects below the workspace folder.
Note that right now, private (password protected) NuGet feeds are not working with the dotnet cli, see this issue on GitHub. You can resolve that by storing the password in plain text in NuGet.config.
cd "%WORKSPACE%\<PathToProject>"
dotnet publish -c EnvironmentName
Changes directory to the actual project folder and runs the publish command. Replace the EnvironmentName with whatever you want to use for publishing.

To make sure your pre- and postpublish scripts run, include them in your package.json (for npm) and project.json (for dotnet) files, for example like this:

project.json:

"scripts": {
    "prepublish": [ "npm install", "npm run prepublish" ],
    "postpublish": [ "dotnet publish-iis --publish-folder %publish:OutputPath% --framework %publish:FullTargetFramework%" ]
  }

package.json:

"scripts": {
      "prepublish": "bower install && tsc && gulp clean && gulp copyClientDeps && gulp min" 
    }

This combination would effectively run the npm install and npm run prepublish commands first, then compile and publish the application via dotnet cli and finally run the dotnet-publish-iis command.

Additionally, before deploying, you might want to run a web.config transformation as described here.

Publish to IIS with Web Deploy

For the following step, you should have set up Web Deploy on both the source and target server. There’s only one more step needed, and that is calling msdeploy.exe to publish the app to IIS.
When doing that, you must supply valid credentials for the user that has publishing rights in IIS. Since it’s never a good idea to include plain text user credentials in a script or build step, you have to save them manually to the Windows credentials store. For that, log into your CI server with the user account for Jenkins, open a command prompt and execute the following command:

"C:\Program Files (x86)\IIS\Microsoft Web Deploy V3\msdeploy.exe" -verb:dump -source:Iisapp=YourSiteName,computerName='https://WebDeployUrl:8172/msdeploy.axd?site=YourSiteName ',userName='Username',password='Password',authType='Basic',storeCredentials='StorageName'

YourSiteName
The name for the site. This is rather important since the WebDeploy service will determine whether or not the user has access to the service depending on the site name that is specified here.
WebDeployUrl
You should just specify the Url endpoint for the WebDeploy service (that was configured earlier). If you’re not having an SSL certificate for that (or none at all, because you’re free to use any dns name for the MSDeploy service on Port 8172), you can add the parameter “-allowUntrusted”, which ignores SSL errors. But you should really try not to ignore SSL errors in any setting, especially in a CI environment where it’s never ever gonna be resolved again…
Username
The username for the user who you gave access to WebDeploy. You might possibly have to include the network domain name in the form of “domain\user” or, if it’s a local user, the servers computer name as “serverComputerName\user”.
Password
Should be clear – Provide the user accounts password
StorageName
This is the key under which the credentials will be stored in Windows' Credentials Manager, you’ll later retrieve them by going like “use credentials for StorageName”

The authType=’Basic’ parameter is not strictly required. If your happen to be in an Active Directory domain, you could also use Windows Authentication and completely omit any credentials in the Web Deploy process.
The verb=dump will result in msdeploy listing you the contents of the remote location (upon successful authorization), so you know you've got it right when you see that. (or see no error messages, since we haven’t yet deployed any files=)
As per the msdeploy documentation, the credentials will be stored even if the response is a 401 – Unauthorized, so keep that in mind if you're just testing stuff. Also, the path to the msdeploy.exe may vary on your installation if you chose not to install it in the default location.

Now that we've stored the credentials we can finally approach the last line of commands we’re going to need for the Jenkins job:

"C:\Program Files (x86)\IIS\Microsoft Web Deploy V3\msdeploy.exe" -verb:sync -source:IisApp='%WORKSPACE%\publish -dest:iisapp='YourSiteName',computerName='https://WebDeployUrl:8172/msdeploy.axd?site=YourSiteName',getCredentials='StorageName',authType='Basic' -enableRule:DoNotDeleteRule - -enablerule:AppOffline

verb:sync
We want to sync our publish folder with the server, so this is the operation (“verb”) to perform
source:IisApp='%WORKSPACE%\publish
The publish directory, will be by default like bin\EnvironmentName\Platform\publish below the project folder
dest
The destination where we want to deploy to. YourSiteName and the WebDeployUrl should be adjusted to your needs, as well as the StorageName under which you stored the credentials. It’s the same command you used to store the credentials earlier.
enableRule:DoNotDeleteRule
This is playing on the safe side, the setting prevents files from being deleted on the server if they’re not present in the source. It’s not required for most applications and might cause troubles when your website folder contains old files. So say, for example, you only want to keep your AppData folder where you store local files for your site, then just swap this command with
-skip:Directory=\\App_Data
You can chain multiple rules, so you can always exclude additional folders from the deployment.
enablerule:AppOffline
This will copy an app_offline.html file before the operation and remove it afterwards, telling IIS to shut the site down during the deployment process. It’s so you don’t get any conflicts where DLLs are still loaded and can’t be overwritten.

If you want to dig further into msdeploy, these three links from the technet contain a lot of info:

Summary

Here’s a screenshot of all three required build steps:

Now you should be able to click on “Build now” and let the magic happen, continuous deployment for your .Net Core website. Have fun!

Setting Asp.Net Core Environment Variables via web.config in IIS

Thu, 09 Jun 2016 23:32:44 Z

Since RC2, hosting .Net Core apps within IIS is no longer using the common HttpPlatformHandler as with any other processes but instead the ASP.NET Core Module for Windows Server Hosting.

While not a lot has changed, the Xml schema for the web.config elements is new, so you need to specify environment variables the following way in your main web.config file:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="%LAUNCHER_PATH%" arguments="%LAUNCHER_ARGS%" forwardWindowsAuthToken="false" stdoutLogEnabled="true" >
      <environmentVariables>
        <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
      </environmentVariables>
    </aspNetCore>
  </system.webServer>
</configuration>

Alternatively, you can still use regular web.config transformations for publishing to IIS (there's currently no support for that in dotnet-publish-iis), for example in your web.Production.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <system.webServer>
    <aspNetCore>
      <environmentVariables xdt:Transform="Insert">
        <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
      </environmentVariables>
    </aspNetCore>
  </system.webServer>
</configuration>

Applying web.config Transformations without MSBuild

Thu, 09 Jun 2016 22:29:21 Z

There are certain cases where you deploy a website to IIS, rely on a web.config file but don't have MSBuild in the build process, like deploying .Net Core or php apps.

ASP.Net Web Config Transform Runner to the rescue! That's a nice, little command line tool wrapper around the Microsoft.Web.Xdt package. I'm using that to deploy .Net Core and reverse proxy configurations to IIS where I'm not having any MSBuild step in the deployment process.

Applying the Transformations

The PowerShell script below can be used in Continuous Integration systems like Jenkins or simply as part of a scripted deployment.

$configuration = "Production"                  # The name of the configuration, e.g. "Release" to apply transformations from web.Release.config
$wwwRoot = $ENV:WORKSPACE + "\PublishFolder"   # The folder under which to recursively look for web.config files
$deleteAfterTransformation = true              # true if web.*.config files should be deleted after the process
# Get path to WebConfigTransformationRunner
# INFO: Supply manual value to "WebConfigTransformRunner.exe" for $latestWebConfigTranformator if it isnt restored via "dotnet restore"
$webConfigTransformatorPackages = Join-Path -Path $env:USERPROFILE -ChildPath "\.nuget\packages\WebConfigTransformRunner"
$latestWebConfigTranformator = Join-Path -Path ((Get-ChildItem -Path $webConfigTransformatorPackages | Sort-Object Fullname -Descending)[0].FullName) -ChildPath "Tools\WebConfigTransformRunner.exe"
# Find all directories containing web.config foles
$webConfigDirs = Get-ChildItem -Path $wwwRoot -Recurse -Filter "web*.config" | Select -Property Directory -Unique
ForEach ($directory in $webConfigDirs.Directory){
    # Check if file for transformation is present
    $transformationSource = (Get-ChildItem -Path $directory -Filter ("web." + $configuration + ".config"))
    if ($transformationSource) {
        # Found a file to apply transformations
        $guid = [Guid]::NewGuid().ToString()
        $transformArguments = @("""" + (Join-Path -Path $directory -ChildPath "web.config") + """",`
                                """" + $transformationSource[0].FullName + """",`
                                """" + (Join-Path -Path $directory -ChildPath $guid) + """")
        $transformationProcess = Start-Process -FilePath $latestWebConfigTranformator -ArgumentList $transformArguments -Wait -PassThru -NoNewWindow
        if ($transformationProcess.ExitCode -ne 0) {
            "Exiting due to web.config transformation tool having returned an error, exit code: " + $transformationProcess.ExitCode
            exit $transformationProcess.ExitCode
        }
        # Delete original web.config and rename the created one
        Remove-Item -Path (Join-Path -Path $directory -ChildPath "web.config")
        Rename-Item -Path (Join-Path -Path $directory -ChildPath $guid) -NewName (Join-Path -Path $directory -ChildPath "web.config") 
    }
    if ($deleteAfterTransformation) {
        # Delete all web.*.config files
        ForEach ($file in (Get-ChildItem -Path $directory -Filter "web.*.config")){
            Remove-Item -Path $file.FullName
        }
    }
}

The $configuration variable determines which sources for the transformations to use, e.g. setting it to Production will apply transformations from web.Production.config files
$wwwroot specifies which folder to search for web.config files. All child folders are searched as well
$deleteAfterTransformation indicates if web.*.config files should be deleted after the transformation has been applied. Set it to true to remove unnecessary files for publishing.

Attention: This script does automatically search for the latest WebConfigTransformRunner.exe in the default path on the system where dotnet caches NuGet packages to. If you manually download the tool, change $latestWebConfigTranformator to the full file path of the exe.

Unit Testing and Code Coverage with Jenkins and .NET Core

Mon, 30 May 2016 22:34:28 Z

Update 19.08.2017:

There's an updated version of this post that's targeted to the most recent tools and frameworks. It's simplified and uses the current dotnet CLI *.csproj format.

This post is describing a rather generic way of unit testing .Net Core projects and I've published quite a long script to achieve that. If you're happy with a really short and simple solution, you can read here how to set up basic unit testing for .Net Core and TypeScript.

This post is assuming a Windows environment. Check here for instructions on Linux.

Now that .NET Core RC2 has been released (this tutorial still works in the released versions, for example 1.0 and 1.1), there have been quite a few changes to the tooling around the stack. I've converted a small sample application (available at GitHub) and tried to set up the CI system for continuous testing and deployment. In this article, I'll describe how to perform unit test and code coverage analysis on the new platform.

Setup Required Tools

In order to successfully run unit tests and code coverage analysis for a .NET Core RC2 project, you first have to install the .NET Core Preview 1 SDK. It is available at the official dot.net site and installs the dotnet CLI tool and registers it globally for all users on the PATH variable.

In Jenkins, you'll need the following plugins:

PowerShell Plugin, since later there'll be a script that takes care of running the tests and collecting the data
xUnit Plugin to evaluate test results
Cobertura Plugin for the code coverage data
Html Publisher Plugin to show additional coverage reports

Additionally, add the following three dependencies to the project.json of your unit test project(s):

"dependencies": {
    "OpenCover": "4.6.261-rc",
    "OpenCoverToCoberturaConverter": "0.2.4",
    "ReportGenerator": "2.4.5"
}

Tip: If you're having trouble with the xUnit test runner, make sure to have at least version 1.0.0-rc2-build10025 of the dotnet-test-xunit package referenced.

OpenCover is the process that wraps around the actual dotnet test runner and collects coverage analysis. OpenCoverToCoberturaConverter translates the coverage reports into the Cobertura format for which there are Jenkins plugins. Additionally, ReportGenerator is a tool that creates some Html pages to visualize code coverage.

Configure the Job in Jenkins

Create a Execute Windows Batch Command as first build step with the single command dotnet restore, so that all projects within the workspace have their dependencies restored.

Tip: If you're using private NuGet feeds as package sources, the NuGet version that is bundled with the RC2 tooling does not support encrypted passwords but only plain text passwords in a NuGet.config file. See the NuGet documentation for how to setup clear text passwords for private repositories.

The second step is to execute the following PowerShell script (sorry for it being so long=):

$testProjects = @("src\Dangl.WebDocumentation.Tests")                                  # Array of test projects containing the xUnit tests you want to run, relative to the workspace directory
$filterRootNamespace = "Dangl"                                                         # If you only want to get coverage for a specific root namespace, eg. "MyCompany.*" Leave empty otherwise
$reportGeneratorHistoryPath = "C:\BuildCoverageReportHistories\Dangl.WebDocumentation" # Path where the history of the code coverage Html reports are stored - Must be outside the workspace so it does get. Leave empty if no history is wanted
# Modify the values below here if you need to - Standards should be fine
$dotnetPath = "C:\Program Files\dotnet\dotnet.exe"
$jenkinsWorkspace = $ENV:WORKSPACE # Use $ENV:WORKSPACE in Jenkins
$codeCoverageHtmlReportDirectory = "CodeCoverageHtmlReport"
$xUnitResultName = "xUnitResults.testresults"
$openCoverResultPath = Join-Path -Path $jenkinsWorkspace -ChildPath "OpenCoverCoverageReport.coverage"
$coberturaResultPath = Join-Path -Path $jenkinsWorkspace -ChildPath "CoberturaCoverageReport.coberturacoverage"
# Get the most recent ReportGenerator NuGet package from the dotnet nuget packages
$nugetReportGeneratorPackage = Join-Path -Path $env:USERPROFILE -ChildPath "\.nuget\packages\ReportGenerator"
$latestReportGenerator = Join-Path -Path ((Get-ChildItem -Path $nugetReportGeneratorPackage | Sort-Object Fullname -Descending)[0].FullName) -ChildPath "tools\ReportGenerator.exe"
# Get the most recent OpenCover NuGet package from the dotnet nuget packages
$nugetOpenCoverPackage = Join-Path -Path $env:USERPROFILE -ChildPath "\.nuget\packages\OpenCover"
$latestOpenCover = Join-Path -Path ((Get-ChildItem -Path $nugetOpenCoverPackage | Sort-Object Fullname -Descending)[0].FullName) -ChildPath "tools\OpenCover.Console.exe"
# Get the most recent OpenCoverToCoberturaConverter from the dotnet nuget packages
$nugetCoberturaConverterPackage = Join-Path -Path $env:USERPROFILE -ChildPath "\.nuget\packages\OpenCoverToCoberturaConverter"
$latestCoberturaConverter = Join-Path -Path (Get-ChildItem -Path $nugetCoberturaConverterPackage | Sort-Object Fullname -Descending)[0].FullName -ChildPath "tools\OpenCoverToCoberturaConverter.exe"
# Run unit tests with OpenCover attached for each test project
ForEach ($testProject in $testProjects){
    $testProjectPath = Join-Path -Path $jenkinsWorkspace -ChildPath $testProject
    # Create a unique output file name for the xUnit result
    $xUnitOutputCommand = "-xml \""" + (Join-Path -Path $jenkinsWorkspace -ChildPath ([Guid]::NewGuid().ToString() + "_" + $xUnitResultName)) + "\"""
    # Construct OpenCover arguments
    $openCoverArguments = New-Object System.Collections.ArrayList
    [void]$openCoverArguments.Add("-register:user")
    [void]$openCoverArguments.Add("-target:""" + $dotnetPath + """")
    [void]$openCoverArguments.Add("-targetargs:"" test " + "\""" +$testProjectPath + "\project.json\"" " + $xUnitOutputCommand + """") # dnx arguments
    [void]$openCoverArguments.Add("-output:""" + $openCoverResultPath + """") # OpenCover result output
    [void]$openCoverArguments.Add("-returntargetcode") # Force OpenCover to return an errorenous exit code if the xUnit runner returns one
    [void]$openCoverArguments.Add("-mergeoutput") # Needed if there are multiple test projects
    [void]$openCoverArguments.Add("-oldstyle") # Necessary until https://github.com/OpenCover/opencover/issues/595 is resolved
    if(!([System.String]::IsNullOrWhiteSpace($filterRootNamespace))) {
        [void]$openCoverArguments.Add("-filter:""+[" + $filterRootNamespace + "*]*""") # Check only defined namespaces if specified
    }
    # Run OpenCover with the dotnet text command
    "Running OpenCover tests with the dotnet test command"
    $openCoverProcess = Start-Process -FilePath $latestOpenCover -ArgumentList $openCoverArguments -Wait -PassThru -NoNewWindow
}
# Converting coverage reports to Cobertura format
$coberturaConverterArguments = New-Object System.Collections.ArrayList
[void]$coberturaConverterArguments.Add("-input:""" + $openCoverResultPath + """")
[void]$coberturaConverterArguments.Add("-output:""" + $coberturaResultPath + """")
[void]$coberturaConverterArguments.Add("-sources:""" + $jenkinsWorkspace + """")
$coberturaConverterProcess = Start-Process -FilePath $latestCoberturaConverter -ArgumentList $coberturaConverterArguments -Wait -PassThru -NoNewWindow
if ($coberturaConverterProcess.ExitCode -ne 0) {
    "Exiting due to CoberturaToOpenCoverConverter process having returned an error, exit code: " + $coberturaConverterProcess.ExitCode
    exit $coberturaConverterProcess.ExitCode
} else {
    "Finished running CoberturaToOpenCoverConverter"
}
"Creating the Html report for code coverage results"
# Creating the path for the Html code coverage reports
$codeCoverageHtmlReportPath = Join-Path -Path $jenkinsWorkspace -ChildPath $codeCoverageHtmlReportDirectory
if (-Not (Test-Path -Path $codeCoverageHtmlReportPath -PathType Container)) {
    New-Item -ItemType directory -Path $codeCoverageHtmlReportPath | Out-Null
}
# Create arguments to be passed to the ReportGenerator executable
$reportGeneratorArguments = New-Object System.Collections.ArrayList
[void]$reportGeneratorArguments.Add("-reports:""" + $openCoverResultPath + """")
[void]$reportGeneratorArguments.Add("-targetdir:""" + $codeCoverageHtmlReportPath + """")
if(!([System.String]::IsNullOrWhiteSpace($reportGeneratorHistoryPath))) {
    "Using history for ReportGenerator with directory: " + $reportGeneratorHistoryPath
    [void]$reportGeneratorArguments.Add("-historydir:""" + $reportGeneratorHistoryPath + """") # Check only defined namespaces if specified
} else {
    "Not using history for ReportGenerator"
}
# Run ReportGenerator
$reportGeneratorProcess = Start-Process -FilePath $latestReportGenerator -ArgumentList $reportGeneratorArguments -Wait -PassThru -NoNewWindow
if ($reportGeneratorProcess.ExitCode -ne 0) {
    "Exiting due to ReportGenerator process having returned an error, exit code: " + $reportGeneratorProcess.ExitCode
    exit $reportGeneratorProcess.ExitCode
} else {
    "Finished running ReportGenerator"
}
"Finished running unit tests and code coverage"

Attention: Line 33 is currently necessary due to a renaming of the mscrolib.dll in .Net Core

This script does call the OpenCover tool to consecutively run all test projects and aggregates the results. Then, they are converted into the Cobertura format (so that Jenkins can pick them up). Finally, the ReportGenerator tool is called to create an additional visualization of the coverage analysis.

Since the resulting files are being stored in the workspace, you need to either configure the job to clean before each build or add another step to delete all earlier results from previous runs. Otherwise, you might run into trouble with duplicated result data.

Evaluate Results in Jenkins

The following three images show the necessary post build steps to publish the results in Jenkins. The file patterns are actually from the generated files in the PowerShell script above, so if you're modifying the script to use other filenames don't forget to adjust your post build actions!

View the Results in Jenkins

Now when you run the job, you'll have the following graphs available in your jobs main page:

There's also an entry called Code Coverage Source Visualization on your left menu in the job overview where you'll see visualized code coverage analysis for your project.

Update 25.09.2016: Added info about how to resolve zero code coverage reports due to rename of mscorlib.dll

Update 31.05.2017: Added link to Linux tutorial

Update 19.08.2017: Added link to updated edition for the current csproj format

Configure Git Hooks on Bonobo Git Server in Windows

Thu, 12 May 2016 21:02:55 Z

This guide will show you how to configure a post receive hook on a Bonobo Git Server that notifies a Jenkins CI server about repository changes. This means that whenever a new commit is pushed to the Git repository, the cURL command line tool will be launched to initiate a Http request telling Jenkins to trigger a job. Bonobo Git Server is a really nice way of setting up private, remote repositories. You can get it at the project site.

Making cUrl Available to the Git Server

cUrl is a nice little command line utility that does all things Http for you.
In order to have cURL available on your server, you need to perform the following steps:

Download cURL and extract the executable and the ca-bundle.crt certificate store to a folder of your choice, e.g. C:\cURL\ (1)
Add the folder you have chosen to the Windows Path environment variable. To do this, open the Windows Explorer, right click on This Computer (2), select Properties and then select Advanced Settings (3). Now click on Environment Variables (4). In the following dialog, find the system variable called Path (5), select it and click on edit. Add the path to the folder containing cURL at the end of the variable (6). Remember to separate it from the previous entry with a semicolon.

Setting Up the Git Hook to Notify Jenkins

Navigate to the repository in Windows Explorer (by default, it’s relative to the IIS Website path in ~\App_Data\Repositories\<RepositoryName>)
Go to the hooks subdirectory and create an empty file with the name post-receive (yes, no extension!)
Open the file with a text editor and paste the following content:

#!/bin/sh
echo Notifying Jenkins Server
curl https://<YourJenkinsServer>/git/notifyCommit?url=<YourGitRepositoryUrl>

This script will be automatically executed whenever you make a push to the server, and the three lines mean the following:
The first line tells Git what type of script the file contains (/bin/sh here meaning a regular shell script)
The second line echos a message to indicate that it’s doing work (you can view the whole console output also in your Git response)
On the third line, curl is executed to perform a Http GET request to <YourJenkinsServer> that passes the Url of <YourGitRepoUrl> as query parameter, so Jenkins knows which Repository it should check for updates.

Jenkins is always listening on that endpoint. If a request hits, Jenkins will start all jobs that are configured for this Git repository.

Basic Jenkins Configuration for .Net Continuous Integration

Thu, 12 May 2016 20:22:13 Z

This article will cover how to do a basic setup for .Net projects using MSBuild, MSTest and Git in a Jenkins Continuous Integration server. It doesn't cover the Jenkins installation, so I'll assume you've got a working installation ready. Otherwise, you can read this post about how to install Jenkins on a Windows Server.

If you follow this tutorial, you'll see how to create automatic tests and builds, triggered after committing code to a Git repository.

Windows Setup

Before turning your attention to Jenkins, you need to set up some prerequisites on your server. Some tools and settings are required for a great DevOps environment.

Reminder: When you configure system settings such as Windows’ PATH variable or creating tool installations, make sure that the user account under which your Jenkins installation is running has access to them.

Install Git on the server
Jenkins will rely on an external Git installation, so just download the latest release at the official site and install it on the server. If you’re using a self-signed certificate, make sure to follow the steps to add the certificate to Gits trusted certificates as described in another post.
Agents for Microsoft Visual Studio 2015 (If you don’t have Visual Studio installed)
Go to the official download site and download the Agents for Microsoft Visual Studio 2015. That’s a package intended for running MSTest without having Visual Studio installed. It’s got that typical Visual Studio installer with that it's extra-long install duration, so better download and start the install right now before you reach the point in this tutorial where it’s required 😉
Microsoft Build Tools
Go to the download section at VisualStudio.com and navigate to the downloads section. Under Tools for Visual Studio 2015, you’ll find a download for Microsoft Build Tools that you need to grab. The picture below shows the correct download.

Update 2017-11-06: I'd actually recommend now to go for Visual Studio 2017. You can get it at the official download site and if you select the workloads you need, you'll get all the required SDKs without having to worry about each single one.

Tip: If you’re having a lot of different target frameworks, you might actually be better off to go along with Visual Studio Community Edition instead of the separate Build Tools & Agents. It’s more heavy on the install side, but it comes with all different .Net SDKs and features installed that you’ll need (except the Dotnet CLI environment, but that’s in another post).

NuGet
You'll be fine by getting the latest executable from the NuGet documentation and place it in a directory that's accessible to your Jenkins service.

Git Windows Style Line Ending Setting

You’re probably familiar with the issue of different operating systems using different defaults for representing line endings, such as \r\n in Windows or just \n in Linux. Since Git is not a native Windows tool, it defaults to the behavior of normalizing line endings to \n when checking out code.

However, imagine a case where you’re performing some integration testing of a library that creates text and uses C#’s Environment.NewLine as line endings. In Windows, this will result in a \r\n newline. Now when you compare text created in your tool in an integration test, you might run into issues where Expected Line #1\nExpected Line #2 is different to Expected Line #1\nExpected Line #2. You can handle this in your tests by ignoring line endings, but you can also easily reconfigure Git to use standard Windows line endings. I prefer the latter since I’m in a pure Windows environment and don’t need to deal with cross-OS normalization.

Logged in as the user under which Jenkins runs, issue the following command in Git to ensure that on checking out, Windows line endings are used:

Git config --global core.autocrlf true

Required Plugins

To make Jenkins work with Git and the .Net stack, we need to add a few plugins in the Manage Jenkins -> Manage Plugins section:

Git Plugin
Provides support for Git repositories
MSBuild Plugin
We need that to build our .Net projects
VSTest Runner plugin
This will use vstest.console.exe to run unit tests. That’s the unit test execution engine Visual Studio uses. You’ll want this since I’ve encountered issues with MSTest, for example the ExpectedException attribute does not work with the MSTest that’s currently included in the Agents for Visual Studio and there might be more issues. It might work for you, but if you’re relying on MSTest then better take the VSTest Runner
MSTest plugin
To convert MSTest results to the JUnit Xml format

Install these plugins and restart Jenkins.

Plugin Configuration

Git Server Credentials

You have to create a login on your Git server so that Jenkins can access the repositories. When you have created a user with access rights to the repository, go back to Jenkins, navigate to Manage Jenkins -> Manage Credentials -> Add Credentials and then select Username with password in the combobox.
Enter the credentials you have created on the Git server here so that we can use whenever Jenkins needs to access the Git server.

If you haven’t done it yet, create a new Git repository containing a simple C# (or VB.Net or...) class library and a MSTest unit test project.

MSBuild Configuration

MSBuild should already be present on your system. If it is not, you can manually download the .Net framework or use the server manager to add the ASP.Net features to your IIS installation and have the framework automatically come along. The folder shown is the standard location of MSBuild (for the currently latest .Net version). This configuration section is again found in Manage Jenkins -> Global Tool Configuration.

VSTest Configuration

This is similar to setting up MSBuild. You’ll need to point the path to the Visual Studio directory that contains the vstest.console.exe (it’s also installed with the Agents for Microsoft Visual Studio 2015). I named it by the Visual Studio version.

Create your first job

In Jenkins, go to the main menu and click New Item in the upper left corner. Give the job a name and select Freestyle Project, then click OK.

Now you are in the job configuration page. Here, go to the Source Code Management section and tell Jenkins to use Git and specify the Url of the repository. Select the login credentials that you’ve configured earlier for the Git server. Also click on Add Additional Behaviours and select Clean before checkout, otherwise the results from previous builds will not be cleaned up and you get more and more test results with every build=)

In Build Triggers, just select Poll SCM without entering a schedule. It’ll warn you that it will never run, but that’s wrong, it will run whenever you push to the Git server. It’s important to leave Ignore post-commit hooks unchecked!

Now we configure two build steps. The first will make the build using MSBuild. It’s pretty straightforward, we’re just referencing the *.sln file via its relative path in the repository (It’s in the root folder for this sample project).

Another build step is configured to execute VSTest. The steps are done consecutively, so it’ll wait until the build step is done to execute the tests. Two parameters are specified: The dll containing the unit tests and the name of the file in which to store the unit test results. Note that you could enter multiple unit test dlls here if necessary. You can leave the advanced settings as they are.

Tip: If you’re having any NuGet packages referenced in your project, you’ll most likely do not have them in source control (which is good!). Then you need to restore them before you can build the project. Hence, add the following build step as FIRST step to your build actions (and set the paths according to your local config):

After the build we tell Jenkins to do two things: Read that *.trx MSTest results file from the VSTest Runner and convert it to a JUnit output (this allows Jenkins to display the unit test results) and additionally we’ll set up an email notification for when things go wrong.

Now click Save and you’re in the detail view of your created Job. Click on Build Now on the left to start your first build! In a few moments, the Build History will show you the job. You can hover over the date entry and expand the sub menu. Now select Console Output to see what’s going on.

If everything went right, the last line in the console output should say:

Finished: SUCCESS

Tip: If the test failed, the console output should provide you with information on what went wrong.

Testing the Git hook

If you've already setup a remote Git repository and configured a Git hook to notify Jenkins on updates (here's a post describing how to do that with a self hosted Bonobo Git Server), now would be the time to trigger an automatic build.

When you look at Jenkins after having done a commit on your remote Git repository, Build History should now have a second entry.

Break the Build

This rarely ever happens in real life, but legend has it that builds break. Let’s add some faulty code and make the compiler unable to build the project. Then commit. Refresh the page...

… and face disaster!

Luckily, you've also been alerted by email of the failing build. You can go to the build and view the console output (that’s also what’s been sent to you by email). It’ll show you a log that will list some compiler errors near the bottom.

Let’s fix that and make another commit. You’ll get another email telling you that the build is back to normal.

To summarize, whenever there is a change that makes a build fail, you’ll be notified by email. As soon as the build starts working again, you’ll get another email. Quite simple yet so convenient!

Set Up Private NuGet Feeds with ProGet and Jenkins

Sat, 30 Apr 2016 22:59:23 Z

This posts goal is to have a continuous integration server (Jenkins) pull a MSBuild project from a remote repository, build it and upload it to a private NuGet server. The NuGet feeds is hosted via ProGet with an authorization mechanism to restrict user access. Since I’m only using the free version of ProGet, this tutorial won’t cover setting up different feeds for different users.

Install & Configure ProGet

There’s a free edition of ProGet available that can host private NuGet (and more) feeds. Installation and initial configuration is nicely covered by their documentation, so I won’t go into much detail here. There was just one bit missing in the documentation that caused some troubles for me: When you’re using MS SQL Server, it’s possible that your default collation is different to the one ProGet will try to set during the database initialization, so make sure to create the ProGet database with SQL_Latin1_General_CP1_CI_AS collation and you’ll not run into issues, otherwise ProGet might fail to apply its database schema during installation.

To keep your feeds private, go into the settings page of ProGet -> Assign Privileges and remove the one that grants anonymous users View Only rights.

Set Up a Private Feed on the Server

In ProGets configuration section, go to Manage Feeds -> Create Feed -> NuGet and assign a name for that feed. The only thing you’ll want to set here is the NuGet API Key, since we’re going to push it via a Jenkins Job and we don’t want to have to include user credentials in a build job in plain text. Leave the symbols server option turned on.

Now if you go back to the feed overview, your feed will be listed along the default feed with its Url.

Admittedly, in the free edition, creating a feed isn’t really necessary at all since there’s no ways to customize access based on feeds. It’s all or nothing in the free edition.

Enable NuGet Package Upload with an ApiKey

Later, you’ll want to use the ApiKey to simplify uploading packages via the command line. For this, you have to create a new role with the task Feeds_AddPackage in the Manage Roles section:

Then, assign that role to the Anonymous user in the Manage Priviliges section:

Now, to upload a package, only the ApiKey is required (when one is configured for the feed).

Configure your Project for NuGet Packaging

Creating a NuGet feed is really easy. At first, you must find out where your NuGet.exe is located or simple download the latest executable from https://www.nuget.org. Then, in your project dir, run the nuget.exe spec command. A *.nuspec file is created with the same name as your *.csproj file with this default content:

<?xml version="1.0"?>
<package >
  <metadata>
    <id>$id$</id>
    <version>$version$</version>
    <title>$title$</title>
    <authors>$author$</authors>
    <owners>$author$</owners>
    <licenseUrl>http://LICENSE_URL_HERE_OR_DELETE_THIS_LINE</licenseUrl>
    <projectUrl>http://PROJECT_URL_HERE_OR_DELETE_THIS_LINE</projectUrl>
    <iconUrl>http://ICON_URL_HERE_OR_DELETE_THIS_LINE</iconUrl>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <description>$description$</description>
    <releaseNotes>Summary of changes made in this release of the package.</releaseNotes>
    <copyright>Copyright 2016</copyright>
    <tags>Tag1 Tag2</tags>
  </metadata>
</package>

All the fields enclosed in $ tags will be automatically populated when you create the package, but you can change them to hard coded values or have your CI system populate them. Just make sure that when you have the placeholder in the file, your Assembly must have the attribute. For example, if in your Project Settings in Visual Studio there is no Description for the assembly, then packaging will fail due to the $description$ tag missing content.

You can do a test run to create a package via nugget.exe pack <PathToYourCsprojFile> -Prop Configuration=Release -Symbols

This will generate a *.nupkg and a *.symbols.nupkg file. The symbols file does contain your *.pdb files.

Next, before you can deploy you need to set the NuGet ApiKey for your ProGet server via this command nuget setapikey <YourApiKey> -source <UrlOfYourFeed>

This will locally (for the current user, so execute the command also with the user that is configured for your Jenkins service) store the ApiKey for that specific feed for pushing packages.

Now pushing the package is really easy with nuget push <PathToYourPackage> -source <PathToYourFeed>

If you do want to include symbols, then upload the *.symbols.nupkg instead of the *.nupkg one. ProGet does not have different endpoints for symbol- and regular packages, it will only accept a single package per project and version and, if this is a symbol package, additionally offer the *.pdb files in its symbol feed while stripping them from the regular feed.

If everything went smooth, your Package is now available on your private NuGet server.

Accessing the Feeds

Since the feeds are now private and protected, it would be advisable to create a user with the View_Only role for accessing the feeds in ProGet.

Once that’s done, you need, on every machine and for every user account that will access the feed, run the following command:

nuget source add -Name <NameOfTheStoredCredentials> -Source <YourNuGetFeedUrl> -User <Username> -Pass <Password>

By default, this will store it in a config file in the current users AppData directory and will be automatically retrieved for this source. The package source will then also be made known for all package restores on your account through NuGet, so you don’t have to specify your custom NuGet feed in Visual Studio. In fact, Visual Studio will be aware of your package source after you’ve entered this command. To search for packages there, set this as your package source in the upper right corner of your NuGet package manager view in Visual Studio. Please note that you can overwrite global feed sources via a project specific NuGet.config file.

Try it out with nuget list -source <YourNuGetFeedUrl>. If it works, you've got time to fetch a coffee while it lists all the feeds (it also relays the official NuGet feed). You could also press Ctrl + C in the cmd window to abort=)

Setting the credentials is an easy way for integrating the private feed in your CI system as well as your IDE, since all you have to do is specify an Url and don’t have to wiggle with the credentials yourself.

Automate NuGet Package Deployment with Jenkins

In Jenkins, you want two build actions:

First, build the project in release mode with the MSBuild plugin (NuGet should do that automatically, but I had issue with NuGet not being able to find the correct MSBuild version)

Then in the second step, you need the following PowerShell script (if you haven’t already, you should install the Jenkins PowerShell plugin):

$workspacePath = $ENV:WORKSPACE
$projectName = "Your.Namespace" # Name of the project. Omit ".csproj", this will be added automatically
$pathToNuGet = "C:\BuildTools\NuGet\nuget.exe"
$configuration = "Release" # The configuration you want to publish
$nuGetFeedTarget = "<YourNuGetFeed>"
# Find the project file
$pathToCsproj = Get-ChildItem $workspacePath -Recurse -Filter ($projectName + ".csproj")
# Create the NuGet package
"Creating the NuGet package"
$nuGetPackArguments = @(("pack"),`
                        ("""" + $pathToCsproj.FullName + """"),`
                        ("-Prop Configuration=" + $configuration),`
                        ("-Symbols"))
                        $nuGetPackArguments
$nuGetPackProcess = Start-Process -FilePath $pathToNuGet -ArgumentList $nuGetPackArguments -Wait -PassThru -NoNewWindow
if ($nuGetPackProcess.ExitCode -ne 0) {
    "Error during NuGet package creation, exiting"
    exit $nuGetPackProcess.ExitCode
} else {
    "Finished NuGet package creation"
}
# Find the package
$pathToPackage = Get-ChildItem $workspacePath -Recurse -Filter ($projectName + "*.symbols.nupkg")
# Upload the package
$nuGetPublishArguments = @(("push"),`
                            ("-NonInteractive"),`
                            ("""" + $pathToPackage.FullName + """"),`
                            ("-source " + $nuGetFeedTarget))
$nuGetPublishProcess =  Start-Process -FilePath $pathToNuGet -ArgumentList $nuGetPublishArguments -Wait -PassThru -NoNewWindow
if ($nuGetPublishProcess.ExitCode -ne 0) {
    "Error during NuGet package publishing, exiting"
    exit $nuGetPublishProcess.ExitCode
}
"Finished package publishing"

Set the five variables at the top according to your project setup and then start a Jenkins build. When everything’s configured correctly, you should see something like this in the ProGet web view of your feed:

And in Visual Studio:

Now you’ve just drastically simplified using your own shared libraries!

Oh, and on a side note: You should take into consideration when you perform that Jenkins job. It might be worthwhile to leave it as manual so you don’t get a new NuGet package version with every single commit you do.