CSharp Build Instructions

From Direct Project
Jump to: navigation, search

Command Line Build

Software requirements for building without Visual Studio 2008 Pro

The .NET reference implementation is written mostly in C#, with the exception of two VC++ projects. For building the C++ projects, Visual Studio 2008 Pro is required, however, the code is structured in such a way, that a full build is possible with just building the C# code. The following instructions explain how to do that.
Windows 7 SDK with .NET 3.5 SP1

Download installer

These are the basic build tools necessary, including MSBuild and the compilers
Visual Studio 2008 Shell Integrated Mode Redistributable Package

Download package

Installs Microsoft.WebApplication.targets, required for Admin UI
Web Platform Installer (WPI)

Download WPI

Installs ASP.NET MVC2, required for Admin UI

Installation steps

Obtaining the Microsoft.WebApplication.targets file requires the following steps:
  1. Run the installer for the Visual Studio 2008 Shell Integrated Mode Redistributable Package. It will just unpack another installer in (for example) C:\VS 2008 Shell Redist\Integrated Mode
  2. Run the vside.enu executable:
  3. If you are running a 64-bit Windows OS, you need to copy the Visual Studio additions for MSBuild from C:\Program Files (x86)\MSBuild\Microsoft to C:\Program Files\MSBuild\Microsoft:

Installing ASP.NET MVC 2:

  1. Run the Web Platform Installer (WPI) and search for MVC:
  2. Click "Add", and then "Install"

Building the Reference Implementation

Once you have obtained the source code, you can build the RI using MSBuild (which comes with the Windows 7 SDK with .NET 3.5 SP1). The SDK also comes with a fully configured command prompt:

Right-click, and run it as administrator:

Go to the nhin-d\csharp directory and run msb.bat - note that setenv.bat is not necessary in this case:

More details on using msb.bat and MSBuild are available below.

Building with Visual Studio 2008 Pro

Install a copy of Visual Studio 2008 Pro, and make sure SP1 is also installed. This will include .NET 3.5 SP1, and MSBuild.

Setting up a Build Console

The command line build uses msbuild.exe. msbuild.exe is a command line application found in C:\Windows\Microsoft.NET\Framework\v3.5 or C:\Windows\Microsoft.NET\Framework64\v3.5 (if you use the 64 bit version). The appropriate directory must be on your PATH environment variable.

If you do not wish to set this up permanently, you can run the setenv.bat file located in the csharp directory.

You can create a command line console to run setenv.bat automatically.
  • Create a new shortcut on your desktop.
  • Name it "Mercurial"
  • Right Click, select properties, and set the Target to C:\Windows\System32\cmd.exe /k C:\hg\nhin-d\csharp\setenv.bat
    • You may need to customize the path in bold.


We building using msb.bat.
  • msb.bat is a useful wrapper around msbuild.exe.
    • It removes the annoying need of having to type a "-target" arg everytime you do anything with msbuild.
  • csharp\msb.bat

Full build

You do a full build of the C# code off the source root.
cd csharp msb

Building Individual Components

  • Msbuild.exe works with targets
  • Targets are defined in csharp\build.xml

Some well known targets:

build or build-all
Builds all of the C# solutions - this is the default target.
Build both the C++ and C# solutions - requires VS 2008 Pro
Builds the agent (build\agent.sln)
Builds the gateway (build\gateway.sln)
clean or clean-all
Cleans up all of the build artifacts
Cleans the build artifacts for the agent
Cleans the build artifacts for the gateway (currently disabled)
test or test-all
Runs all of the tests

By default, msb.bat invokes the build-all target .

Running Unit Tests

Section Being Rewritten

Unit Tests are writting using XUnit, and can be run using one of the 3 variations listed below.

Three limitations:

  1. One of the tests creates an X509Store, and must be run as Administrator. If you do not have sufficient privileges, that test will fail.
  2. Some tests execute DNS lookups against public DNS servers over TCP on Port 53.
    • Many internal corporate (or personal) firewalls block TCP port 53 by default. If so, some Dns resolution and Dns Caching tests may fail.
    • We now have our own Dns server and will migrate these to using a local Dns
  3. The source tree must not be on a networked drive

You can run unit tests using one of the following mechanisms:

Using msb.bat

Build.xml contains targets for each individual unit test.
Dll Path
test-agent test-gateway





cd csharp
msb test


Optionally, you can build tests using the xUnit command line runner. Dependencies:

From the command line without msbuild the tests can be directly run like so:

xunit.console.exe unittests\agent\bin\Debug\Health.Direct.SmtpAgent.Tests.dll

And finally, for the visually delighted:

xunit.gui.exe unittests\agent\bin\Debug\Health.Direct.SmtpAgent.Tests.dll

Optional building agent.sln and gateway.sln + tests.

First time you'll need to perform a few extra steps:

  • Go to the Start Menu\Programs\Microsoft Visual Studio 2008\Visual Studio Tools
  • Click on Visual Studio 2008 Command Prompt (this just makes sure your environment has the necessary paths)
  • CD csharp\gateway\sdk
  • Then run the gen.bat script.
  • This should produce something similar to the following text:

Microsoft (R) 32b/64b MIDL Compiler Version 7.00.0555
Copyright (c) Microsoft Corporation. All rights reserved.
Processing C:\Program Files\Microsoft SDKs\Windows\v6.0A\Include\msado15.idl msado15.idl

At this point you can return back to the csharp directory:

cd ..\..
msbuild build.xml -t:build-gateway

This builds core components as well as unit tests and places them in the bin.

Directory Structure

The C# reference implementation is wholly contained in the csharp directory.

The directory structure is as follows:

-/bin # build bits -- see below
-/build # master solution files
-/external # External DLLs
-/samples # Example files
-/tools # tools and utilities


All binaries and unit tests are compiled into a common bin:
nhin-d\csharp\bin\debug | release

Your .csproj files should be configured (using relative paths) to deposit bits into the above folders.

Note that the project file editor in VC# (at least, the Express version) does not allow the debug path to be changed in the UI, so you must edit the value in the project file using a text or XML editor.

For normal components, which have project files in a subdirectory of the main csharp directory, the debug build path will be:


For unittest components, which have project files in a subdirectory of csharp/unittests, the debug build path will be: