More Tools: NAnt

NAnt Automated building of .net projects made easy...

Though I have been aware of it for quite sometime, I recently read an article in CoDe magazine the provided detailed instructions as to installation and a sample implementation of NAnt. I had wanted to try it out but was a little turned off by the very dry and difficult documentation I had read up till now. Unfortunatly, this is often the case with techie, open source projects.

First I setup my hello world application, next I followed the instructions and within an hour or so I had a batch file and a build.xml file from which i could execute an NAnt build. The instructions in the CoDe article, Even provided instructions to create either a debug or a release build. They did not stop there however, they also included help in creating a deployment .zip file with everything needed.

Very nice...

The article can be found at the following URL:
http://www.code-magazine.com/Article.aspx?quickid=0811051

What a Tool III

Introduction to GhostDoc

Published: 30 Oct 2006
By: Roland Weigelt

GhostDoc is a free add-in for Visual Studio that helps developers writing XML documentation comments.

Introduction
The XML documentation comments of C# reward you in multiple ways: Visual Studio shows their content on various occasions (e.g. in tooltips in the text editor, or in the object browser), and some tools (e.g. NDoc or Microsoft's documentation tool code-named Sandcastle) can generate nice looking help files for you. So overall, writing XML documentation comments sounds like a pretty good idea - unfortunately it often consists of a lot of stupid work that simply has to be done.

For example the documentation of constructors ("Initializes a new instance of ."), or properties (how often did you write "Gets or sets ..."? Or worse, "Gets or sets a value indicating whether..."?). Often enough you need the same documentation over and over again, e.g. when working with interfaces or class hierarchies.

What does GhostDoc do?
GhostDoc installs a new command for Visual Studio's C# source code editor. When editing a source file, you simply navigate the cursor into the method or property you want to document, call that command by pressing a hotkey (or using the context menu) and GhostDoc will insert an XML documentation comment. Much like typing "///" in front of the method or property, but instead of creating just an empty skeleton, GhostDoc tries to generate large parts of the actual documentation.

If your class member is an interface implementation or an override of a base class member, GhostDoc will use the existing documentation, regardless of where the interface or base class comes from. So basically what this means that you can re-use tons of documentation that Microsoft wrote - just remember the last time you've implemented IEnumerable and thought about how to comment the GetEnumerator() method.

