Collection Generator Tutorial

Contents

Introduction

Blayd Software's Collection Generator component generates .Net source code for type-safe collection classes. By automating the process of creating collection class source code you will no longer have to repeatedly type boilerplate code or copy and paste existing class code and then do a search and replace to change the collected class type name. The Collection Generator enables you to produce consistent collection class source code in seconds with the easy to use Collection Generator wizard based user interface.

This tutorial describes each of the Collection Generator wizard pages and explains the choices, selections and entries that are available and then describes the effect these options will have on the generated source code. To follow the article you will need to have a copy of the Collection Generator component installed. If you do not already have a copy of the Collection Generator you can download an evaluation version from www.blayd.co.uk. However, you should note that some of the features described in this article are not available in the evaluation version.

Collection Generator User Interface

When installing the Collection Generator component you have a choice of wizard based user interfaces, you can install the wizard that is launched from a Visual Studio 2005 or Visual Studio 2008 add-in and/or you can install the standalone wizard.

Visually the only difference between the two wizards is on the first page. The add-in launched wizard requires you to select the project to add the generated collection class to. The standalone wizard requires you to select the directory in which to save the generated collection class source code.

Functionally the only difference between the two wizards is that the add-in launched wizard will save the generated source code to the target project's directory and then add the collection class to the target project. The standalone wizard will save the generated source code to the specified directory using either an automatically generated file name or a specified file name.

Launching the Add-in Wizard

Start Visual Studio 2005/08 and load the project or solution that you want to add the generated collection class to. You first have to load the add-in into the Visual Studio 2005/ development environment as follows:

  • From the Tools menu select the Add-in Manager option.
  • Locate the Blayd Collection Generator Add-in in the list of available add-ins. If it is not there, see the note below.
  • Check the box in the Available Add-ins column and then click OK. If you want the add-in to load each time that you start Visual Studio 2005/08, you can also check the box in the Startup column.

Note.

By default the Blayd Collection Generator Add-in should be available in the Add-in Manager's list of add-ins. However, if it does not appear, you will need to configure Visual Studio 2005/08 so that it can find it. Proceed as follows:

  • From the Tools menu select Options
  • In the options dialog, expand the Environment node
  • Select the Add-in/Macros Security node

  • In the Add-in File Paths list there should be an entry as follows:

    %APPDATA%\Microsoft\MSEnvShared\Addins

    If it is not there, you will need to add it by clicking the Add button and browsing to the relevant folder. The %APPDATA% variable will typically transalate to the following directory:

    Windows XP

    C:\Documents and Settings\<user name>\Application Data

    Windows Vista

    C:\Users\<user name>\AppData\Roaming

Once the add-in has been loaded into the Visual Studio 2005/08 development environment you can launch the Collection Generator wizard from the Tools menu Collection Generator option.

Note.

To use the add-in with Visual Studio 2008 you will have to modify the add-in registration file located as detailed above and named as follows:

%APPDATA%\Microsoft\MSEnvShared\Addins\BlaydCollectionGenerator.Addin

If you intend only to use the add-in with Visual Studio 2008, proceed as follows:

  • Open the BlaydCollectionGenerator.Addin file in a text editor.
  • Locate the HostApplication element with a Name value of Microsoft Visual Studio
  • Within the HostApplication element, change the value of the Version element from 8.0 to 9.0

If you intend to use the add-in with both Visual Studio 2005 and Visual Studio 2008, proceed as follows:

  • Open the BlaydCollectionGenerator.Addin file in a text editor.
  • Under the existing, version 8.0, HostApplication element add a new element as follows: 
    <HostApplication>
   <Name>Microsoft Visual Studio</Name>
   <Version>9.0</Version>
</HostApplication>

You should now have two HostApplication elements, one that registers Visual Studio 2005 (version 8.0) and one that registers Visual Studio 2008 (version 9.0).

Launching the Standalone Wizard

From the Start menu navigate to the following shortcut:

Programs - Blayd Software - Collection Generator 2 - Standalone Wizard - Collection Generator Wizard

Wizard Pages

For the rest of this article we are going to discuss the options, selections or entries that are required for each wizard page. We will include all of the possible pages that may be displayed by the wizard and indicate those pages which are optional and depend on a selection that you have made in a previous page. We will also indicate which options, selections or entries on each page are optional and which are mandatory and where appropriate we will explain what effect your selection or entry will have on the generated source code. To proceed through the wizard you should click the Next button and where appropriate you can go back to check or change a previous page by clicking the Back button.

Wizard Page One (add-in). Target Project

