Mehran Nikoo's Notes

Last week, I had a enquiry from a customer about the Spanish locale for the United States. As he mentioned, it does make sense to have this locale, especially for the users based in the southern regions of the US. If you are running Windows XP or Windows Server 2003, there is no such locale supported by the operating system so if you try to access this locale in a managed application by writing this line of code:

CultureInfo cultureInfo = new CultureInfo(“es-US”);

you will get an ArgumentException, which says: “Culture name ‘es-US’ is not supported”. As a workaround, you can use the “es-MX” locale or create your own locale.

But the good news is that the support for the “es-US” locale was added in Windows Vista and Windows Server 2008 so if you are running one of these operating systems, you can now use the es-US locale (LCID = 21514) and the same line of code we used above will work fine.

This page has a complete list of the locale IDs assigned by Microsoft so if you thinking of creating your own locale, check this list first to make sure there is no conflict with the existing locales.

As planned, VSTS 2010 Team Suite Beta 1, .NET Framework 4 Beta 1, TFS 2010 Beta 1 and VSTS 2010 Test Load Agent and Controller Beta 1 are now available for download from MSDN Subscribers area.

We now have 32-bit and 64-bit support for TFS and the TFS client OM. All of the client tools such as Visual Studio will continue to run in 32-bit environment though. For more information on the supported environments for TFS and the improvements in setup, administration and operations refer to Brian Harry’s post.

Most .NET developers and architects are familiar with various approaches to Visual Studio solution design: 

Most of the development projects contain more than one Visual Studio project. As soon as a second project is added to the solution, as a developer/architect, you start thinking about how the dependencies should look like. 

Meet “Camp P”
Members of camp P believe file references are evil as they cause all sorts of versioning and build issues when the dependencies go out-of-date. The members of this camp try to put everything in the same solution and life is great as long as you can count the number of projects with your fingers. There has been a debate out there as to whether Visual Studio should become quicker when it comes to handling large solutions. This issue was partly addressed by release of Visual Studio 2005 SP1 where we introduced some performance improvements in the IDE. These improvements are also rolled forward to Visual Studio 2008. However, you need to take into account all the work the IDE and the compiler need to do while you are typing in the IDE to provide you with Intellisense and compiler warnings/errors. So at some point, you will hit a practical limit on the number of projects you can have open in Visual Studio.

Meet “Camp F”
This is where the members of “Camp F” are coming from. They want to avoid the project references in order to speed up the IDE but they usually end up spending the time they saved on resolving the versioning issues. 

Now Meet Both!
None of these solutions are perfect but as long as the development team is consistent in following one of these approaches, then the team can live with it. This becomes a major problem when you have members from both camps in the same development team. This has been the case in most of the development teams I have worked with and I bet most of you have had similar experiences. So what is a typical day on such project? Somebody from “Camp F” is not happy with performance of the IDE while he is working on the “Order Processing” feature of the application. As a result, he decides to replace all of the references to the “UI Framework” projects with file references. But guess that? The dependency type is defined in the project file, so this change results in modification of the project file and the changes are checked back into the source control at some point. Few hours later, somebody from “Camp P” who is working on one of those “UI Framework” projects is trying to perform an integration test to validate a change she made to the UI Framework and finds out that the dependencies are out of date. She checks the source control as it was working fine until that morning and notices the change. She then reverts all of those changes as file references will make her job harder. And the team will soon end up in changing the references types back and forth between project and file references and and this changes cause further problems in the build process. Add to this all of the discussions/arguments as to which approach is better and you will see how much time is wasted as developers and build engineers keep changing the dependencies to suit their needs. 

What is the solution then? I am going to start with re-iterating what you probably know already but bear with me – I’ll try to keep it short! 

The Team Development with Visual Studio Team Foundation Server guide does a pretty good job at providing high level guidelines for choosing the right approach. It provides three options for managing the solutions: Single Solution, Partitioned Solution and Multiple Solutions. I am going to skip over the Single Solution. If you can manage everything in the same solution, then you are not worried much about the solution design, right? 

Partitioned Solution
If you work on a large system, consider using multiple solutions, each representing a sub-system in your application. These solutions can be used by developers in order to work on smaller parts of the system without having to load all code across all projects. Design your solution structure so any projects that have dependencies are grouped together. This enables you to use project references rather than file references. Also consider creating a master solution file that contains all of the projects. You can use this to build your entire application. 

Instead, you must use a script that understands the order in which the solutions need to be built. One of the maintenance tasks associated with a multiple-solution structure is ensuring that developers do not inadvertently create circular references between solutions. This structure requires complex build scripts and explicit mapping of dependency relationships. In this structure it is not possible to build the application in its entirety within Visual Studio. Instead, you can use TFS Team Build or MSBuild directly. 

