SADev

Why I like Visual Studio 2010? Undock Windows

Robert MacLean — Wed, 28 Jul 2010 01:43:52 PDT

Visual Studio 2010 has the ability to undock code windows by clicking and dragging on the code window tabs. This is a great feature and it is often touted for multi-monitor setups where you may want to have the form on one window and code on another window, or maybe two different code files open at the same time.

That is very useful, however that is not why I like this feature. I like the ability to undock the windows because it lets me view two different parts of the same file at the same time. Visual Studio 2010 and earlier have supported this using the split view option () but that means you lose half of your screen (like below).

Using the undock windows in 2010 you can use the Windows –> New Window option to duplicate the current window.

Then you can drag the second (or third, or forth) windows out and get a full screen side by side view which is GREAT for comparing code.

Cannot open VS project if Blend is used?

Robert MacLean — Tue, 27 Jul 2010 03:38:28 PDT

I ran into an issue recently after reinstalling my laptop, where I couldn’t open a C# (WPF) project in Visual Studio 2010. Every time I tried it just grimaced at me and said:

Unable to read the project file 'Rule18.csproj'.

E:\Projects\Rule18\Rule18\Rule18.csproj(335,3): The imported project "C:\Program Files (x86)\MSBuild\Microsoft\Expression\Blend\3.1\WPF\Microsoft.Expression.Blend.WPF.targets" was not found. Confirm that the path in the <Import> declaration is correct, and that the file exists on disk.

Part of the cause is that previously I had Blend installed, and I had used it on this project to do some fairly complex things, in particular Font Embedding. However since reinstalling I had not installed Blend again.

This is caused the build target file not to be installed, and that caused the error.

How do you get around this?

The best solution is to install the FREE Blend SDK because that will put the build targets on the machine. Links for the SDKs:

Blend 4 .NET SDK: http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=75e13d71-7c53-4382-9592-6c07c6a00207
Blend 4 Silverlight SDK: http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=d197f51a-de07-4edf-9cba-1f1b4a22110d

However I didn’t have time to do this, so as a temporary solution (and definitely not a recommended solution): I opened the project file, and right near the bottom I found the Import for CSharp and Blend. I removed the Blend one, saved and reloaded and worked.

VirtualBox UUID already in use

Robert MacLean — Mon, 26 Jul 2010 02:58:40 PDT

I am playing around with using VirtualBox to run virtual machines and I ran into an issue trying to use a clone (copy) of a VDI file. The VDI file is the hard disk drive and it has a unique identifier in it it (UUID) and so trying to use a clone of one gives you the error: UUID of the hard disk is already exist in the media registry.

To solve it you need to run the following command to change the UUID of the file:

VBoxManage.exe internal commands sethduuid [VDI file]

Example:

"c:\Program Files\Oracle\VirtualBox\VBoxManage.exe" internal commands sethduuid

AppFabric.vdi

Announcing new sponsor for Visual Studio and TFS hands on lab event: Devexpress

Robert MacLean — Fri, 23 Jul 2010 00:50:14 PDT

I’m sure you know that in a week 50 talented and interested people will be getting together for a day of FREE hands on labs focused on Visual Studio 2010 and TFS 2010! If you didn’t know, have a look here.

Today I am very proud to announce we have another sponsor for the event – Devexpress! Devexpress are makers of some FANTASTIC addon’s for Visual Studio and development.

So what are they sponsoring? TWO licenses for their Visual Studio productivity add-on: CodeRush!

These two licenses will be given away as prizes to two lucky people at the event (you must be there to win).

ALM in 2010

Robert MacLean — Wed, 21 Jul 2010 23:35:29 PDT

Here is the slides from my talk on Application Lifecycle Management in 2010 which I did for the Information Worker user group.

Here is the blurb for the session

Development is not just about writing code and pressing compile. It is a process, which starts long before code is written and extends long after the compile is done and this process includes a lot of management - this process is called Application Lifecycle Management (ALM).

SharePoint development is not immune to this and this presentation looks at what the landscape and tools are like for ALM in 2010 and how it relates to SharePoint development.

You can download the slides and the white paper from the IW site.

HTTP Status Codes Cheat Sheet

Robert MacLean — Wed, 14 Jul 2010 10:22:01 PDT

Today’s poster is for the variety of HTTP status codes which exist. Not only is there the 34 original HTTP v1.0 ones and the 6 new ones that came in with 1.1. There is also another 10 extensions from official RFC’s, and two special case ones. That is 52 in total, and it isn’t easy to remember what they are all are – so this poster is a cheat sheet to help with that.

It is also related to my other REST cheat sheet, since good HTTP status code usage is important for good REST services.

You can download the high resolution XPS file below.

Attachment	Size
RestCheatSheet2.xps	2.38 MB

"How RESTful are your services?" - The quick reference poster

Robert MacLean — Tue, 13 Jul 2010 10:39:03 PDT

Today’s quick reference poster looks at REST services and gives a guide to how RESTful (or not) your services are, from level 0 (not restful) to level 4 (using everything). These are not a scientific levels, it is just a simple classification I devised to promote easy communication about the services. The idea for this is to promote thinking about what features to use and assist with communication in a team. It is not a a requirement to always have level 4, some times you just need level 1 and this fine – do not over engineer for the sake of saying you are level 99.

If you are in into classification of REST services, have a look at http://www.innoq.com/blog/st/2010/07/rest_litmus_test_for_web_frame.html

Download the high resolution XPS file below.

Attachment	Size
RestfulCheatsheet1.xps	1.6 MB

Proven Practices in Threading Quick Reference Poster

Robert MacLean — Mon, 12 Jul 2010 00:45:38 PDT

This poster is based off my talk on .NET Threading, which I wrote about the entire process about the creation of that talk (see here). This poster takes the key proven practices in the talk and groups them into six themes for easy consumption.

High resolution XPS version below.

Attachment	Size
Threading Cheat Sheet.xps	824.48 KB

Free Visual Studio 2010 and TFS 2010 training!

Robert MacLean — Thu, 08 Jul 2010 23:58:43 PDT

Update 13 July 2010: The event is fully booked now! If you want to add yourself to the waiting list in case a spot becomes free, please contact me.

I am very excited to announce that Zayd Kara, fellow Visual Studio ALM MVP, and myself have arranged a free hands on labs training for Visual Studio 2010 and TFS 2010. This is your opportunity to get some time learning about the new features in these products.

The event will take place on Saturday, 31st July 2010 and will run from 9am to 1:30pm and is completely free, but it is limited to 50 people!

You will be able to do the following labs:

Authoring and Running Manual Tests using Microsoft Test Manager 2010
Branching and Merging Visualization with Team Foundation Server 2010
Code Discovery using the Architecture Tools in Visual Studio 2010 Ultimate
Debugging with IntelliTrace using Visual Studio 2010 Ultimate
Introduction to Coded UI Tests with Visual Studio 2010 Ultimate
Introduction to Test Case Management with Microsoft Test Manager 2010
Planning your Projects with Team Foundation Server 2010
Understanding Class Coupling with Visual Studio 2010 Ultimate
Using the Architecture Explorer in Visual Studio 2010 Ultimate to Analyze Your Code

Click here for more details and registration form.

I would also like to take this opportunity to thank our sponsors for making this possible:

What's new in Visual Studio 2010 quick reference poster

Robert MacLean — Thu, 08 Jul 2010 23:52:14 PDT

One of my favourite aspects of my work at BB&D, is the creation of quick reference posters and cheat sheets for the DRP site which is one of BB&D’s way of sharing knowledge outside the organisation. I have recently produced a bunch of new posters which I will be releasing over the next few days. First up is…

What’s new in Visual Studio 2010

A quick reference post which explains the edition changes, some new features (IntelliTrace and the architecture tools) and gives some hints about the IDE (docking of windows, search shortcuts, block selection and zooming).

You can download the high definition XPS file below.

Attachment	Size
VS 2010 Cheat Sheet.xps	665.35 KB

Presentation Dump - Mid 2010: VS2010, NDepend, RESTful Design, SSIS, EntLib 5, .NET Reflection, AppFabric, BDD, Sikuli & Redmine

Robert MacLean — Thu, 08 Jul 2010 03:12:06 PDT

The past 6 months have been hectic from a presentation perspective for me, with 20 presentations and classes given this year so far. So instead of a single dump of presentations at the end of the year, as I did last year, I am doing a mid-year dump.

What is new in Visual Studio 2010

