Collection Generator Product Tour

Introduction

Blayd Software's Collection Generator is a .Net source code generating component that produces consistent code for type-safe collection classes. A type-safe collection class defines a public interface that only allows objects of a specific type to be added to the collection by callers. The objects returned by a type-safe collection are of the same specific type, therefore callers do not have to cast the references returned by the collection.

Installation Options

Access to the Collection Generator component is provided by two similar but separate user interface components. There is a UI component that installs as an add-in for Visual Studio 2005 and/or Visual Studio 2008, allowing developers to add their generated collection class source code directly into their Visual Studio solution. There is also a standalone UI component, with no Visual Studio dependencies, that allows developers to save their generated collection class source code to a specified disk file. The only visual difference between the two wizard based user interfaces is on the first page: the add-in has a 'Target Project' list from which the developer chooses the Visual Studio project to add the source code to, the standalone UI has a 'Generated Source Code Directory' option from which the developer browses to and selects the folder in which to place the source code.

Collection Generator User Interface

The wizard based Collection Generator user interface captures the values required to generate the source code for a type-safe collection class. The values that may or in some cases must be specified are described in the sections that follow.

.Net Language

In theory the Collection Generator can generate collection class source code for any .Net language that has a code provider (see below), however, some .Net languages do not explicitly support collection classes and cannot therefore be used by the Collection Generator. The developer has the choice of the following .Net language options:

CSharp

The source code for the collection class will be generated in CSharp.

Visual Basic

The source code for the collection class will be generated in Visual Basic.

Other

The source code for the collection class will be generated using the code provider specified by the developer.

When 'Other' is selected the next wizard page requires the developer to select a code provider. The developer can browse the assemblies and namespaces in the current application domain or if required the developer can explicitly load a specific assembly from which to select a code provider. 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', the developer 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.

Collection Class Base Type

To create the .Net source code for a type-safe collection class, the Collection Generator generates a class that extends one of the .Net Framework collection type base classes. The developer has the choice of two base types as follows:

CollectionBase

An abstract base class. By extending this class the Collection Generator creates a custom type-safe collection class that will only allow objects of a specific type to be added to the collection.

NameObjectCollectionBase

An abstract base class. By extending this class the Collection Generator creates a custom type-safe, name/key object pair class that will only allow objects of a specific type to be added to the collection.

Collected Class Name and Namespace

The name or to be more precise the type name of the class that is to be stored in the generated collection has to be specified in the user interface. The developer also has the option of specifying the collected class namespace.

The term 'collected class' refers to the type that will be stored in the generated collection class. 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 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.

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.

Collection Class Name and Namespace

The Collection Generator user interface generates a 'suggested' type name for the collection class 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 UI will generate a suggested collection class name of WidgetCollection. The suggested name can be changed, if required, to any other valid identifier name.

A namespace may also be specified for the collection class. When specified, the source code for the collection class will be generated within the specified namespace.

The developer can also specify whether or not the generated collection class will allow callers to add null entries to the collection. If null entries are not allowed, the generated source code will include code to throw an exception when a caller attempts to add a null entry.

Collection Name or Key Properties

When the selected collection base type is NameObjectCollectionBase the developer can also specify various options for validating the name or key of each collection entry. The options are as follows:

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

By default, the generated collection class source code prevents all of the above and generates code to throw an exception if a caller attempts to add an entry with a duplicate, Empty or null name or key. However, the developer can override the default behaviour by specifying any one or any combination of the above options.

Source Code File Name

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 Generate would generate a source code file named CustomerCollection.cs.

The developer can override the default behaviour by specifying a file name. The Collection Generator user interface displays the source code file extension specified by the code provider as a guide but the developer is free to use whatever name and extension they require.

Synchronized Wrapper and Documentation

A synchronized wrapper class and documentation comments may be generated for the collection class.

If specified, 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.

If specified, the Collection Generator will generate documentation comments for all public and protected members of the collection class. The developer can specify a comment prefix for .Net languages that do not have built in support for documentation comments but do have a third party documenter available. The 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.

Generating the Source Code

When the various properties outline above have been specified in the Collection Generator user interface the source code for the type-safe collection class can be generated.

The source code is always written out to the file that has been specified in the UI or to a file named by the Collection Generator. When the source code is generated using the standalone user interface that is the end of the operation. However, when the source code is generated using the Visual Studio 2005/08 add-in, the source code is written the selected project's directory and then the class is added to the project.

Conclusion

Blayd Software's Collection Generator alleviates the drudgery of repeatedly coding near identical classes for the collections required in a component or application. Of course there is nothing to stop a developer from modifying or adding component specific members to the generated source code if required. Even if modification is required, automating the process of producing the boilerplate code required by nearly all collections will still save time and effort.