When launched from the Visual Studio 2005/08 add-in the opening page of the Collection Generator wizard has a Target Project list that contains the name of all the projects in the current solution. You need to select the project that the generated collection class is to be added to. When you select a project the wizard will select the relevant .Net Language in the Source Code Generator Language list. You can, if you wish, override the wizard's selection and specify a language that is different from the target project's language. The source code file generated by the Collection Generator will be placed in the target project's directory. You must select a target project.

Wizard Page One (standalone). Source Code Path

The standalone Collection Generator wizard's opening page has a Generated Source Code Directory control that is used to specify the directory in which to place the generated collection class source code file. Click the browse button, to the right of the control and browse to the required folder. You must specify a source code directory.

Wizard Page One (both wizards). .Net Language

When launched from the Visual Studio 2005/08 add-in, the wizard will select the appropriate .Net language for the target project, however, when using the standalone wizard you have to select the required language yourself.

There are three options available in the Source Code Generator Language list as follows:

CSharp
When this option is selected the Collection Generator will create the collection class in CSharp.
Visual Basic
When this option is selected the Collection Generator will create the collection class in Visual Basic.
Other
When this option is selected you have to provide the fully qualified name of the required code provider class, see the .Net Language Code Provider section below.

You must select a .Net language option.

Wizard Page Two (optional). .Net Language Code Provider

This is an optional page and will only be displayed when the selected .Net Language, on page one, is Other.

A .Net language code provide is represented by a class that derives from the framework's System.CodeDom.Complier.CodeDomProvider abstract base class. Therefore, when selecting Other, you must specify a code provider class that is derived from the System.CodeDom.Complier.CodeDomProvider class. The specified class will then be used to generate the collection class source code.

To select a code provider click the browse button to the right of the Fully Qualified Name of Code Provider control to display the Type Selector dialog. On loading, the Type Selector dialog will display any System.CodeDom.Complier.CodeDomProvider derived classes contained in the assemblies in the current application domain. If the class you require is included, select it's node and click OK. If the class you require is not included, click the Load Assembly button and browse to the assembly that contains the required System.CodeDom.Complier.CodeDomProvider derived class and then click Open to load the assembly into the Type Selector dialog. Locate the required code provider class node from the assembly that has just be loaded and then click OK.

When you select Other on page one of the wizard you must specify the fully qualified name of a code provider class on page two.

Note.

Not all .Net languages explicitly support collection classes. If your chosen code provider does not support the creation of collection classes an exception will be thrown when the Collection Generator tries to generate the source code.

Wizard Page Three. Collection Class Base Type

The collection class generated by the Collection Generator extends one of the framework's collection class abstract base types. You (currently) have a choice of two base types as follows:

CollectionBase
This type is extended to provide a type-safe collection that will only allow objects of the specified type to be added to the collection. Items in the collection are accessed by index.
NameObjectCollectionBase
This type is extended to provide a type-safe name object pair collection that will only allow objects of the specified type to be added to the collection. Items in the collection can be accessed either by name or key or by index.

Both types have enumerators and therefore support the foreach statement (For Each in Visual Basic).

The CollectionBase type is suitable for situations where the objects stored in the collection are to be accessed sequentially or where the ordinal position or index of the collected object is known or can be calculated or derived.

The NameObjectCollectionBase type is suitable for situations where the objects stored in the collection are to be accessed in a non-linear way using a name or key that is associated with the object. Collected objects can also be accessed sequentially using their ordinal position or index within the collection.

You must select a collection class base type.

Wizard Page Four. Collected Class

The term 'collected class' refers to the type that is to be stored in the collection. For example, you may generate a collection class named CustomerCollection that is intended to contain instances of the Customer class. In this example the collected class is Customer.

You must enter a value in the Collected Class Name control. The value should be the type name of the class that is to be stored in the collection. You may use built in or simple types as the collected class, for example you can specify String as the collected class name to generate a custom string collection class. You may also specify value types such as Int32 as the collected class, however, because value types require boxing when adding to the collection and unboxing when removing from the collection, storing them in a standard collection is not very efficient. The .Net Framework's generic list and collection types provide a more efficient way to store these types.

The Collected Class Namespace value is optional. If the specified collected class and the collection class are in different namespaces, specifying the collected class namespace will instruct the Collection Generator to output a using, Imports, etc. namespace statement in the generated collection class source code.

You must enter a value for the collected class name.

The collected class namespace value is optional, therefore you do not have to enter a value.

Wizard Page Five. Collection Class

When you navigate to this page, using the Next button, for the first time, the wizard will generate a 'suggested' collection class name by appending 'Collection' to the value specified as the collected class name. For example if Widget has been specified as the collected class name, the wizard will generate a suggested collection class name of WidgetCollection. The suggested name can be changed, if required, to any other valid identifier name.