This presentation is the one I have given many times this year. It originally started as 10 on 10, which looked at 10 features in 20min for Dev4Dev’s last year. It then evolved into 12 on 10, which added two more features, still in 20min. It then evolved into ?? on 10 for 6 degrees of code where it became an hour and half presentation. It is demo heavy and really the slides are the very basics – the important is hidden slides and notes for the demos.

NDepend

The tool that keeps on giving! For people working with taking over customer sites, reviewing code or anything else where you need to deal with other peoples code this tool is a must. This presentation was given to the architecture team at BB&D.

RESTful Design

RESTful design is an evolution of an earlier presentation I did, REST & JSON, which drops the JSON stuff completely and also drops the heavy compare with SOAP/WS* parts which seemed to cause confusion. This revised presentation covers just REST and looks at it much more practically by covering the required HTTP knowledge and patterns for designing RESTful services.

SQL Server Integration Services

Another upgrade in 2010 of an earlier presentation which not only cleans up some aspects but also goes into a lot more detail.

Enterprise Library

“The presentation that never was”, often I will spend time researching a technology or trend and preparing the presentation to come to the conclusion that it is just not worth the time of the attendee’s. Enterprise Library 5 is one of those, as the presentation covered what is new in it, and that is not very much.

.NET Reflection

This one is actually one from last year, but I had problems getting it onto SlideShare so it is only showing up now.

Windows Server AppFabric

AppFabric, the local one – not the Azure one, was a great presentation I did for the BB&D architecture team. This is not the original presentation – it has been edited to remove customer info as a lot of analogies between a project BB&D did and AppFabric was in it (cause who hasn’t built a system similar to AppFabric).

BDD

One of the presentations I spent the most time on this year, and one of the most exciting presentations. It really is a great methodology and I would love to see it used more.

Sikuli

Another presentation which did not make the cut to actually be presented. It is an interesting project, but of limited scope and when compared to the Coded UI from Visual Studio 2010 it is really far behind.

Redmine

Redmine is a bug tracking system, and being it’s not TFS may surprise you that an ALM MVP would do training on it. However for me to do training meant I head to learn it, which means I know the ALM landscape better and can point out which is better or not without uneducated bias (btw it still is TFS :)). This training was aimed not at developers but at call centre/power user people who would log initial bugs to then be managed in the system – so it was more of a ticketing system than a bug system in the end.

TFS Integration Platform: Why the custom adapter format?

Robert MacLean — Tue, 06 Jul 2010 23:31:26 PDT

Note: This is my personal opinion and not a view of Microsoft.

The TFS Integration Platform includes the ability to create and use custom adapters, however these are done using a custom adapter format. A question asked by many people, including myself, is why a custom adapter format?

Microsoft has a few solutions in the adapter space already which could’ve been used:

SSIS: SQL Server Integration Services, Microsoft’s platform for ETL has the ability to build adapters which can read and/or write.
WCF LOB Adapters: Microsoft has a very complete framework for building LOB adapters which can be used by custom code or products like BizTalk.
BizTalk adapters: Native adapters for Microsoft BizTalk server.

So why reinvent the wheel? There are three compelling reasons I see for it:

Lightsaber vs. Gun

A weapon from a more civilised age, the lightsaber is a weapon with a number of purposes:

Deflecting laser shots
Melting doors
Cutting off snow monster arms
Slicing open the belly of a tauntaun.

and it does all those well.

A gun is completely different, it is a single minded point and click interface for killing and sometimes it is better to just get the job done as Indiana shows us:

The other adapter templates are like lightsabers in that they are designed to deal with a variety of situations and so flexibility is key. They have the concept of data in/data out and do not care about the data is. The TFS Integration Platform adapters are like a gun, they are built precisely for a single purpose and so do that exceptionally well.

The Scotty Factor

Star Trek is about a group which has research and discovery vessels flying round space and dealing with what is encountered. The ships in Star Trek are not designed for warfare¹, but they do a lot of fighting. Why is it then that these peaceful ships can fight, because it is a reality of the situations they encounter, that they will need to be able to defend themselves.

Knowing ahead the common scenarios that can arise, means that you can prepare better and the TFS Integration Platform is an indication of that. There is a lot of knowledge of work items and version control built into the platform, even some assumptions which are not true for all systems, and that means as a developer you write less code in your adapter to get it to work and it also means the platform is optimised for the job at hand.

All you need is a paper clip, a rubber band and a sugar cube

A paper clip is meant to hold multiple pieces of paper together – that is it’s job. Introduce McGuyver and the edge case usage of a paper clip being able to control low orbiting satellites comes into play, however he will need a few other things to hack it together. When you work with a generic migration/integration system, those edge cases are very difficult to cater for. The TFS Integration Platform handles edge cases related to the task at hand very well because they aren’t edge cases – they are normal expected cases.

There is one ship purpose built for fighting, the Defiant.

What Office taught me about Visual Studio? A very cool toolbox trick.

Robert MacLean — Mon, 14 Jun 2010 01:52:55 PDT

I spend a significant amount of time in PowerPoint and to get a constant look and feel in my slides, I often use the Format Painter option. Using this tool you highlight some text/image/video, click the Format Painter button and then paint some other text/image/video and it applies the format settings from the first group to the group you paint.

What if you want to do this over and over? You may think you need to highlight → click → paint over and over again, but Office has a trick – double click the button! Then you can highlight → double click → paint → paint → paint

So how does this help in Visual Studio? I am working with the UML diagrams at the moment and needed to connect a bunch of items and the first few times I did the following: Click the connector in the toolbox → click source item → click destination, repeat from start.

Suddenly I thought, maybe it works like Office and you know what? It does! You can double click a toolbox item, and then it becomes sticky and adding lots of them is easy!

How to create an adapter for the TFS Integration Platform - Appendix 2: SimpleDictionary

Robert MacLean — Thu, 10 Jun 2010 03:34:52 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

For my WI adapter I needed an implementation of Dictionary<T,V> which could be serialised and unfortunately the .NET one can’t. So I threw together a simple implementation of one using two List<T>. It is not perfect for every possible time you may need an alternative to Dictionary<T,V>, for example the only item manipulation I have is to add an item and clear all items, but it is great for my needs in the case:

[XmlRoot("simpleDictionary")]
public class SimpleDictionary<Key, Value> : IEnumerable, IXmlSerializable
{
    private List<Key> keys = new List<Key>();
    private List<Value> values = new List<Value>();

    public List<Key> Keys
    {
        get
        {
            return keys;
        }
    }

    public List<Value> Values
    {
        get
        {
            return values;
        }
    }

    public IEnumerator GetEnumerator()
    {
        return (IEnumerator)new SimpleDictionaryEnumerator(this);
    }

    public void Add(Key key, Value value)
    {
        keys.Add(key);
        values.Add(value);
    }

    public void Add(object o)
    {
        KeyValuePair<Key, Value>? keyValuePair = o as KeyValuePair<Key, Value>?;
        if (keyValuePair != null)
        {
            this.Add(keyValuePair.Value.Key, keyValuePair.Value.Value);
        }
    }

    public void Clear()
    {
        keys.Clear();
        values.Clear();
    }

    #endregion

    private class SimpleDictionaryEnumerator : IEnumerator
    {
        private SimpleDictionary<Key, Value> simpleDictionary;
        private int index = -1;

        public SimpleDictionaryEnumerator(SimpleDictionary<Key, Value> simpleDictionary)
        {
            this.simpleDictionary = simpleDictionary;
        }

        #region IEnumerator Members

        public object Current
        {
            get
            {
                return new KeyValuePair<Key, Value>(simpleDictionary.keys[index], simpleDictionary.values[index]);
            }
        }

        public bool MoveNext()
        {
            index++;
            return !(index >= simpleDictionary.keys.Count);

        }

        public void Reset()
        {
            index = -1;
        }
    }

    public System.Xml.Schema.XmlSchema GetSchema()
    {
        return null;
    }

    public void ReadXml(XmlReader reader)
    {
        if (reader.IsEmptyElement)
        {
            return;
        }

        XmlSerializer keySerialiser = new XmlSerializer(typeof(Key));
        XmlSerializer valueSerialiser = new XmlSerializer(typeof(Value));

        reader.Read();
        while (reader.NodeType != System.Xml.XmlNodeType.EndElement)
        {
            reader.ReadStartElement("keyValuePair");

            reader.ReadStartElement("key");
            Key key = (Key)keySerialiser.Deserialize(reader);
            reader.ReadEndElement();

            reader.ReadStartElement("value");
            Value value = (Value)valueSerialiser.Deserialize(reader);
            reader.ReadEndElement();

            this.Add(key, value);

            reader.ReadEndElement(); // for keyvaluepair
            reader.MoveToContent();
        }

        reader.ReadEndElement(); // for root
    }