In those cases where no existing documentation can be used, GhostDoc tries to guess the texts for the comments. While this idea seems to be a bit strange at first, under certain conditions (we'll get to that later) GhostDoc actually does a pretty good job. Often enough the results are not accurate or even downright funny, but on average correcting the mistakes/problems in the generated documentation takes less time than writing the whole comment from scratch.

But how can a tool with virtually no understanding of the English language generate often pretty accurate documentation? Well, the basic idea is pretty simple: GhostDoc assumes that your code follows the Microsoft's Design Guidelines for Class Library Developers:

• you are using PascalCasing or camelCasing to write identifier names consisting of multiple words
• your method names usually start with a verb
• you do not use abbreviations in identifier names
  

If you follow these rules (e.g. write "ClearCache()" instead of "Clrcch()") and choose more or less self-documenting identifier names, there's a good chance for GhostDoc to split the identifier names into words, tweak and/or shuffle them a little and produce a comment that, while not perfect, gives you a head start on the way to good documentation.

The text generation is performed using customizable rules and templates, and in addition to the built-in rules it is possible to define new custom rules that extend or replace existing rules (by giving the custom rules a higher priority and/or disabling built-in rules)

As mentioned above, GhostDoc does not really understand English identifier names, nevertheless it tries to apply certain mechanisms to increase the quality of the generated comments:·

• Handling of verbs (GhostDoc assumes the first word of a method name to be a verb): Add -> Adds , Do -> Does, Specify -> Specifies.
• "Of the" reordering (using trigger words like "width", "height", "name", etc.): ColumnWidth -> Width of the column
• Combined with special handling of specific adjectives: MaximumColumnWidth -> "Maximum width of the column" instead of "Width of the maximum column"
• Automatic detection of acronyms consisting of consonants (Html -> HTML), combined with a list-based approach for other acronyms (Gui -> GUI)
• Use of a list of words where that should not be headed by a "the" (AddItem -> Adds the item, but BuildFromScratch -> Builds from scratch)

As the quality of the comment depends heavily on the quality of the identifier name, using GhostDoc for a longer period of time actually teaches writing consistent and self-documenting identifier names, which is definitely a nice side-effect.

What doesn't GhostDoc do?
GhostDoc cannot perform miracles, and the way it guesses documentation may not work well with your personal style. And GhostDoc is not a tool for creating the complete documentation for a given source file in one go. You can only document one member at a time - which is by design and fully intentional, because you always have to check and, if necessary, correct the results of each text generation.

Summary
GhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from name and type of e.g. methods, properties or parameters.

References
GhostDoc can be downloaded from the GhostDoc website:http://www.roland-weigelt.de/ghostdoc

(This article was taken from the DotNetSlackers website)

What a Tool II

Source Monitor 2
Type: Management
Source: Campwood Software
Download URL: http://www.campwoodsw.com/sourcemonitor.html
Price: free

The freeware program SourceMonitor lets you see inside your software source code to find out how much code you have and to identify the relative complexity of your modules. For example, you can use SourceMonitor to identify the code that is most likely to contain defects and thus warrants formal review. SourceMonitor, written in C++, runs through your code at high speed, typically at least 10,000 lines of code per second. SourceMonitor provides the following:

• Collects metrics in a fast, single pass through source files.
• Measures metrics for source code written in C++, C, C#, VB.NET, Java, Delphi, Visual Basic (VB6) or HTML.
• Includes method and function level metrics for C++, C, C#, VB.NET, Java, and Delphi.
• Saves metrics in checkpoints for comparison during software development projects.
• Displays and prints metrics in tables and charts.
• Operates within a standard Windows GUI or inside your scripts using XML command files. Exports metrics to XML or CSV (comma-separated-value) files for further processing with other tools.
  
  (This article was taken from the Campwood Software website)
  
  

What a Tool!

So, lately I have been interested in learning more about the tools that are out there to help me increase the productivity of our rather small team. After a little searching I stumbled onto http://www.visualstudiogallery.com/ , this was a great source for new and interesting tools to support .NET development. As I Scanned through the offerings I saw there were toys for everyone. I thought that since I had a budget of little or none there would be just about that much offered to me. I was sure wrong about that… There are Code Metrics and Code analysis tools to help me ensure we have as high quality a product as possible, there are documenting tools for the members of the development team, there are even a few toys for the LINQ enthusiasts among us.

I am going to break my evaluation of these tools in to the above suggested 3 categories. First Management, then tools to assist in everyday development, and last things that were just neat toys but not all that useful.

FxCop
Type: Management
Source: Microsoft
Download URL: http://msdn.microsoft.com/en-us/library/bb429476(VS.80).aspx
Price: free

FxCop is actually the utility that started this whole adventure, I recently read about as a sidebar in an article in one of the many .net developer oriented magazines. I did a quick search and found it available from our good friends in Redmond. It holds itself out as a rules based code analysis tool. Out of the box it comes preloaded with rules near and dear to the folks at Microsoft, it included more of their standards than I ever knew existed.

After downloading it and kicking the tires a bit I proceeded to turn it loose on our departments most recently deployed application. In no time it had a few suggestions to offer. By a few I mean 5000, and when I say suggestions, that is what they actually were. The application offered suggestions as to how to bring each warning into compliance. It reported on unused variables, anything that did not meet the .Net guidelines for naming, tense, even using a dictionary to make sure variables had a name that made since.

For my money, this is a great application to ensure that everyone working on the project stays on track, I plan to run it at regular intervals ensuring no other application gets so far out of spec, because in the end, we all want code that is as standardized as possible; it is just easier to support.

Next to be evaluated: Source Monitor 2

What is LINQ

LINQ (Language Integrated Query) is a component released within the .NET 3.5 Framework. It is one of the most powerful features of .NET 3.5. It serves the purpose of querying objects. It is a Microsoft programming model and methodology that essentially adds formal query capabilities into Microsoft .NET-based programming languages. LINQ offers a compact, expressive, and intelligible syntax for manipulating data. The real value of LINQ comes from its ability to apply the same query to an SQL database, a DataSet, an array of objects in memory and to many other types of data as well.
There is no one definition for LINQ, but it aims to solve the problem where we currently use different techniques for manipulating and selecting data from databases versus XML versus object collections; LINQ aims to make our life easier by giving us a coordinated, consistent and efficient syntax from our development environment and by using your one chosen programming language, rather than switching between programming languages.The current LINQ family of technologies and concepts allows an extensible set of operators that work over objects, SQL data and XML data sources. The generalized architecture of the technology also allows the LINQ concepts to be expanded to almost any data domain or technology, so what LINQ is today will expand in the future.

LINQ to SQL
The LINQ to SQL provider is just one part of the overall framework, however, it is a very powerful and attractive option when and ORM (see Object-relational mapping below) is called for. LINQ uses an SQL-like syntax to make query expressions well beyond the capabilities of embedded SQL as implemented in programming languages. That's because embedded SQL uses a simplified, streamlined syntax to add SQL statements to other programming languages, where there's no attempt to integrate such statements into the native syntax and typing mechanisms. Thus, you can't invoke native language structures such as functions in embedded SQL statements, as you can using LINQ, because it is implemented to use native syntax, structures, and typing mechanisms. Furthermore, LINQ may be used to access all kinds of data, whereas embedded SQL is limited to addressing only databases that can handle SQL queries.

In short LINQ to SQL can operate as middle ware between business objects and the database, the advantage of this may seem abstract but consider the following example. In SVT if we want to get just a single standard and do some work on it we first have to create a new object of type standard, next we tell the new object that it’s id is say 21. From here the standard object has been programmed to take that id and go call on other objects from the data namespace, it call a specific one the passes the standard id to a stored procedure which returns a query containing the desired info. Next, that query is returned to the standard object and it essentially, loops over all the columns in the query and populates a property in the new standard object for each one. Now (very simplistically speaking) we have our standard object, it has the methods and properties needed to do work. After we change a few things and tell the object to update the database, the whole process happens again in reverse. If on the other hand we were using LINQ we would simply write a 1 line SQL like expression passing the id of the standard we desired, and it would return a standard object ready to go. We could then edit that object and tell it to update and be done with it.

LINQ to Objects
The LINQ to Objects provider is used for querying in-memory collections, using the local query execution engine of LINQ. The code generated by this provider refer the implementations of the standard query operators as defined in the Sequence class and allows IEnumerable collections to be queried locally.

What this means is that when we want specific information from an array or other type of collection, instead of looping over the entire array, building another array of the desired data, we can simple query the array as if it were a table in a database.

Conclusion
The overall gain in productivity we realized by switching to LINQ is immeasurable, instead of taking all day to get everything needed in the SQLGateway class up and running, our team can do a LINQ query in seconds returning full blown already initialized objects. In an effort to make the implementation as effective as possible I dedicated months of personal research, read many books on the subject, countless articles, and attended several workshops. I felt that to make it all work I needed to become the departmental expert helping the others along as they were ready. As each team member came on board with the new concepts they too became very excited with the prospects and really wish other languages such as Coldfusion had similar features.

Object-relational mapping (aka ORM, O/RM, and O/R mapping) is a programming technique for converting data between incompatible type systems in relational databases and object-oriented programming languages. This creates, in effect, a "virtual object database" which can be used from within the programming language.

Coming out of your Shell Part I

Over my career as a software engineer, I have learned that no matter what the requirements are, most web apps are made up of the same basic components. A few of these components include a site layout, menu system, configuration, user management, a security model and a data model. For some time now I have been interested in developing a “shell” application from which most of my new applications could be derived. This shell application would need to include these “core” components, and would serve as the foundation, from which the rest of the app could be constructed.
I have considered using a portal system such as Xoops (PHP) of .Net Nuke (VB). Both do meet the above described requirements, including user management and providing extensibility points known as modules. Unfortunately, I feel that the core is designed with the needs of the open source community in mind, not those of my clients. Additionally, as it is an “off the shelf” product, I doubt that I would be able to effectively understand the complexity and extend the core as needed.
It is my intention that this open ended series will document my quest to develop “my” very own “shell application”, one that can be adapted and continually enhanced. It will provide both a starting point and eventually I hope an iron clad core for all future web apps.

Some of C# 3.0's new features

C# 3.0 provides many new technologies, recently I became aware of some of the syntax improvements. This post is intended to outline some of the highlights.

Auto Implemented Properties
One new feature in C# 3.0 is “Auto Implemented Properties”, this is a fancy way of saying that we no longer have to create the private property and the public fields when we write new classes. Take a look at the below example:

private string userId;
Public String UserId
{
get { return userId; }
set { userId = value; }
}

IS the same as

public string UserId {get;set;}

The compiler will write out the needed getters and setters, however, they need not be in the source code unless a more complex structure is needed. The net effect is 5 less lines of code per property.

Object initializers
Another new feature is known as “Object Initializers”, this is a means to allow programmers to set values that aren’t part of the constructor at init time. Take a look at the below example:
Customer c = new Customer(“john”,”doe”);
c.phone=”123-456-7890”;
c.zip = “43534”;

is the same as

Customer c = new Customer(“john”,”doe”) {phone=”123-456-7890”,zip=”43534}

This may seem insignifigant, however, it is not. There are many classes I have come in contact with that have properties that aren’t set in the constructor. In these cases you must make additional statements to set the further needed properties. That limitation is now removed, you can now set those properties all at once. This again, it a little compiler trickery, at compile time they are broken out into individual statements just as you would have, but as with the auto implemented properties, this is an improvement in the overall readability, serviceability, and cleanliness of the source code. I a way this reminds me of how you can add items into an array at the time of declaration
string[] x = new string[]{“a”,”b”,”c”};

Local Variable Type Inference
Microsoft has seen the complaints that the following just looks a little odd:
Customer customer = new Customer();
Their answer is called local variable type inference using the var keyword. What this means that the following will now be accepted:
var customer = new Customer();
In this case the compiler detects the type from the new Customer() part of the statement. I cant say this is a whole lot shorter or neater in most case, however, when using linq, the type is not known as types are created on the fly to support the data requested. So it does seem to be useful in the linq arena.

More thoughts as they come in.

LINQ to SQL Overview" video

From TechEd Barcelona,
This presentation from Luca Bolongnesa is heavy on the Italian accent, but also heavy on content. This is probably the best video, podcast, or article I have read to date on Linq to SQL. Luca covers

• how the Linq to SQL engine works, explaining in depth scenarios, and demonstrating the sql that was executed.
• How joins and aggregation are accomplished
• Stored Procedures
• Optimistic Concurrency and Pessimistic Concurrency
• Transactions both distributed and non distributed

System.Collections.Generics - Dictionary

So, I have wanted to dive into the world of generics for some time now. I have read and read about the stack, queue, and the dictionary classes but just didnt have a need until now. recently on project foo, the need to use an "anchor" that would never change and get back the current display text was presented. I considered my options, we could query for each value... No, there would be many many instances of this need on the same page, and though stored procs are fast, I felt that would be clumsy. Then a light came on, use the dictionary object.

I tried to take it a step farther and use a linq query and the todictionary extension method, to create my dictionary, unfortunatly this went nowhere. I was able to write the needed statement for the linq query, but had many problems with the todictionary method. I suspect it is partly because i am new to both generics and linq. I found that there were few good examples of how to use the todictionary method that I could reference, so I ended up doing it the old fashon way, creating a dataset, then creating a dictionary, and finally itterating over the dataset/datatable and adding each record.

LINQ to SQL and Datacontexts

At first I thought LINQ to SQL was going to be as simple as creating a datacontext, adding all tables to it and then linq away. After some work and some research, I have discovered that though that did work a little more thought is required. For one, what happens if the database schema changes, would the datacontext be updated? Second, should I have a global all encompasing datacontext or would there be a performance cost?


Most of the how-to's and chapters in books i have read do not really cover this, they simply explain how to setup a new datacontext and then how to begin "linqing". I did a little research and discovered that the data context does not get updated when you make changes to the database schema.

So what is the right way to do this, what should go where, and when? One article i found on the subject can be found at http://www.west-wind.com/weblog/posts/246222.aspx . This article by Rick Strahl a Microsoft MVP, suggests the a global datacontext be avoided. After reading several articles on the matter I am inclined to go with a datacontext per thread. This relitively easy to implement, and circumvents the issue he discusses with the global data context forcing all users to updates at one time. I still, havent found any discussion as to weather the whole database should be modeled in a single context or if seperate contexts should be created to hold logical groups of tables. Additionally, I have yet to see any real discussion on the issue that happens if the database schema changes.


There is a code camp coming up on 6/7/2007 and I plan to follow the linq track exclusively.

Refractor SQLGateway Class to Linq

Currently the SQLGateway class is the most confusing and difficult file in the entire system to manage. Unfortunately, it is also the one files that every other file must interact with as it is just as the name states, the gateway to the database. I have held off on this for some time as I wanted to make sure I understood as much as I possibly could about what was being done and what could be done instead.
Here are my conclusions:
1. This class was developed with the intention of abstracting the data layer from the business layer. This is a fantastic idea, in that it can provide a means for reusing queries, and provide a central point of change should the system ever need to be ported over to another DBMS such as Oracle. This follows the spirit of what we as programmers have been taught to do, but were never able to accomplish since the very beginning.
2. Though the idea of providing a single point of change should we use another DBMS is here, it would be impossible in practice to actually accomplish the needed changes to 6100 lines of code along with the other supporting classes, interfaces, and stored procs in any reasonable amount of time.
3. This highly overblown abstraction makes it extremely difficult and time consuming to add new features such as new objects/tables or even new fields as there are about 10 places that need to be updated for each,
4. When the system was initially developed there was obviously a decision made that dictated that all forms of CRUD (insert, update, delete, and select) would be implemented for all data objects. I find this to be a security risk, but beyond that it is very unnecessary. Perhaps the SQLGateway class was generated, and not to be edited by hand, it sure seems so.
5. These standards and techniques were developed to support a .net 1.1 application and thus are subject to review as many years have passed and the app is now under .net 3.5
6. .net 3.5 offers a new technology known as linq or language integrated query. This new data access methodology, provides a 1-3 line interface to the database through ORM (object relational mapping). This interface also provides a parameterized approach which is the number 1 reason for using stored procs, as if additional programming is needed ala a stored proc it still offers these as methods od the data object it creates. Behind the scenes linq creates a data class to mode each entity/table in the database, thus providing the abstraction called for in the 3 tier environment.

I plan to use linq instead of and in place of the current data model wherever possible, Since this application is already quite developed, meaning there is already a large system in place, and the team and myself are all a little new to linq, I plan to implement a 4 tier environment. 1 UI layer (already provided), 1 business layer ( already provided), and 2 data layers stacked. The first will be the existing SQLGateway class and its supporting cast. The second data layer will be interacted with through the first. This means all the existing data methods in the SQLGateway class will remain, and will return what they always have, however inside them, as time permits, I will adjust them to use linq instead of the traditional stored proc setup. This change, along with removing unneeded methods to update, insert, and delete system table data will in my calculations reduce the size of the SQLGateway class by 50%, increase productivity among our team, and still offer every bit of the value of the old model.

First Entry

This blog will be a way of documenting and colaborating within the department about what we have and are still learning in the .net world.

As this blog is dedicated to Asp.net I thought I'd start off by mentioning, if you havent already been there you should surf http://www.asp.net/ This is a fantastic site for information, and has great free how-to videos (direct link) http://www.asp.net/learn/. These videos are better than those from learnvisualstudio.net in my opinion.

Happy Learning,

-Lendog