You must enter a value in the Collection Class Name control or accept the suggested value. The value of this control will be used as the type name for the generated collection class.

The Collection Class Namespace value is optional. When specified, the source code for the collection class will be generated within the specified namespace.

The Collection Allows Null Entries check box is optional. By default the generated collection class source code will not allow null entries. The source code will include code to throw an exception if a caller attempts to add a null entry. The default behaviour can be overridden by checking the Allows Null Entries box to allow callers to add null entries to the collection.

You must enter a value for the collection class name.

The collection class namespace value is optional, therefore you do not have to enter a value.

The allow null entries value is optional, therefore you do not have to check the box.

Wizard Page Six (optional). Collection Entry Name or Key Properties

This is an optional page and will only be displayed when the selected collection class base type on page three is NameObjectCollectionBase.

The check boxes on this page specify how the generated collection class is to validate the name or key associated with a collection entry. The available options are as follows:

  • Collection allows entries with duplicate names.
  • Collection allows entries with Empty names.
  • Collection allows entries with null names.

These check boxes are all optional. By default the generated collection class source code will not allow callers to specify a duplicate, Empty or null name or key when adding an entry to the collection i.e. the boxes are not checked. The source code will include code to throw an exception if a caller attempts to add an entry with a duplicate, Empty or null name or key. The default behaviour can be overridden by checking one, all or any combination of the above boxes.

All of the values on this page are optional, therefore you do not have to check any of the boxes.

Wizard Page Seven. Source Code File

By default the Collection Generator generates a source code file name from the value of the collection class name and the file extension specified by the code provider. For example if the collection class name is specified as CustomerCollection and the selected .Net language is CSharp the Collection Generator will generate a source code file named CustomerCollection.cs.

The Source Code File value is optional. You can override the default behaviour, of generating a file name, by entering a source code file name. The default extension for the selected code provider is displayed as a guide, however you can use whatever name and extension you want.

The source code file value is optional, therefore you do not have to enter a value.

Wizard Page Eight. Synchronized Wrapper and Documentation

The Collection Generator can be instructed to generate a synchronized wrapper class for the generated collection class and/or to generate documentation comments for the protected and public members of the generated collection class.

The Generate Nested Synchronized Wrapper Class value is optional. When checked the Collection Generator will generate a Synchronized method in the collection class source code and a nested wrapper class to provide callers with thread-safe access to the collection.

The Generate Documentation Comments value is optional. When checked the Collection Generator will generate documentation comments for all protected and public members of the collection class. Documentation comments are extracted, during the build process, to an XML file. This file can then be redistributed with your component to be used by the intellisense system in Visual Studio and/or used to generate a Help file.

The Documentation Comment Prefix value is optional. This control is only enabled if the selected code provider does not have built in support for documentation comments. At the moment only CSharp and Visual Basic are recognised as supporting documentation comments, therefore this control will only be enabled if the selected .Net language on page one is Other.

The generated documentation is, out of necessity, generic in nature but should be adequate in a lot of situations or alternatively the comments can be easily modified or extended.

The generate nested synchronized wrapper class value it optional, therefore you do not have to check the box.

The generate documentation comments value is optional, therefore you do not have to check the box.

The documentation comment prefix value is optional, therefore you do not have to enter a value.

Wizard Page Nine. Generate Type Safe Collection

The wizard now has all the data it requires to initialize the Collection Generator component. Click the Generate button to create the source code for the collection class.

The process of generating the source code for the collection class is the same no matter how the wizard was launched, however what happens after the source code has been created depends on how the wizard was launched. The process is as follows:

Add-in launched wizard
The source code is written to a file in the target project's directory. The name of the file is either generated by the Collection Generator or if a value was specified on page seven that value is used. When the source code file has been created the collection class is added to the target Visual Studio 2005/08 project.
Standalone wizard
The source code is written to a file in the directory specified on page one. The name of the file is either generated by the Collection Generator or if a value was specified on page seven that value is used.

Wizard Page Ten. Completion Page

The final wizard page is displayed automatically by the wizard when the source code generation process is complete. The page displays the full path of the generated source code file. Click the Close button to exit the wizard.

Conclusion

The Collection Generator wizard has context sensitive help for each wizard page, just click the Help button to get information relating to the current wizard page.

At ten pages the wizard may, when reading through this article, seem daunting, however, some of the pages are optional and are only displayed in response to specific selections, a lot of the pages contain some optional entries, other pages contain entirely optional entries. Therefore, in most cases the wizard can be clicked through very quickly, certainly in far less time than it would take to hand code a comparable collection class.

Copyright ©Blayd Software Limited 2007-2010. All rights reserved.