    public void WriteXml(XmlWriter writer)
    {
        XmlSerializer keySerialiser = new XmlSerializer(typeof(Key));
        XmlSerializer valueSerialiser = new XmlSerializer(typeof(Value));

        for (int counter = 0; counter < this.keys.Count; counter++)
        {
            writer.WriteStartElement("keyValuePair");

            writer.WriteStartElement("key");
            keySerialiser.Serialize(writer, this.keys[counter]);
            writer.WriteEndElement();

            writer.WriteStartElement("value");
            valueSerialiser.Serialize(writer, this.values[counter]);
            writer.WriteEndElement();

            writer.WriteEndElement();

        }
    }
}

Pro tips for the Visual Studio Pro Power Tools

Robert MacLean — Wed, 09 Jun 2010 05:48:04 PDT

The team has release a new version of the tools which solve a lot of the issues, and provide a bunch more great features. Please make sure you see and use the latest version.

At Tech·Ed North America on Monday the Visual Studio Pro Power Tools were announced, and they are fantastic. A full run down of them can be found on Brian Harry’s blog. However there are some tips in the usage which may not be immediately obvious so this post will explain some additional tips.

Add Reference Dialog

The new dialog is amazing and fits the UI experience of VS2010 way better than the out of the box one. One point to be aware of is that when you hit Add that it does not close the dialog - it does mark the selected assembly and in the background it adds it. This is great for adding multiple assemblies. If you want to remove an assembly you can do it here too – just select an already added assembly (green tick) and the Add button becomes a Remove button.

Document Tab Well

This is one of the first things you will see, because the tabs are a variety of colours suddenly. How can you control this? Go to the Tools menu –> Options –> Environment –> Document Tab Well to customise the settings. Setting the preset to Visual Studio 2010 is the same as disabling it.

As a side point, if you are thinking of disabling it – before you do disable it, try the Dynamic Tab Well preset. It is very similar to the standard VS2010 tabs, but with more features added and should appeal without over killing it.

The shortcut to get to that part of help is right click on any blank space in the tab well and click Customize…

Highlight Current Line

Another one that is immediately obvious – the grey behind your current line of code. If this colour is not aligned to your colour scheme then you can tweak it using the Tools menu –> Options –> Environment –> Fonts & Colours –> Display Items –> Current Line (Extension).

To “disable” it set the background to Automatic.

Align Assignments

If this is not working for you, it could because your C# settings are stopping it. To , you must uncheck: Tools menu –> Options –> Text Editor –> C# –> Formatting –> Spacing –> Ignore spaces in declaration statements

Colourised Parameter Help

Don’t like the the colours of the new tool tips? Want them to match your theme?

You can do this via Tools menu –> Options –> Environment –> Fonts & Colours –> Display Items –> Signature Help Tooltip Background

~~Important to not that the foreground colour cannot be changed, only the background colour.~~

Move Line Up/Down Commands

Did you have something already on the Alt+↑ or Alt+↓ or maybe you want to bind to something else? You can do this in Tool (menu) –> Options –> Environment –> Keyboard. The commands are:

Edit.MoveLineDown
Edit.MoveLineUp

The Hack

Should you really dislike an extension or a specific extension is conflicting (tab well for instance conflicts with another tab management extension available) there is a completely unsupported hack to remove a specific feature while keeping other features on. Note that you will need to do this for EVERY update and it is unsupported, so do not bother to ask for help. It may also cause side effects to Visual Studio which cannot be foreseen. In short you had better be desperate.

Hack #1

The VSIX file is just a ZIP file, which you can open in your favourite archive tool. From there you can see the assemblies for each extension and remove them if needed.

Hack #2

When an extension is installed it is unpacked to C:\Users\<Username>\AppData\Local\Microsoft\VisualStudio\10.0\Extensions\ in here you will find directories for the various authors and under those the extensions. To find the Pro Power Tools go to: \Microsoft\Visual Studio 2010 Pro Power Tools\10.0.100525.1000 and you will see all the files, simply delete or move out the assembly of the feature you do not want that will disable it.

How to create an adapter for the TFS Integration Platform - Appendix 1: Power Tips

Robert MacLean — Wed, 09 Jun 2010 05:38:33 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

Throughout the series I have share a bunch of power tips for making this easier and this is a quick cheat sheet of them all.

From Part II: Getting Started

Power Tip: Once you have completed the tools install, go into to SQL Server and backup the TFSIntegrationPlatform database immediately. There are not only a few odd bugs that roam around which may cause you to need it but if you want to test on a clean environment, a restore is quicker than a reinstall.
Power Tip: Make a common root for the TFS code and yours (in my case I used RangersCode) and then create sub directories in there for platform and your code (so I had My Production and MS production folders under RangersCode). This helps keep the items close, which makes things easier later plus keeps them separate so you can identify them.

From Part III: Overview of adapters

Power Tip: The TraceManager puts all information written to it in the log files, so please make sure you do not put any sensitive information in there.

From Part IV: IProvider

Power Tip: Using Visual Studio 2010’s new “Generation from usage” features makes this stage of development much easier.

From Part V: Items (IMigrationItem & IMigrationItemSerializer)

Power Tip: VC stands for Version Control. This refers to an adapter that works with the source control aspects of the system. WI, work items, and WIT, work item tracking, are the same thing. File attachments in WI are NOT regarded as VC and must be handled by your WI adapter.
Power Tip: When you are downloading files in the IMigrationItem, you are responsible for the creation of the path too. So make sure you are creating directories and also checking what directories exist too.

From Part VIII: IMigrationProvider

Power Tip: In my implementation I used the very useful Path.GetTempFileName() from the .NET framework to get a place to put the file. However this causes an empty temp file to be created automatically and the platform doesn’t like that, so I needed to delete the temp file after that, and then call Download.
Power Tip: For folders creation or for deletes of files/folders you can use the Path property of the action to get the folder name.

From Part IX: IServerPathTranslationService

Power Tip: The neutral path, or canonical path as it is correctly named, is a path that is “Unix like”, (I.e. /src/project/). However these do not follow all the same rules as true Unix paths. For example : is a valid character in the path.

How to create an adapter for the TFS Integration Platform - Part X: Reflection on SharePoint

Robert MacLean — Tue, 08 Jun 2010 07:09:59 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

This post is not a technically heavy, like the most of the series, but more a reflection on what I learnt about integrating to SharePoint. This information will hold true for any type of work with SharePoint, not just if you are creating adapters.

What I used

For the WIT adapter I used on the lists.asmx web service, which allows you to work with list items. While with the VC adapter I used both the lists.asmx and copy.asmx web service and I ended up using some WebDav methods too. You may be asking why I needed lists.asmx with VC – because of SharePoint Rule #1 “Everything is a list” – even a document library. The copy web service allows for files to be uploaded to SharePoint.

My goal was to use just web services, which are one of the three ways you can interact with SharePoint the other two being WebDav and the API. The API is better than web services in every aspect (it is faster and more feature complete) but has a serious limitation, you MUST run the application using the API on the same server as SharePoint is install on. It makes it really only useful for tools used by SharePoint admins or web components, like web parts. WebDav is a standard for talking to web services and is generally regarded as a poorer implementation compared to the web services because it does much less.

In the end I had a bug with file deletion in the VC adapter when using the web services. After much fighting, I gave up and used WebDav for that one function.

What I learnt

If I rewrote these adapters I would use mostly WebDav and only use the lists.asmx web service for meta information tasks rather than manipulation. This is because while the WebDav implementation does less, it does all the fundamentals (create, update, delete) and it does it faster and more reliable way than the list and copy web services. The lists.asmx web service would be used only for getting item ID’s, lists of items, files and folders and maybe renaming since WebDav can’t rename. This would allow me to drop the copy web service would give me faster adapters and cleaner code in less time.

How to create an adapter for the TFS Integration Platform - Part IX: IServerPathTranslationService

Robert MacLean — Mon, 07 Jun 2010 04:04:46 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

IServerPathTranslationService takes the path to your source control item and translates it into a platform neutral path and visa versa. An example for this is if you were moving files between Windows and Linux. On Windows your path may be c:\RangersCode\My Production\ while on Linux that path needs to become/src/RangersCode/My Production/ to handle the differences you need to change it to a neutral path first.

The amount of sleep that I lost on path translation is embarrassing because the concept is dead simple, applying it correctly is ridiculously hard. The de facto guide for how this should work can be found on Willy-Peter’s blog, however there is also an update based on a lot of question asking by me which you may want to read.