The Partitioned Solution approach doesn’t scale well for very large solutions since it will make the IDE very slow and this sends you down the Multiple Solutions approach. So you group related projects and create a solution for each group. You use project references for dependencies inside the solution and file references for those dependencies that cross the solution boundaries. This is where the problems start: 

1- You cannot create a master solution that contains all of the projects. This is because you have created file references for cross-solution dependencies, which will cause problems when you try to build the master solution. 

2- Depending on which area of the system you are working on, you may want to have a different slice of the system in your solution. For example, if you are a member of a team working on a specific feature such as Order Processing, you want to have a vertical slice that goes across application layers (presentation, business and data). But if you are working on the UI Framework for the application, you want to have a horizontal slice that includes the presentation layer from all functional areas as well as the UI Framework. 

So even if all of the team members agree on the concept of Multiple Solutions, there are decision to be made on how the projects are going to be grouped into multiple solutions and as you can see in the above diagram, these categorisations don’t necessarily play well with each other. 

You always need to consider various factors such as the solution size and simplicity of the build process and choose one of these approaches (none of which are perfect): 

• Single Solution
• Partitioned Solution
• Multiple Solutions 

Multiple Partitioned Solutions 
Some of you may know about this already but there is another approach too. One can argue that it is the same as Partitioned Solution but in order to avoid confusion(!), I usually call it “Multiple Partitioned Solutions” or “MPS” (as you know we love TLAs). So what is it and how does it work? 

MSBuild is a great build engine. One of its features is the ability to follow and find the project references in a project even if those referenced projects are not inside the solution you are trying to build. This means you no longer need to have all of the project references inside the solution. Believe it or not, but you can successfully build the solution and the projects inside it even if the referenced projects are not in the solution. This will work both from the IDE and the command line as they both rely on the underlying MSBuild functionality. The only condition here is that the referenced projects need to have been built already. MSBuild is able to follow and find those referenced projects but it won’t build them for you. Is this a major problem? Probably not because when you get the latest version from the source control, you usually do a full build and then start working on your specific area. 

Let’s see how the system will be structured then. The dependencies between the projects are created as project references wherever possible. Depending on your requirements, you can create a solution that contains only a subset of projects you need to work on. Because the dependencies are project references, you can now have cross-cutting solutions that go across functional areas and architectural layers. You can also have a master solution because the dependencies are project references. Clearly, you don’t want to open the master solution in the IDE often as it will take a long time to load, it will be slow and you don’t usually work on all projects at the same time. The master solution will primarily be used for build purposes. 

Why do I call it “Multiple Partitioned Solutions”? Because the master solution is partitioned multiple times based on various perspectives. For example, the master solution can be partitioned into three solutions, one for each logical layer (such as presentation, business and data). At the same time, it can also be partitioned into another three solutions, one for each functional area (such as Order Processing, User Management and Call Centre). 

Like the other approaches, The MPS approach is not perfect and it has its own challenges. I personally prefer this approach though. It addresses the concerns around solution size and versioning and is very flexible as you can have cross-cutting solutions. But from a tooling perspective, we can provide you with better support so this is an area for improvement. As an example, if you try to remove a project from a solution in Visual Studio, it removes all of the dependencies on that project too. If you are following the MPS approach, this is not necessarily what we want. This is not as bad as it looks as in most projects I have seen, the solutions are created and maintained by dev leads, architects and/or build engineers so as long as they know what they are doing, it will be fine but it would be nice to have a proper solution here. 

I have found a workaround for this, which is to unload the projects that depend on the project we are trying to remove before removing the project. This will prevent the dependencies from being dropped automatically. Another approach is to manually edit the solution file and remove the project(s). 

As I said, these are workarounds not solutions. When we remove a project, we ideally want to be able to specify whether we want the project to be removed from the dependencies or we are just trying to exclude that project from the solution. So maybe we could add an “Exclude” option to the project context menu in the Solution Explorer?  

So… have you used the MPS approach in your development projects? If yes, can you share your experiences? What are the challenges you have faced and how have you addressed them? What kind of support do you expect from the IDE in this area?

The Application Architecture Guide 2.0 is out and you can now download it from here. As J.D. writes in his post, there are some changes since the Beta 2, including the foreword by Scott Guthrie (which follows the foreword by Soma added in the Beta 2 timeframe) and the incorporated feedback from the long list of internal and external reviewers. 

Working on this guide has been a great experience in the past few months, working with the core team and the contributors and reviewers from various product and consulting teams at Microsoft as well as partners and customers. Since this is an architecture guide, it is all about best practices and general guidance and it was amazing to see how we started with varied (and sometimes conflicting) views on different subjects and how we came to an agreement in those areas as we came closer to the release date and we all learnt new ways of looking at various architectural topics.

