In this post I'll begin to talk about getting a build process up and going. I'll cover at a high level a build process that I think works for small to medium size teams, talking about some steps you might want your build process to go through.
In my last post I either completely ommitted or glossed over some things. In this post, I'll cover the use of the versioning and resource attributes as well as how I layout my web application projects.
Versioning Attributes
You'll notice that I use three different attributes for denoting the version of an assembly: AssemblyVersion, AssemblyFileVersion, and AssemblyInformationalVersion. The first attribute, AssemblyVersion, should be very familiar to everyone as it is the one used to specify the version number that makes up part of the fully qualified assembly name. As you can see in the below screenshot of my GAC, System.Core's version is 3.5.0.0; however if you look at the properties of the System.Core.dll, you can see that there is an additional version #s listed.
These #s come from the AssemblyFileVersion and AssemblyInformationalVersion attributes and are a great way to keep track of which build assemblies came from.
You really want to avoid incrementing your AssemblyVersion attribute with every build, specially if you're strongly signing your assembly because if you did, that would force all of your clients to rebuild every time you do. Even MS will keep the version # of assemblies the same between .Net Framework service packs. Could you imagine having to redirect all of your applications every time a new service pack was released!
Combining the use of all three attributes lets you maintain your AssemblyVersion static while the AssemblyFileVersion and AssemblyInformationVersion attributes let you identify specifically which build a particular assembly came from.
Resource Attributes
The next thing I want to cover is the use of the NeutralResourcesLanguage attribute. This attribute is really about giving the .Net Framework a hint as to what your "Neutral" language is...You can read more about that in this article. To quote the article. "A direct consequence of the way the ResourceManager object looks for resources is that resources related to the default locale are located only after checking that no subdirectory for that culture exists. This means, for example, that all the resources for an application whose default culture is en-US are loaded only after checking that no en-US folder exists under the app's main directory. You can avoid this little overhead by applying the NeutralResourcesLanguage attribute to the main assembly to inform the resource manager about the language for the neutral resources that are embedded in the main assembly".
Project Naming Convention
I touched on one naming convention in my last post, and that is to name the project the same as the assembly name. My other convention is to give unit test project the same name as the project it will be testing but just add the UnitTest suffix to it. You can see that in this screenshot:
In this same screenshot you can see that I name the Web Deployment project, the same as the Web Application project but just add the .Deployment suffix.
Web Project Code and UI Separation
You can also see above that I have both a BlackBeltSolutions.Sample.Web.UI project (A Web Application Project) as well as a BlackBeltSolutions.Sample.Web project (A Class Library Project). I prefer to separate the .aspx/.ascx, etc files that are the content to be deployed from the actual code. I do not go as far as putting the codebehind in the class lib project, just the presenter, view definitions (i.e. view interfaces), HttpModules, etc. Essentially anything that is not either a codebehind or content that is to be deployed is in the web app project and everything else in the class lib project. The reason for this is that I found if you mix the two, sometimes you want to create folders not because of content but to create a namespace. When you do this, mixing the content and code can be confusing. It also does force you to visibly see and think about the separation of the codebehind from the presenter/view definitions. Call me anal, but that's what I like...
Build Output
The next thing I want to cover is how I change the build output location. In a web application, I do two things. Have all the projects except for the Web.UI project build to the same directory. Really, the only reason I do this is to eliminate having multiple copies of each of the DLLs in each of the projects. For example, both the BLL and DAL project reference the BlackBeltSolutions.Sample project because that project would contain the model classes. If I leave the build output directory as the default, both the BLL and DAL projects would copy the BlackBeltSolutions.Sample DLL into their respective bin folders. This isn't so bad when it's a small solution but if you have a big one, you can end up with quite a bit of copies of DLLs all over the place. Below you can see that I change the output directory to
In the deployment project, I do something similar but instead of naming the folder SiteComponents, I name it after the name it after the website.
Then your BuildOutput directory will look like:
This also give you a well known place that you continuous integration build script can target when it needs to archive the build output.
Conclusion
I don't think I've left anything out...But if I did, there will be a part Trois (aka 3).
Hope this helps
Now that I've covered one way to structure your repo within and across systems, I'll cover what I usually do when first starting a solution. This includes project naming convention, build output directory, project properties and deployment project setup.
Lets first walk though where I place solution and project files. the below picture denotes where I place solution files (In the Source folder). The Source folder is the place where I put all of my solutions files. Depending on the system being written, it may make sense to have multiple solutions files, each grouping different projects uniquely. The folder structure matches my previous post on repo structure.
The next thing to note is that each of the project names match the assembly name as well as the default namespace. I like this convention because it lets you know which output comes from which project.
Another thing that I like to do is to treat warnings as errors. Usually if the compiler is warning you about something is with good reason...If there are warnings that I want ignored, then I usually use a pragma to turn specific warnings on/off.
The next thing I do is setup my assembly for signing. I no longer use the AssemblyKeyFile attribute because it has been deprecated and generates a warning. See this MS article for the details as to why this was deprecated; however, I think VS 2005/2008 does a horrible job of supporting this in the project properties tab. Every time you browse to the key file, it copies it locally! It does not support relative paths. So what I typically do is setup the key file reference through VS as shown below.
Then I unload the project and edit the project file's XML directly, and put the relative path, which point to the Builds\Certificates folder. Then when you reload the project you will see that the path is relative and you can delete the copy of the snk file that VS copied to the project folder.
Notice the AssemblyOriginatorKeyFile has been changed to the relative path...When you Reload the project, you can see that the relative path is now visible in the project properties window.
The last thing I do to get the projects ready to start work on is to get all the attributes setup. These are typically stored in the AssemblyInfo file which by default looks like the below screenshot.
There are quite of bit of attributes that are common throughout all of the projects in the solution, so I usually create a SolutionInfo.cs file to host these shared attributes. I also create a VersionInfo.cs file which is where the versioning information is stored. I separate the version information into a separate file because this is the file that my continuous integration environment will overwrite as it versions the builds. Of course things can't be too easy! To share those files across multiple projects, you have to make sure that you add them as a link; otherwise, VS will again make copies for you in each project. The below sequence of screenshots walks you through the process.
First create the two files and add them to the solution.
Once you've got the files in the solution, you can also add them to the project. This is where the tricky part come in because you have to make sure you add the files as Links (Drop down the Add button and you will see the option) otherwise VS will make copies instead of just reference the existing files...
Once you've done this, you will see the files added to the project. You can tell they were added as link since they will have the shortcut icon on the bottom left hand corder.
I then just move this files into the Properties folder so that they're alongside with the AssemblyInfo.cs file.
Once you've got the files in the right place, you can edit them. For example, the AssemblyInfo.cs file in the Bll project will look like:
The VersionInfo.cs fill will contain:
And finally, the SolutionInfo.cs file will contain:
This lets you share all of the common assembly attributes, get the version info ready for you continuous integration build to modify and keep the assembly specific attributes isolated.
Whew! Now will all that work done, you can start writing code! On the next post I'll talk about why I have both a .Web and .Web.UI project which you may have noticed in the above screenshots...
Hope this helps
Its is very typical for companies to have a set of common components. These are typically in one or more assemblies and shared by more than one system.In this post, I'll walk you through my through process on how I divide out projects and enable sharing of these common components between different project roots.
In a previous
post I mentioned how I typically structure my source code repository no matter whether I use TFS/Subversion/etc. The structure is really about being able to check out everything you need to build the project, including dependencies to dlls, build scripts, build tools, etc. At the very top of the structure is what I labeled as <Root>. Underneath this root are different folders where you can place different branches (Depending on your needs, but that's a future post) with the Main folder being synonymous to the trunk.
This <Root> typically is a system but could be an application. The way I see it, your repository structure can be affected by how you're going to deploy your code, meaning what gets deployed at the same time. So if you have a web application made up of multiple projects all shipped at the same time, I would setup the project as:
<Root>
- Main
- Source
- Code
- ProjectX
- ProjectY
This makes sure that when you branch you take all projects along with you that you deploy, ensuring that your branch reflects what you have deployed. So given this, lets say you have multiple roots (whether they represent applications or systems is up to you) and a suite of common components that both roots need to share. What do you do? Put all three under one <Root> so that you can do project references?? Like so:
<RootA>
- Main
- Source
- Code
- ProjectX
- ProjectY
- ProjectS
- ProjectT
- CommonX
- CommonY
I do not like this since it means that you'd be branching all three things at the same time even if you don't release all three at the same time, making for branches that do not match what you have deployed. Here's how I tend to do it:
<RootA>
- Main
- Source
- Code
- ProjectX
- ProjectY
CommonX.dll
CommonX.pdb
CommonY.dll
<RootB>
- Main
- Source
- Code
- ProjectS
- ProjectT
CommonX.dll
CommonX.pdb
CommonY.dll
<CommonComponentsRoot>
- Main
- Source
- Code
- CommonX
- CommonY
Notice how in the above structure, RootA and RootB use CommonX.dll and CommonY.dll and do not use project references. What this means is that you have a binary refence to these assemblies instead of project references. This does complicate things since it means that somehow these assemblies need to get copied over to these projects. I typically have the continuous integration build deploy the assemblies to projects that need them. This means that after a successful build of Common then RootA and RootB will have their continuous integration build kickoff since they got a drop of the new common assembiles. If you have good test coverage, the likelyhood of knowing if any of these changes to common broke either RootA/RootB should be increased and hopefully lets you know that you've made breaking changes. If you have made breaking changes and aren't ready to compensate for those in either RootA/RootB, you can stop the Common continous integration build from dropping new versions of the dlls into the SharedBinaries folder and rollback to the previous version of the Common dll in question. Once you've made the changes needed to support the new version of common, you can turn the droppping of new dlls back on.
One other thing to note is that I show also dropping the pdbs in the SharedBinaries folder. This will enable you to step through the Common libraries source code from RootA/RootB even if you CommonX.dll or CommonY.dll are release builds. The only drawback is that you have to open the source file for the common components you want to put a breakpoint on using File | Open instead of being able to use Solution Explorer...
Hope this helps...
Unless you've developed a one-off application, you're more than likely going to need to need to branch. In this post, I'll point you to some great documentation on how to decide on what your branching strategy should be. I will leave it to you to decide what meets your needs. In my last post I mentioned how I typically structure my source code repository no matter whether I use TFS/Subversion/etc and I'll assume you're using a structure similar to that one.
My one recommendation is to branch judiciously, meaning branch only when needed. Branching provides isolation at the cost of maintenance and merging. Depending on how long you go between merges, this can become a dreadful experience. I would suggest to merge at least once a week so that you feel the pain little by little instead of at the very end.
The VSTS Rangers team has some good advice in CodePlex http://tfsbranchingguideii.codeplex.com/ that has been divided into Basic, Standard, and Advanced branching plans. Here's a quick rundown, but I will not cover everything the guide goes through, so I highly recommend the various guides available at codeplex.
Basic Plan
Gives you the ability to support concurrent development (whether its by team/feature) having a stable main branch and a release branch for shipping bug fixes. Useful if you only do version releases.
Standard Plan
Adds to the basic plan the ability to also support for service packs.
- These service pack branches would go in the maintenance folder from the structure I use and older releases would go in the safekeeping folder.
Advanced Plan
Adds to the basic and standard plan by adding support for having hot fixes as a formal type of release.
- These hot fix branches would also go in the maintenance folder and older releases would go in the safekeeping folder.
When you check out the CodePlex project, make sure you download the drawings zip file it has a great poster that provides some walkthroughs.
The below repository structure is taken from a couple of sources and personal experience. Part of it is from the TFS Guide. Now don't dismiss it just because it comes from the TFS guide. It has great advice which applies to other source code repositories not just TFS. I am actually not a fan of TFS, prefering either Subversion or Git. Some of the structure also comes from Visual Studio Team System: Better Software Development for Agile Teams.
<Root>
/Development
/FeatureBranchXName
/<Branched From Main>
/FeatureBranchYName
/<Branched From Main>
/Main
/Builds
/Certificates
/Scripts (Contains build scripts)
/Tools (A dir for each tool)
/XMLPreprocess
/etc.
/Docs (Contains product docs etc Shipped to customer)
/Source solution (.sln files)
/Code (Contain folder for all source)
/ClassLibrary1 (Contains ClassLibrary1.csproj)
/MyApp1Web (Contains MyApp1Web.csproj)
/Database (Depending on whether or not db is shared with other applications you may not want this here)
/UnitTests (Container folder for unit tests)
/ClassLibrary1.UnitTests (Contains test project and code)
/MyApp1Web.UnitTests (Contains test project and code)
/SharedBinaries (Shared binaries e.g. libraries)
/SharedSource (Shared source code)
SolutionInfo.cs (Shared file used to contain assembly attributes like copyright, NeutralResourcesLanguageAttribute, etc)
/Tests (Container for tests Testcases - Only needed if not using a tool like Quality Center)
/FunctionalTests
/PerformanceTests
/SecurityTests
/Maintenance
/Release1
/<Branched From Main>
/Release2
/<Branched From Main>
/Safekeeping
/Release1
/<Branched From Main>
/Release2
/<Branched From Main>
/Spikes
/...
/Tags
/v1_0_0_0
Most of the folders are self explanatory, but let me give a quick synopsis but you can get details from the TFS Guide.
Now the location of this will depend on what repository you use, for example for Subversion, I typically use one repo per system.
Typically used for team/features branches which you may or may not use depending on your branching strategy. I'll be covering that in an upcoming post.
As the name implies, this is synonymous to Trunk but I used Main to keep Subversion terminology from leaking into the structure
Root folder for all things related to the build process.
Contains thinks like your snk file or authenticode cert
Hopefully self-explanatory 
Parent folder used to contain subfolders for each of the tools used during the build process.
Folder for documentation that will be shipped to the client (i.e. help file project files)
Folder containing branches which are currently under active maintenance (i.e. code in production)
Folder containing archived branches.
Folder containing spike projects for the system that root is for. This lets people have version control for spikes and gives and can even give you glimpse as to why certain approches were taken on production code if a spike was used to test out theories.
Typically only used if your repository needs a physical folder to contain tags (i.e. labels)
Here's a picture that I think is a little easier to see than the above ASCII tree.
Some additional things to note. Underneath the code folder I typically name the folder containing the project to match the project name which in turn matches the name of the assembly (The root namespace of the project also matches the assembly name). The unit test project for that project uses the same name as the project the unit tests will be covering but the the ".UnitTests" suffix. This is because you may also have an integration tests assembly. I typically use different projects for unit and integration tests to make it easier to separate when the tests will be run by the build environment.
I've been on the fence about using SharedSource vs. just having the files right in the Source folder (at the same level that the .sln files are put). Still not sure but I've shown the SharedSource folder in this post so that you can make up your own mind.
I like having the tools included (and anything else you need to build) in source control so that when you checkout the project, you have everything you need to build. I don't like having the tools (or other dependencies) in a separate location in the repository and then having to checkout both the project and the tools and needing to put the tools in a well known folder so that your project can reference them...
I'm also a big fan of XMLPreprocess, and the MSBuild Extension Pack projects.
In the upcoming posts I'll talk about how to increment version numbers, get the build going, etc.
Now that I provided you with a spreadsheet you can use to track your sprints, in my upcoming posts, I'm going to talk about things that you generally need to think about when starting up a new project on a more technical level. I won't go overly in depth unless warranted and will provide links to materials I used to come to my decisions as well as my rationale and hopefully that will help someone out...Without further ado, here's my list:
- Repository Structure
- Branching Strategy
- Tool Selection (things like unit testing/mocking frameworks/etc)
- Build Environment Setup
- Deployment Options
- Solution Architecture Decisions
Once I finish this up, I'll get in depth on the solution architecture components. Hope this gives you a look at what's coming up.
As the title suggest, about the backlog. There are tools out there that let you do agile project management but some times the easiest thing is just to use a spreadsheet. I haven't seen too many examples of those, so I figured that would be an area I could help out in and walk you though a spreadsheet that has evolved over time for me and actually started from a sample that I got from my ScrumMaster certification class.
Welcome to my blog. My name is Carlos Santos and have been doing software development since 1996. I've been a solutions architect for various teams, done training classes, been selected from hundreds of MCTs to work at TechEd twice and developed and validated test for BrainBench. My goal here is to talk about the design tradeoffs I've faced during the development of existing and new systems.
I'll be talking about various things, ranging from solution architecture (And the decisions at each of the layers) to agile practices.
The reason I chose Snowflake Design for the name of the blog is because enterprise and solution architecture is so dependent on the environment and the tradeoffs you are willing to make, that like snowflakes, architectures are typically different from one environment to another. As they say, there is no silver bullet.
And now, for the disclaimer
******************DISCLAIMER ****************
This is a personal weblog. The opinions expressed here represent my own and not those of my employer.
All data and information provided on this site is for informational purposes only. blackbeltsolutions.com makes no representations as to accuracy, completeness, currentness, suitability, or validity of any information on this site and will not be liable for any errors, omissions, or delays in this information or any losses, injuries, or damages arising from its display or use. All information is provided on an as-is basis.
In addition, my thoughts and opinions change from time to time…I consider this a necessary consequence of having an open mind. This weblog is intended to provide a semi-permanent point in time snapshot and manifestation of the various memes running around my brain, and as such any thoughts and opinions expressed within out-of-date posts may not the same, nor even similar, to those I may hold today.
*************************************************