This is only needed for VC adapters so if you just want a WI adapter you can skip this.

Power Tip: The neutral path, or canonical path as it is correctly named, is a path that is “Unix like”, (I.e. /src/project/). However these do not follow all the same rules as true Unix paths. For example : is a valid character in the path.

The two methods you need to implement are:

TranslateToCanonicalPathCaseSensitive

This method requires you provide a neutral path for one of your paths. For me this is simply just putting a leading slash on the item’s URL:

public string TranslateToCanonicalPathCaseSensitive(string serverPath)
{
    TraceManager.TraceInformation("WSSVC:TranslationToCanonical - {0}", serverPath);
    string localPath = string.Format(CultureInfo.CurrentCulture, "/{0}", serverPath);
    
    TraceManager.TraceInformation("WSSVC:New:{0} -> {1}", serverPath, localPath);
    return localPath;
}

TranslateFromCanonicalPath

This method is the reverse from TranslateToCanonicalPathCaseSensitive it takes a neutral path and provides one that applies to your adapter. In my case it meant dropping the first character and making sure I had an absolute URI:

public string TranslateFromCanonicalPath(string canonicalPath, string canonicalFilterPath)
{
    TraceManager.TraceInformation("WSSVC:TranslationFromCanonical - {0} - {1}", canonicalPath, canonicalFilterPath);
    string result = new Uri(canonicalPath.Substring(1)).AbsoluteUri;
    TraceManager.TraceInformation("WSSVC:TranslationFromCanonical:Result {0}", result);
    return result;
}

First in the Platform’s Eyes

There is an interesting thing that the platform does when it comes to server path translation, it creates this class first. This is before anything else, like the configuration service, so you need to make sure this class relies on very little, if any ,outside information. During the creation it also takes the root path from the filter items in your configuration and passes it to TranslateToCanonicalPathCaseSensitive to get the root neutral path. It needs to know this because it will want to strip this information out when it passes it to the other adapter and add it back when other adapters pass their paths to you.

How to create an adapter for the TFS Integration Platform - Part VIII: IMigrationProvider

Robert MacLean — Fri, 04 Jun 2010 00:50:36 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

The IMigrationProvider interface is the sister to IAnalysisProvider and handles the writing to your system. As with IAnalysisProvider it include some methods you can ignore.

InitializeServices

As with IAnalysisProvider the InitializeServices method is what is called first and is used for all setup. In my implementation I do a lot of setup for SharePoint which may not apply to other implementations. One thing you must do though, is register your item serialiser with the platform as follows:

changeGroupService.RegisterDefaultSourceSerilizer(new SharePointVCMigrationItemSerializer());

ProcessChangeGroup

The ProcessChangeGroup method is the most important method of IMigrationProvider as it is called to do the write operation. You are provided a ChangeGroup and the Actions property of that ChangeGroup contains each file/folder/item you need to write/update/delete to your system. The ProcessChangeGroup needs to return a log of what has happened so that the platform knows all the actions were performed and also so it can correctly tie up item unique ID’s in your system with the other system unique item ID’s. The log is done with a ConversionResult

ConversionResult conversionResult = new ConversionResult(configurationService.MigrationPeer, configurationService.SourceId);

Each action has an Action which tells you what you need to do with the item, be it an update or add or delete etc…

Each action also has an ItemTypeReferenceName which tells you what it is. For WIT this is not too important as you will be dealing with work items, but for VC this very important as it could be a concrete item file or folder or a more theoretical item like a branch or merge instruction.

So you need to loop over all the actions and based on the action + type do the correct thing:

foreach (MigrationAction action in changeGroup.Actions)
{
    if (action.Action == WellKnownChangeActionId.Add || action.Action == WellKnownChangeActionId.Edit)
    {
        if (action.ItemTypeReferenceName == WellKnownContentType.VersionControlledFile.ReferenceName)
        {

Once you have completed your action you need to add the information to the conversion result log. My two adapters do this very differently for no reason other than I wrote the VC adapter much earlier and when I write the WI adapter later I did a more refined generic implementation there. The key part of the adding the information though is below. The most important thing is to provide the ID (the third parameter) to the platform so it knows how to link your item in future which is needed for deletes and updates.

conversionResult.ItemConversionHistory.Add(new ItemConversionHistory(sourceSystemId, string.Empty, newSharePointId.ToString(), string.Empty));

Items and VC

With the VC adapter the way you request the actual file you want is using the Download method on the source item and providing a path.

Power Tip: In my implementation I used the very useful Path.GetTempFileName() from the .NET framework to get a place to put the file. However this causes an empty temp file to be created automatically and the platform doesn’t like that, so I needed to delete the temp file after that, and then call Download.

Power Tip: For folders creation or for deletes of files/folders you can use the Path property of the action to get the folder name.

Items and WIT

WIT is easier when it comes to writing because you do not need to worry about paths and files - you just need to do some XML parsing. All the information about the item will be provided to you in the MigrationActionDescription property of the action and you need to parse that into an item. Since the mapping of field names is handled by the platform this is very simple. In my case the following small method was all I needed to build a list of fields:

private static Dictionary<string, object> BuildFieldList(IMigrationAction action)
{
    Dictionary<string, object> fields = new Dictionary<string, object>();

    XmlNodeList columns = action.MigrationActionDescription.SelectNodes("/WorkItemChanges/Columns/Column");

    foreach (XmlNode columnData in columns)
    {
        string fieldValue = columnData.FirstChild.InnerText;
        string fieldName = columnData.Attributes["ReferenceName"].Value;

        if (string.IsNullOrEmpty(fieldName) == false)
        {
            fields.Add(fieldName, fieldValue);
        }
    }

    return fields;
}

Item ID

The platform handles the mapping of item ID’s too, so if you need to know what item needs to be updated or deleted it can be found in the MigrationActionDescription. The following method will work regardless of what your system is:

private string GetSharePointID(IMigrationAction action)
{
    TraceManager.TraceInformation("WSSWIT:MP:GetSharePointID");
    XmlNode workItemChangesNode = action.MigrationActionDescription.SelectSingleNode("/WorkItemChanges");
    string value = string.Empty;

    if (workItemChangesNode.Attributes["TargetWorkItemID"] == null)
    {
        TraceManager.TraceInformation("WSSWIT:MP:GetSharePointID:Cannot find work item id. XML is: {0}", workItemChangesNode.OuterXml);
    }
    else
    {
        value = workItemChangesNode.Attributes["TargetWorkItemID"].Value;
        TraceManager.TraceInformation("WSSWIT:MP:GetSharePointID:Value {0}", value);
    }

    return value;
}

How to create an adapter for the TFS Integration Platform - Part VII: WIT Conflict Handling

Robert MacLean — Thu, 03 Jun 2010 00:40:17 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

The WIT adapter needs a custom conflict type and a custom conflict handler, really for no reason other than the platform expects it.

Conflict Handler

If you have no reason for a custom conflict handler, a simple implementation which allows for manual resolution can be created, which is what I have below.

public class SharePointWITGeneralConflictHandler : IConflictHandler
{
    public bool CanResolve(MigrationConflict conflict, ConflictResolutionRule rule)
    {
        return ConflictTypeHandled.ScopeInterpreter.IsInScope(conflict.ScopeHint, rule.ApplicabilityScope);
    }

    public ConflictResolutionResult Resolve(MigrationConflict conflict, ConflictResolutionRule rule, out List<MigrationAction> actions)
    {
        actions = null;

        if (rule.ActionRefNameGuid.Equals(new ManualConflictResolutionAction().ReferenceName))
        {
            return ManualResolve(out actions);
        }

        return new ConflictResolutionResult(false, ConflictResolutionType.Other);
    }

    public ConflictType ConflictTypeHandled
    {
        get;
        set;
    }

    private static ConflictResolutionResult ManualResolve(out List<MigrationAction> actions)
    {
        actions = null;
        return new ConflictResolutionResult(true, ConflictResolutionType.Other);
    }
}

Conflict Type

If you have no reason for a custom conflict type, you can do what I did which is to re-implement the generic one with even less features namely only supporting ManualConflictResolution and a very simple scope hint.

public class SharePointWITGeneralConflictType : ConflictType
{
    public static MigrationConflict CreateConflict(Exception exception)
    {
        return new MigrationConflict(
            new SharePointWITGeneralConflictType(),
            MigrationConflict.Status.Unresolved,
            exception.ToString(),
            CreateScopeHint(Guid.NewGuid().ToString()));
    }

    public static MigrationConflict CreateConflict(Exception exception, IMigrationAction conflictedAction)
    {
        return new SharePointWITGeneralConflictType().CreateConflict(exception.ToString(), CreateScopeHint(Guid.NewGuid().ToString()), conflictedAction);
    }

    public override Guid ReferenceName
    {
        get
        {
            return s_conflictTypeReferenceName;
        }
    }

    public override string FriendlyName
    {
        get
        {
            return s_conflictTypeFriendlyName;
        }
    }

    public override string Description
    {
        get
        {
            return s_conflictTypeDescription;
        }
    }

    public SharePointWITGeneralConflictType()
        : base(new SharePointWITGeneralConflictHandler())
    { }

    public static string CreateScopeHint(string sourceItemId)
    {
        return string.Format(CultureInfo.CurrentCulture, "/{0}/{1}", sourceItemId, Guid.NewGuid().ToString());
    }

    protected override void RegisterDefaultSupportedResolutionActions()
    {
        AddSupportedResolutionAction(new ManualConflictResolutionAction());
    }

    private static readonly Guid s_conflictTypeReferenceName = new Guid("{606531DF-231A-496B-9996-50F239481988}");
    private const string s_conflictTypeFriendlyName = "TFS WIT general conflict type";
    private const string s_conflictTypeDescription =
        "This conflict is detected when an unknown exception is thrown during Work Item data submission.";
}

How to create an adapter for the TFS Integration Platform - Part VI: IAnalysisProvider

Robert MacLean — Wed, 02 Jun 2010 07:22:08 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

IAnalysisProvider, has a name that is a bit misleading, or was misleading to me because for a long time I thought it did some analysis of the environment as a pre-step and then real work happened elsewhere. The reality is the IAnalysisProvider is the reader part of your adapter, it’s goal is to get data from your system and into a format and/or location that the platform can work with.

IServiceProvider

IAnalysisProvider inherits from IServiceProvider which means you need to implement a method for that, GetService, which just returns this object.

object IServiceProvider.GetService(Type serviceType)
{
    return (IServiceProvider)this;
}

Misc Methods

I am not cover every method you need to implement from IAnalysisProvider, because you seldom need to implement them all. For example in my implementation of DetectConflicts is just does some logging:

void IAnalysisProvider.DetectConflicts(ChangeGroup changeGroup)
{
    TraceManager.TraceInformation("WSSVC:AP:DetectConflicts");
}

InitializeServices

The first method you must care about is InitializeServices, this is the first method which is called by the platform and it does five key things in my scenario:

void IAnalysisProvider.InitializeServices(IServiceContainer serviceContainer)
{
    TraceManager.TraceInformation("WSSVC:AP:Initialize");
    this.analysisServiceContainer = serviceContainer;

    supportedContentTypes = new Collection<ContentType>();
    supportedContentTypes.Add(WellKnownContentType.VersionControlledFile);
    supportedContentTypes.Add(WellKnownContentType.VersionControlledFolder);

    SharePointVCChangeActionHandler handler = new SharePointVCChangeActionHandler(this);
    supportedChangeActions = new Dictionary<Guid, ChangeActionHandler>();
    supportedChangeActions.Add(WellKnownChangeActionId.Add, handler.BasicActionHandler);
    supportedChangeActions.Add(WellKnownChangeActionId.Delete, handler.BasicActionHandler);
    supportedChangeActions.Add(WellKnownChangeActionId.Edit, handler.BasicActionHandler);

    configurationService = (ConfigurationService)analysisServiceContainer.GetService(typeof(ConfigurationService));

    highWaterMarkDelta = new HighWaterMark<DateTime>(Constants.HwmDelta);
    highWaterMarkChangeset = new HighWaterMark<int>("LastChangeSet");
    configurationService.RegisterHighWaterMarkWithSession(highWaterMarkDelta);
    configurationService.RegisterHighWaterMarkWithSession(highWaterMarkChangeset);
    changeGroupService = (ChangeGroupService)analysisServiceContainer.GetService(typeof(ChangeGroupService));
    changeGroupService.RegisterDefaultSourceSerilizer(new SharePointVCMigrationItemSerializer());
}

The first part is the setting up of what types of content we support (lines 6 to lines 8). You can see above I only care about files and folders.
The second part is the setting up of what actions we support for reading (lines 10 to 14), which in this case is Add, Delete and Edit. Delete is a bit of a lie since we do not actually support it but we say we do.
The third part is getting the configuration service which is important since we will use it later (line 16).
The forth part is getting the HWM, or high watermark information (lines 18 to 21) which I will explain in a moment.
Lastly we register the default item serialiser (line 23) so that the platform knows how to convert the items.

Registration

We setup the content types and actions we support and then we need to register those and the way to do that is with RegisterSupportedChangeActions. What I did was to loop over the actions and then loop over the types finally calling RegisterChangeAction. You could do this differently, for example if you only supported some actions on some types:

void IAnalysisProvider.RegisterSupportedChangeActions(ChangeActionRegistrationService contentActionRegistrationService)
{
    TraceManager.TraceInformation("WSSVC:AP:RegisterSupportedChangeActions");
    this.changeActionRegistrationService = contentActionRegistrationService;
    foreach (KeyValuePair<Guid, ChangeActionHandler> supportedChangeAction in supportedChangeActions)
    {
        foreach (ContentType contentType in ((IAnalysisProvider)this).SupportedContentTypes)
        {
            changeActionRegistrationService.RegisterChangeAction(supportedChangeAction.Key, contentType.ReferenceName, supportedChangeAction.Value);
        }
    }
}

ChangeActionHandler

The ChangeActionHandler class is a separate class which is used in the IAnalysisProvider during registration which provides the minimal functionality for figuring out how to register a new action (i.e. add file, update work item etc…).

public abstract class ChangeActionHandlers
{
    protected ChangeActionHandlers(IAnalysisProvider analysisProvider)
    {
    }

    public virtual void BasicActionHandler(MigrationAction action, ChangeGroup group)
    {
        if (action == null)
        {
            throw new ArgumentNullException("action");
        }

        if (group == null)
        {
            throw new ArgumentNullException("group");
        }

        group.CreateAction(action.Action, 
            action.SourceItem, 
            action.FromPath, 
            action.Path, action.Version,
            action.MergeVersionTo,
            action.ItemTypeReferenceName, 
            action.MigrationActionDescription);
    }
}

High Watermark

High watermarks are a very interesting feature of the platform, and they let you store a value in the database for the usage of identification of change groups. One aspect I liked of it’s construction is its use of generics, meaning you can work with the types that make the most sense, so I have Int and DateTime, and as you associate a name to it.

To get the value from the database you called the Reload method, to set the value and save call Update.

highWaterMarkDelta.Reload();
highWaterMarkDelta.Update(deltaTableStartTime);

Conflict Types

I have mentioned conflict types briefly before and I have said that my VC adapter does not have a conflict type which is not 100% true. It does have one, the GenericConflictType, which is base from the platform. Below is the code snippet from the WIT adapter which does have a custom conflict type. The only difference with the VC adapter is that last line does not exist.

public void RegisterConflictTypes(ConflictManager conflictManager)
{
    TraceManager.TraceInformation("WSSWIT:AP:RegisterConflictTypes");
    this.conflictManagerService = (ConflictManager)analysisServiceContainer.GetService(typeof(ConflictManager));
    this.conflictManagerService.RegisterConflictType(new GenericConflictType());
    this.conflictManagerService.RegisterConflictType(new SharePointWITGeneralConflictType(), SyncOrchestrator.ConflictsSyncOrchOptions.Continue);
}

GenerateDeltaTable

The next method to cover, and the second most important is GenerateDeltaTable which is responsible for actually getting the values from the source system. This is done below in two steps first GetSharePointUpdates and second PromoteDeltaToPending.

void IAnalysisProvider.GenerateDeltaTable()
{
    TraceManager.TraceInformation("WSSVC:AP:GenerateDeltaTable");
    highWaterMarkDelta.Reload();
    TraceManager.TraceInformation("\tWSSVC:AP:Initial HighWaterMark {0} ", highWaterMarkDelta.Value);
    deltaTableStartTime = DateTime.Now;
    TraceManager.TraceInformation("\tWSSVC:AP:CutOff {0} ", deltaTableStartTime);
    GetSharePointUpdates();
    highWaterMarkDelta.Update(deltaTableStartTime);
    TraceManager.TraceInformation("\tWSSVC:AP:Updated HighWaterMark {0} ", highWaterMarkDelta.Value);
    changeGroupService.PromoteDeltaToPending();
}

GetSharePointUpdates

This is a huge method and does the heavily lifting and I will skip covering all the boring details of talking to SharePoint and focus covering what you need to do. First you need to identify what is new, this is done using the HWM and comparing the modified date.

// item has been modified since HWM & before deltra table start time
if (item.Modified.CompareTo(highWaterMarkDelta.Value) > 0 && item.Modified.CompareTo(deltaTableStartTime) < 0)

You also need to figure out if the file is new or an update. In my VC adapter I created a special system called the ProcessLog. This was to cater with a situation caused by SharePoint and won’t apply to other systems. Once you done all of that you can tell the platform about it by creating an action and saving the action. The following code is for VC:

TraceManager.TraceInformation("\tChangeSet:{0} - {1} ({2})", highWaterMarkChangeset.Value, item.Filename, item.AbsoluteURL);
string itemType = item.ItemType.ToWellKnownContentType().ReferenceName;
ChangeGroup cg = CreateChangeGroup(highWaterMarkChangeset.Value, 0);
cg.CreateAction(actionGuid, item, null, item.AbsoluteURL, item.Version, null, itemType, null);
cg.Save();
highWaterMarkChangeset.Update(highWaterMarkChangeset.Value + 1);

and this is the same logic for WIT:

ChangeGroup changeGroup = CreateChangeGroup(highWaterMarkChangeSet.Value, 0);
changeGroup.CreateAction(actionGuid, task, string.Empty, listName, string.Empty, string.Empty,
    WellKnownContentType.WorkItem.ReferenceName, CreateFieldRevisionDescriptionDoc(task));
changeGroup.Save();
highWaterMarkChangeSet.Update(highWaterMarkChangeSet.Value + 1);

Revision Description Doc

While the VC adapter is fairly easy, the downloading is done in the SharePointItem - the WIT adapter doesn’t download anything. What it needs is a special XML file called a revision description document. You are responsible for the generation of this document as part of the creation of the action (you may have noticed that in the sample above).

This is what actually makes the field mapping possible, if you do not understand field mapping you must read Willy-Peter’s post on it. You can see below how I create my document, which is created per SharePoint list item and how I can support all the columns, including custom ones:

private static XmlDocument CreateFieldRevisionDescriptionDoc(SharePointListItem task)
{
    XElement columns = new XElement("Columns",
            new XElement("Column",
                new XAttribute("DisplayName", "Author"),
                new XAttribute("ReferenceName", "Author"),
                new XAttribute("Type", "String"),
                new XElement("Value", task.AuthorId)),
            new XElement("Column",
                new XAttribute("DisplayName", "DisplayName"),
                new XAttribute("ReferenceName", "DisplayName"),
                new XAttribute("Type", "String"),
                new XElement("Value", task.DisplayName)),
            new XElement("Column",
                new XAttribute("DisplayName", "Id"),
                new XAttribute("ReferenceName", "Id"),
                new XAttribute("Type", "String"),
                new XElement("Value", task.Id.ToString())));

    foreach (KeyValuePair<string, object> column in task.Columns)
    {
        columns.Add(new XElement("Column",
            new XAttribute("DisplayName", column.Key),
                new XAttribute("ReferenceName", column.Key),
                new XAttribute("Type", "String"),
                new XElement("Value", column.Value)));
    }

    XElement descriptionDoc = new XElement("WorkItemChanges",
        new XAttribute("Revision", "0"),
        new XAttribute("WorkItemType", "SharePointItem"),
        new XAttribute("Author", task.AuthorId),
        new XAttribute("ChangeDate", task.ModifiedOn.ToString(CultureInfo.CurrentCulture)),
        new XAttribute("WorkItemID", task.Id.ToString()),
        columns);

    XmlDocument doc = new XmlDocument();
    doc.LoadXml(descriptionDoc.ToString());
    return doc;
}

How to create an adapter for the TFS Integration Platform - Part V: Items (IMigrationItem & IMigrationItemSerializer)

Robert MacLean — Tue, 01 Jun 2010 00:23:51 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

An important class in your implementation is your item implementation, which is used to identify what an item (be that file, directory, list item, bug etc…) is. This class needs to implement IMigrationItem. This class is more important for VC than WIT but in both cases you need to put in all the properties you need to know about. You must also make sure that all properties are serialisable by the default XML serialiser in .NET.

Power Tip: VC stands for Version Control. This refers to an adapter that works with the source control aspects of the system. WI, work items, and WIT, work item tracking, are the same thing. File attachments in WI are NOT regarded as VC and must be handled by your WI adapter.

IMigrationItem

WIT

The WIT adapter is slightly smaller than the VC one since it is just a set of properties. I do not care too much about the inherited DisplayName property here either and the Download method is just logging. The only interesting part is the SimpleDictionary<T,V> I use. SimpleDictionary<T,V> is just to store Key/Value pairs of column information from SharePoint (because you may have customised the columns in SharePoint, I cannot hard code them). The reason I use this rather the Dictionary<T,V> which .NET provides, is because that class is not able to be serialised using the default XML serialiser. I will cover SimpleDictionary<T,V> in a later post.

public class SharePointListItem : IMigrationItem
{
    public SharePointListItem()
    {
        this.Columns = new SimpleDictionary<string, object>();
    }

    public string Id { get; set; }
    public DateTime ModifiedOn { get; set; }
    public string AuthorId { get; set; }
    public SimpleDictionary<string, object> Columns { get; set; }    
    public string DisplayName { get; set; }

    public void Download(string localPath)
    {
        TraceManager.TraceInformation("WSSWIT:MI:Download - {0}", localPath);
    }
}

VC

The VC adapter is a little more complex with more properties but the key difference is the DisplayName property, which I return the filename. Even more important though it the Download method which is used to get the actual file or folder to a specific location, provided by the localpath parameter, on disk for the platform to use.

Power Tip: When you are downloading files in the IMigrationItem, you are responsible for the creation of the path too. So make sure you are creating directories and also checking what directories exist too.

string IMigrationItem.DisplayName
{
    get { return Filename; }
}

void IMigrationItem.Download(string localPath)
{
    TraceManager.TraceInformation("WSSVC:Item:Download:From {0} to {1}", this.AbsoluteURL, localPath);
    if (this.ItemType == SharePointItemType.File)
    {
        TraceManager.TraceInformation("\tType is file");
        string targetDir = Path.GetDirectoryName(localPath);
        if (!Directory.Exists(targetDir))
        {
            TraceManager.TraceInformation("\tCreating Directory for file - {0}", targetDir);
            Directory.CreateDirectory(targetDir);
        }

        HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create(this.AbsoluteURL);
        webRequest.Credentials = this.Credentials;
        using (Stream responseStream = webRequest.GetResponse().GetResponseStream())
        {
            using (FileStream fileStream = new FileStream(localPath, FileMode.CreateNew, FileAccess.ReadWrite))
            {
                byte[] buffer = new byte[1024];
                int bytesRead;
                do
                {
                    // Read data (up to 1k) from the stream
                    bytesRead = responseStream.Read(buffer, 0, buffer.Length);

                    // Write the data to the local file
                    fileStream.Write(buffer, 0, bytesRead);
                } while (bytesRead > 0);
            }
        }

        TraceManager.TraceInformation("\tFile downloaded successfully");
    }

    if (this.ItemType == SharePointItemType.Directory)
    {
        TraceManager.TraceInformation("\tType is directory");
        if (!Directory.Exists(localPath))
        {
            TraceManager.TraceInformation("\tCreating Directory - {0}", localPath);
            Directory.CreateDirectory(localPath);
        }
    }
}

IMigrationItemSerializer

The migration item serializer is just a way to get your item to XML using .NET serialisation. My implementation of this is the exact same for both VC and WIT.

public class SharePointWITMigrationItemSerializer : IMigrationItemSerializer
{
    public IMigrationItem LoadItem(string itemBlob, ChangeGroupManager manager)
    {
        TraceManager.TraceInformation("WSSWIT:S:LoadItem");
        if (manager == null)
        {
            throw new ArgumentNullException("manager");
        }

        if (string.IsNullOrEmpty(itemBlob))
        {
            throw new ArgumentNullException("itemBlob");
        }

        XmlSerializer serializer = new XmlSerializer(typeof(SharePointListItem));

        using (StringReader itemBlobStringReader = new StringReader(itemBlob))
        {
            using (XmlReader itemBlobXmlReader = XmlReader.Create(itemBlobStringReader))
            {
                return (SharePointListItem)serializer.Deserialize(itemBlobXmlReader);
            }
        }
    }

    public string SerializeItem(IMigrationItem item)
    {
        if (item == null)
        {
            throw new ArgumentNullException("item");
        }

        TraceManager.TraceInformation("WSSWIT:S:SerializeItem - {0}", item.DisplayName);

        XmlSerializer sharePointTaskSerializer = new XmlSerializer(item.GetType());

        using (MemoryStream memoryStream = new MemoryStream())
        {
            sharePointTaskSerializer.Serialize(memoryStream, item);
            memoryStream.Seek(0, SeekOrigin.Begin);
            using (StreamReader streamReader = new StreamReader(memoryStream))
            {
                return streamReader.ReadToEnd();
            }
        }
    }
}

How to create an adapter for the TFS Integration Platform - Part IV: IProvider

Robert MacLean — Mon, 31 May 2010 00:10:13 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

IProvider is the first class we will look at implementing for both adapters (WI and VC) as it provides the core information for the platform to talk to our adapter. The first thing you provider needs is the ProviderDescriptionAttribute, which has three properties ID, Name and Version.

[ProviderDescription("{7F3F91B2-758A-4B3C-BBA8-CE34AE1D48EE}", "SharePoint TIP Adapter - Version Control", "1.0.0.0")]

The ID must be unique and you will need a record of it somewhere as it is used in configuration for the platform. The name and version are potentially used to make it easier for users, but I have not seen them used anywhere (maybe in future/different tools).

The only method in the provider is the GetService method which is used to get the implementations of the interfaces/classes we will be building later. Put another way this allows the platform to request a class which implements a specific interface using this method:

object IServiceProvider.GetService(Type serviceType)
{
    TraceManager.TraceInformation("WSSVC:Adapter:GetService - {0}", serviceType);

    if (serviceType == typeof(IAnalysisProvider))
    {
        if (analysisProvider == null)
        {
            analysisProvider = new SharePointVCAnalysisProvider();
        }
        return analysisProvider;
    }
    
    if (serviceType == typeof(IMigrationProvider))
    {
        if (migrationProvider == null)
        {
            migrationProvider = new SharePointVCMigrationProvider();
        }
        return migrationProvider;
    }

    if (serviceType == typeof(IServerPathTranslationService))
    {
        if (transalationProvider == null)
        {
            transalationProvider = new SharePointVCAdapterTranslation();
        }
        return transalationProvider;
    }        

    return null;
}

Above is the implementation is what I used in the SharePoint VC adapter, the WI adapter is the same except it does not have the server path translation service at the end.

Power Tip: Using Visual Studio 2010’s new “Generation from usage” features makes this stage of development much easier.

How to create an adapter for the TFS Integration Platform - Part III: Overview of adapters

Robert MacLean — Fri, 28 May 2010 01:42:16 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

The TFS Integration Platform has two types of adapters, a WI (for work items, tasks, bugs etc…) and a VC (version control) adapter and they are nothing more than a .NET assembly made up of a number of classes which, mostly, you will inherit from interfaces in the Toolkit project. For both adapters the key interfaces you need to implement are:

IProvider: Gives the platform the way to invoke your adapter.
IMigrationProvider: This is used for writing to the adapters source system, so for me SharePoint.
IMigrationItemSerializer: This provides support for converting the item to XML.
IAnalysisProvider: This is used for reading from the adapters source system.

as well as they both need to implement the ChangeActionHandlers abstract class.

The VC adapter also needs:

IServerPathTranslationService: Used to translate the path (i.e. directories and such) from other adapters to this adapter and visa versa.

While the WIT adapter needs:

IConflictHandler: Provides support for handling conflicts during the migration.

So in both adapters you will need a minimum of 6 classes you will implement, excluding any extra ones you will need for your specific requirements.

The core concepts of the adapters are all explained in the interfaces and so it appears that it is very simple to implement, and indeed it is – however there are some weird things which may catch you up which we will cover in detail in future posts.

TraceManager

Something very nice in the platform is the TraceManager class which is really just a wrapper around System.Diagnostics.Trace but it has some extras in that wrapper, such as being what is included in the console windows and log files. You will see this sprinkled through out my code because it is useful to to have when trying to debug later on.

Power Tip: The TraceManager puts all information written to it in the log files, so please make sure you do not put any sensitive information in there.

How to create an adapter for the TFS Integration Platform - Part II: Setup of the environment

Robert MacLean — Wed, 26 May 2010 07:34:11 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

Getting started with the adapter development is not the easiest task because you are stuck a little in the wild, so this part will serve as as a quick start guide for getting what you need to become a TFS Integration Platform developer.

SQL Server

The TFS Integration Platform requires Microsoft SQL Server so you need to install an instance of that.

TFS

It goes without saying, or maybe it doesn’t, that if you plan to write an adapter to integrate to TFS you will need TFS. Even if you don’t care about TFS, you will want to test and the TFS 2010 adapters are of the highest quality and so they make a great test target (so testing between your adapter and TFS). Thankfully with TFS 2010 you can now install on Windows 7 natively so this means as a developer you can have a great easy environment.

Target system (SharePoint for me)

Since I was developing for SharePoint that meant I needed a SharePoint installation, which meant a 20Gb Windows 7 Virtual Machine :( Hopefully for you this will be less of an issue.

TFS Integration Platform

The TFS Integration Platform, is a software component and database which runs on your machine and handles the actual moving of data around. You can get it from http://tfsintegration.codeplex.com/releases - however it may not be obvious which is the one you want since the team has so many download options, you want the tools:

During install you will get an option to install the service, which is recommended for production environments when you want to have the synchronisation running continuously. However for development this is not needed.

Power Tip: Once you have completed the tools install, go into to SQL Server and backup the TFSIntegrationPlatform database immediately. There are not only a few odd bugs that roam around the platform (it’s still in beta) which may cause you to need a restore of the database but if you want to test on a clean environment then a restore is quicker than a reinstall.

Platform Source

To build adapters you will also need the source code for the TFS Integration Platform which you can also get from CodePlex. Best is to get the latest drop of the code which you can get from the Source Control page and then by clicking on the Download link in the latest version box on the far right.

In there you will find the IntegrationPlatform folder which contains all the code from Microsoft.

Power Tip: Make a common root for the TFS code and yours (in my case I used RangersCode) and then create sub directories in there for platform and your code (so I had My Production and MS production folders under RangersCode). This helps keep the items close, which makes things easier later plus keeps them separate so you can identify them.

The code itself is for Visual Studio 2008, however you can be just like me and use Visual Studio 2010 and it will work just fine. Once you have done all of this you are finally ready for writing your adapter!

How to create an adapter for the TFS Integration Platform - Part I: Introduction

Robert MacLean — Tue, 25 May 2010 05:29:16 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

Since September 2009 I have been engaged in a ALM Rangers project, namely the TFS Integration Platform. Which is:

The TFS Integration Platform is a project developed by the Team Foundation Server (TFS) product group and the Visual Studio ALM Rangers to facilitate the development of tools that integrate TFS with other systems. Currently, the scope of this project is to enable TFS to integrate with other version control and work-item/bug tracking systems, but the eventual goal of this project is to enable integration with a broader range of tools/systems (i.e. build). This platform enables the development of two major classifications of tools: tools that move data unidirectionally into TFS, and tools that synchronize data bidirectionally.

So in short it is a integration system, like BizTalk or SSIS but specially built for version control and work items. I have not said TFS there because, it can work to migrate between other source control and work item systems provided adapters exist. Adapters are the logic which allows the TFS platform to connect to a variety of technologies, and my goal has been to build two of them – one for SharePoint lists and one for SharePoint document libraries.

You may have noticed that SharePoint isn’t a version control or work item system, so why integrate? Well lots of companies do use it for ALM related items, such as the lists being used for tracking work items and the document libraries are used to store content which should be in a source control system. This is the first post in a series which will give you an idea of what is involved in building adapters, show you what to avoid and hopefully give you a few laughs at my expense.

Now I want to be clear this series will not covering usage of the platform or any of the core concepts in it. For those please see the links below in particular Willy-Peter’s blog. You do need to understand a bit about how the platform works before you attempt to build your own adapter.

As all my work was done for the ALM Rangers the source code for my adapters is included in the code which can be obtained from the CodePlex site.

To help you on your way let’s list a few links which are key for this:

MSDN home page: http://msdn.microsoft.com/en-us/vstudio/bb840033.aspx
CodePlex Project home page: http://tfsintegration.codeplex.com
Willy-Peter Schaub’s blog: http://blogs.msdn.com/willy-peter_schaub/
MSDN Forums for the Platform: http://social.msdn.microsoft.com/Forums/en-US/tfsintegration

.NET 4 Baby Steps: Part XIII - Tiny steps

Robert MacLean — Wed, 19 May 2010 02:15:41 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

There is a bunch of tiny additions in .NET 4 which I have not covered yet, this post provides a quick hit list of some of the new and improved features:

New

StringBuilder.Clear: Quick method to clear a string builder.
StopWatch.Reset: Quick method to reset a stop watch timer.
IntPtr & UIntPtr: Both have had two new methods added, one for addition and one for subtraction.
Thread.Yield: Allows you to yield execution to another thread that is ready to run on the current processor.
System.Guid: Has got two new methods, TryParse and TryParseExact to allow for testing of the parsing.
Microsoft.Win32.RegistryView: This allows you to request 64bit or 32bit views of the registry.
Environment: Now contains two properties to identify 64bit scenarios:
- Is64BitOperatingSystem: To identify if the OS is 64bit.
- Is64BitProcess: To identify if the process is 64bit.
System.Net.Mail.SmtpClient: Support for SSL

Improved

Path.Combine: A new method overload to allow you to combine file paths.
Compression.DeflateStream & Compression.GZipSteam: They have been improved so that they so no try to compress already compressed data.
Compression.DeflateStream & Compression.GZipSteam: The 4Gb size limit has been removed.
Monitor.Enter: A new overload has been added which allows you to pass in a reference boolean which returns true of the monitor was successfully entered.
Microsoft.Win32.RegistryOptions: Now includes an option to specify a volatile key which is removed when the system restarts.
Registry keys are no longer limited to 255 characters.
System.Net.Mail.MaiMessage: Support for new headers
- HeadersEncoding: Sets the type of text encoding used in the mail header.
- ReplyToList: Sets the list of addresses to use when replying to a mail. This replaces ReplyTo which only supported one email address.
System.Net.NetworkCredential: To improve security passwords can now be stored in a SecureString.
ASP.NET Hashing: The default value has been changed from SHA1 to SHA256.
ASP.NET Output caching: Previously setting the output cache to ServerAndClient also required calling SetOmitVaryStar to ensure it would be cached on the client. From .NET 4, calling of SetOmitVaryStar is no longer needed.
TimeZoneInfo.Local & DateTime.Now: Both of these follow the OS daylight savings settings rather than using the .NET Framework settings.
When running on Windows 7, locale info will be retrieved from the OS rather than being stored in the framework.
Support for all 1400 characters of Unicode 5.1.
ServiceInstaller.DelayedAutoStart: If you on a more modern OS (Vista, Win 7 etc…) then you can services can start as Automatic Delayed. This means they start, but after system boot so that the user gets in quickly. This is now possible for your .NET apps using the DelayedAutoStart property.

.NET 4 Baby Steps: Part XII - Numbers

Robert MacLean — Tue, 18 May 2010 00:32:58 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

A new namespace has arrived in .NET 4 for those who spend a lot of time with numbers, System.Numerics which has two classes: BigInteger and Complex – and they are exactly what they say they are. BigInteger is for big integers and Complex is complicated ;)

BigInteger

BigInteger is a class, not a type (like float), which allows you to have an integer with no theoretical upper and lower limits! Why is that cool? think about Int64 which can do up to: 9,223,372,036,854,775,807. If you have an Int64 which has that massive value, and you add one to it, the Int64 it overflows and becomes -9,223,372,036,854,775,806. That is not possible with BigInt since it has no upper limit!

Being a class means it has methods and properties you can use too, for example some of the properties

IsZero: Tells you if it equals zero.
IsEven: Tells you if it is an even number.

An example of using it:

BigInteger firstBigInt = new BigInteger(Int64.MaxValue);
BigInteger secondBigInt = new BigInteger(Int64.MaxValue);

Console.WriteLine("First BigInt is even? {0}", firstBigInt.IsEven);
Console.WriteLine("First BigInt = 1? {0}", firstBigInt.IsOne);
Console.WriteLine("First BigInt is power of twp? {0}", firstBigInt.IsPowerOfTwo);
Console.WriteLine("First BigInt = 0? {0}", firstBigInt.IsZero);
Console.WriteLine("First BigInt is positive (1), zero (0), or negative (-1)? {0}", firstBigInt.Sign);
Console.WriteLine("{0} multipled by {0} is {1}", Int64.MaxValue, BigInteger.Multiply(firstBigInt, secondBigInt));

You can also use the standard operators (-, +, * etc…) with it.

This gives the following output (look at the size of the number from the multiplication!):

BigRational

What if you want to work with rational numbers with no limits, rather than integers? Then you can use the BigRational class the BCL team has made available at http://bcl.codeplex.com/

Complex

A complex number is a number that comprises a real number part and an imaginary number part. A complex number z is usually written in the form z = x + yi, where x and y are real numbers, and i is the imaginary unit that has the property i2 = -1.

That snippet is the first line from the documentation on System.Numeric.Complex and unfortunately I am not smart enough to know what they are talking about. So who should understand this?

Electrical engineers: Using Complex they can do the following: Resistance(R) and Reactance(X) to calculate the impedance Z.
Mathematicians: Vector Calculus as well as Graphs.
People using positional (mapping) info: X, Y coordinates on a map or 2d plane.

For an example I will just wimp out and show you what the MSDN documentation has:

// Create a complex number by calling its class constructor.
Complex c1 = new Complex(12, 6);
Console.WriteLine(c1);

// Assign a Double to a complex number.
Complex c2 = 3.14;
Console.WriteLine(c2);

// Cast a Decimal to a complex number.
Complex c3 = (Complex)12.3m;
Console.WriteLine(c3);

// Assign the return value of a method to a Complex variable.
Complex c4 = Complex.Pow(Complex.One, -1);
Console.WriteLine(c4);

// Assign the value returned by an operator to a Complex variable.
Complex c5 = Complex.One + Complex.One;
Console.WriteLine(c5);

// Instantiate a complex number from its polar coordinates.
Complex c6 = Complex.FromPolarCoordinates(10, .524);
Console.WriteLine(c6);

That produces:

Some info on complex is from: http://www.dotnetspider.com/resources/36681-Examples-On-Complex-Class-C-New-Feature.aspx

.NET 4 Baby Steps - Part XI: Special folders

Robert MacLean — Mon, 17 May 2010 04:18:27 PDT

Note: This post is part of a series and you can find the rest of the parts in the series index.

Environment.SpecialFolder

If you are building an application which takes advantage of special folders in Windows (special folders are folders like My Documents), you will be happy to know that .NET 4 has expanded the number of special folders it support, by adding 25 new options to the Environment.SpecialFolder enum.

The new options are:

AdminTools
CDBurning
CommonAdminTools
CommonDesktopDirectory
CommonDocuments
CommonMusic
CommonOemLinks
CommonPictures
CommonProgramFilesX86
CommonPrograms
CommonStartMenu
CommonStartup
CommonTemplates
CommonVideos
Fonts
LocalizedResources
MyVideos
NetworkShortcuts
PrinterShortcuts
ProgramFilesX86
Resources
SystemX86
Templates
UserProfile
Windows

Usage is:

Console.WriteLine(Environment.GetFolderPath(Environment.SpecialFolder.MyVideos));

GetFolderPath

The GetFolderPath method has also gotten an update with a new overload which takes a second enum, SpecialFolderOption. This has three values

None: Returns the path, but does not verify whether the path exists. If the folder is located on a network, specifying this option can reduce lag time.
Create: Verifies the folder path. If the folder does not exist, an empty string is returned. This is the default behavior.
DoNotVerify: Forces the folder to be created if it does not already exist.

Super fast network option:

Console.WriteLine(Environment.GetFolderPath(Environment.SpecialFolder.MyVideos, Environment.SpecialFolderOption.None));

Visual Studio ALM Ranger Champions for 2010!

Robert MacLean — Fri, 14 May 2010 00:48:07 PDT

I am a proud contributor to the Microsoft Visual Studio ALM Rangers (see this post for who they are) and each year, the Rangers have a vote for who they believe are helping the Rangers initiatives the most. The top four from the votes are honoured with the title of Champion! I was honoured in 2009 to be included in the list of the four champions and even more honoured that I have again been listed in the top 4!

Congrats to the other three champions and especially to Mathias Olausson, who was also re-awarded!

For more details on the latest Rangers champions see: http://blogs.msdn.com/willy-peter_schaub/archive/2010/05/12/external-visual-studio-alm-rangers-the-votes-have-been-tallied-and-the-2010-champions-are-have-been-known.aspx