One of the interesting challenges for us during the development of this guide was to make sure we keep it up-to-date as we announced new products and technologies and made decisions about our development platform roadmap. Clearly, the Microsoft application platform will evolve and we have a long list of products to be released in the next couple of years so the p&p team will be working with various product teams to publish prescriptive guidance and best practices and to revise the existing guides where necessary.

We hope that you enjoy reading this guide and please keep your feedback coming via the CodePlex site.

When you create a document-level customisation for Office using VSTO, the customisation is compiled into a .NET assembly and the location of this assembly is stored in a custom document property called _AssemblyLocation. When loading the document, Office first checks to see whether this custom property is present and if it is, it tries to load the customisation. Now what if you are going to send this document to another organisation or department who don’t have (or don’t want to have) that customisation (assembly)? Since they don’t have the assembly on their machine, they will see an error message presented via a dialog box saying that the assembly could not be found, which is not nice.One way to prevent the code from running but without receiving an error message is to hold down the SHIFT key (as described on MSDN) when you are opening the document via the File menu. Note that this solution does not work if you are opening the document using the “Getting Started” task pane. This solution works but it requires the user to open the document using the File menu and they need to remember to hold down the SHIFT key so it is not necessarily a desired solution.   

The alternative solution is to remove the custom document property that points to the customisation assembly. This way Office will not try loading the customisation assembly on the end-user’s machine so they will not get the error message. However, you may need to put those custom properties back in the document if they user modifies the document and returns the document back to you.So how can you remove the custom properties? 

Manually
Open the document in the Office application (Word, Excel or PowerPoint), go to Properties -> Advanced Properties -> Custom and remove the assembly location custom property.

ServerDocument Class in VSTO
Both versions of VSTO (VSTO 2005 SE and VSTO 3.0) come with their own version of this class and have a very similar functionality. Note that you don’t need to have Office installed on the machine that is trying to modify the document using the ServerDocument class so you can perform this process on a server machine as part of an automated process that you run before sending out Office documents. You can find more information on this approach here.

OpenXML
If you are using Office 2007, you can access and manipulate the custom document properties by using the types in the System.IO.Packaging namespace or by using the Open XML Format SDK. Again, you don’t need to have Office installed on the machine that is using these components to manipulate the Office documents.  

As I mentioned earlier, when you receive the document from the other party, you may want to add the VSTO customisation again. You can use any of the approaches mentioned above to put the custom properties back on. (Thanks to Mary Lee for the pointers)

Application Architecture Guide Beta 2 is now available for download from CodePlex. We have got some general improvements in the Beta 2 release. There are also some new additions and JD Meier has a list of the key changes in his blog post.

If you have been using the .NET Framework since its first version, you may remember the Application Architecture for .NET guide, which was published back in 2002. Most of the subjects covered in this guide are still relevant but since then, .NET Framework has come a long way and there are loads of new features available in the framework such as automatic transaction management, WCF, WFP, WF, ADO.NET Entity Framework, etc, etc. So the patterns and practices team thought this is a good time to revisit this guide and rewrite it to bring it up-to-date.

We have been working on this guide for the last few months and the first beta is now available for download from here. This release has a very practical approach to application architecture and breaks down the applications based on the “Application Type” and the “Architectural Style“:

It then provides specific guidance related to the application type and architectural style. The guidance is mainly provided in the form of “Architecture Frames“, which are ”collection of hot-spots that represent key engineering decisions”. Here are a few architecture frames used in this guide: Authentication and Authorisation, Caching and State, Config Management, Data Access and Logging and Instrumentation. Each architecture frame is then broken down into fine-grained questions. So for example, the following questions are related to the Data Access architecture frame:
- How to manage database connections?
- How to handle exceptions?
- How to page records?
- How to perform transactions? 

When designing the architecture, we usually deal with cross-cutting concerns so looking at the system from various perspectives (such as application type and architectural style) is a great way of tackling the problem and allows us to provide the most relevant guidance for each category. 

I don’t want to go into further details as J.D. has a great blog post with all the details. 

So what to do next? Go and download the guide, go through the content and let us know what you think. This guide is still in beta so you have the opportunity to let us know if:

- There is anything missing.
- You believe that specific parts of the guidance are not correct, too high level or too much prescriptive.
- You want to add more content to specific areas.

The best way to send your feedback is via the CodePlex site.

Earlier today, we announced the next wave of developer products and tools, namely Visual Studio 2010 and .NET Framework 4.0. Both of these products are major releases that bring new concepts and paradigms to the software development and introduce new first class citizens to the Visual Studio environment. The result will be an ever higher productivity for the development teams and lower barrier to entry for developing applications for various products and technologies we offer today and will ship within the next few years. 

The focus of the first annoncement is on VSTS 2010 (code-named “Rosario”) and the improvements to the ALM process. My favourite enhancements are: 

• Visualisation tools for change tracking across branches and merging into the production build
• Workflow-based builds, which allow the errors to be caught before they impact other team members (great news for those who have been buying coffee for their team mates!)
• Built-in support for UML and DSL in the IDE (just in case you missed the news, Microsoft announced its membership in the OMG earlier in September)
• Support for hierarchical work items in TFS

This is not an exhaustive list but these are the items that caught my eyes as I was reading the announcement. There is also a (good!) change in the product licensing for VSTS, which is great news for the development teams. Since I don’t want you to miss this announcement, I am going to write a separate post on this subject. 

As you can imagine, there are loads of more features to come with Visual Studio 2010 and .NET Framework 4.0. If you are going to the PDC, you will be lucky enough to hear about it all the time but if you aren’t, make sure you follow the news on the blogosphere and the PDC official web site. 

Additional resources:
- VSTS 2010 on Channel9
- VSTS 2010 and .NET Framework 4.0 Overview on MSDN

As we already know, apart from bug fixes, .NET Framework 3.5 SP1 includes major product enhancements such as ADO.NET Entity Framework, ADO.NET Data Services and enhanced LINQ to SQL (which now supports the new date and FILESTREAM data types in SQL Server 2008). Clearly, this is not an exhaustive list so please refer to the release notes for more information on the new features. It is also good to know that: 

• .NET Framework 3.5 SP1 introduces the concept of a client-only subset of the framework called “.NET Framework Client Profile”. The size of the runtime in the Client Profile is only 26.5MB so it is much smaller than the full framework. This allows solutions based on the client components such as WinForms, WPF and VSTO to be deployed much easier. Clearly, when you are developing your application, you need to make sure that you don’t use a feature that is not part of the Client Profile. When you install Visual Studio 2008 SP1, it adds a new property to the project settings in Visual Studio that will enforce the Client Profile policy. Enabling this option will prevent you from using the types in those assemblies that are not shipped as part of the Client Profile, which is exactly what you need.
• The setup package for .NET Framework 3.5 SP1 installs .NET Framework 2.0 SP2 and .NET Framework 3.0 SP2 first, which means you “technically” need to retest your existing .NET 2.0 and .NET 3.0 applications too.

More: Download Links, VS 2008 SP1 and NET 3.5 SP1 Dev Center

One of the namespaces introduced in the .NET Framework 3.0 is System.IO.Packaging (in the WindowsBase assembly), which provides classes that support storage of multiple data objects in a single container, like a ZIP file. These data objects can be referenced in a hierarchical format, similar to the file system. This functionality can be used to open, read and manipulating the files based on the Open XML standard since the Open XML file format follows the same principle. A while back, I wrote a piece of code for a customer to use the classes in this namespace for setting the values for custom properties in Word 2007 documents and Excel 2007 spreadsheets. This wasn’t hard but I had to use XPath queries and use the appropriate XML namespaces in order to find the elements I was trying to update. 

We then had an initiative to create an SDK that provides strongly-typed part classes for use with the documents based on Open XML. This SDK was available in CTP mode until earlier this week when its first version was released. You can now download the Open XML Format SDK from the Download Center. This SDK relies on the functionality provided by the System.IO.Packaging namespace so it requires .NET Framework 3.0. 

The Open XML Format SDK makes the life so much easier for the developers, but wait… we are not finished yet. Right after the release of the Open XML Format SDK, another open source project called “PowerTools for Open XML” was announced, which provides more than 30 PowerShell cmdlets to manipulate the Open XML files. So for example, there are cmdlets for manipulating the watermark, header and footer, style, etc. This means you can read and edit Open XML files on the server-side without using the Office object model and without a need for an Office 2007 license on the server machine. Here is a great screencast that includes some nice demos that show how you can use the PowerTools to go through a list of Word documents, add a watermark to all of them and make sure they all use the same text style. There is also another demo that performs a mail merge using a simple PowerShell script.

I remember that a few years back, I was working on a project where the customer decided to spend a considerable amount of cash on a document generation and rendering solution and the development team had to write a lot of code to populate the templates provided by the third-party solution. The integration and testing experience was quite painful too. It is great to see how the publication of Open XML as a standard and the development of great tools by Microsoft and the open source community has simplified the document generation process and I can clearly see how this will result in reduction of licensing and development costs.