Enums and Other User Defined Types

The designer knows about most common data types, such as numeric types, strings and dates, and includes support for some database-defined types such as SQL Server 2008 spatial types.  You can also add your own types to the designer.  A particularly common use for this to represent integer columns as .NET enumerations (enums).

To add a type to the designer, open the LightSpeed Model Explorer, right-click the root model node, and choose Add New User-Defined Type.

Adding an Enum Type to the Designer

To add an enum type to the designer, specify the following options for the newly created user‑defined type:

·         Name: The name to be displayed in the Data Type drop-down, e.g. Priority.

·         CLR Type Name: The type name of the enum, as it should be emitted into the generated code.  Typically, this will be the fully-qualified type name, e.g. MyCompany.Shipping.Priority, though you can omit the namespace if the enum is part of the same namespace as the model, or if the namespace is imported through the Imported Namespaces collection.

·         Data Type: Leave this as Int32 for most enum types.  If your enum is backed by a short or long integer type, specify the appropriate backing type.  (This is used only for database synchronisation.  It doesn’t affect the entity definition, or the enum type definition itself.)

·         Is Value Type: Leave this as True for enum types.

·         Is Standard Data Type: Leave this as True for enum types.

·         Converter Type: Leave this blank for enum types.

Adding a Database‑Defined Type to the Designer

The designer already supports some database‑defined types.  If you want to use a type which is defined by your database but not supported by the designer, you can add it as a user‑defined type by specifying the following options:

·         Name: The name to be displayed in the Data Type drop-down, e.g. SqlHierarchyId.

·         CLR Type Name: The .NET type name of the type, as it should be emitted into the generated code.  This is typically defined by the ADO.NET provider, e.g. Microsoft.SqlServer.Types.HierarchyId.  You must fully qualify the name, or add the containing namespace to the Imported Namespaces collection.

·         Is Value Type: Set this to True or False depending on whether the ADO.NET type is a struct or a class.  (This is important if you have nullable instances of the type.)

·         Is Standard Data Type: Set this to False for database-defined types.

·         Database Type Name: Set this to the SQL name of the database‑defined type, e.g. hierarchyid.  This is used for database synchronisation.

·         Converter Type: Leave this blank for types that are defined by the ADO.NET provider.

Adding a User‑Defined Type with Custom Mapping

The third main use case for user‑defined types is when you have a type that has a custom mapping from the database to the CLR.  This can be because the type is a standard one but it is mapped to the database in a non-standard way, such as a Boolean which is mapped to a Y/N string column in the database, or an enum which is stored using its string name instead of its integer value, or it may be because the database column contains data which doesn’t map to a standard type, such as a string column in a legacy database which contains several pieces of data packed together as comma separated values.

You can add such a type as a user‑defined type by specifying the following options:

·         Name: The name to be displayed in the Data Type drop-down, e.g. Money or YesNo.

·         CLR Type Name: The .NET type name of the type, as it should be emitted into the generated code.  This may be a .NET type defined in your code, e.g. MyCompany.Money, or a standard type, e.g. System.Boolean.

·         Is Value Type: Set this to True or False depending on whether the CLR type is a struct or a class.  (This is important if you have nullable instances of the type.)

·         Is Standard Data Type: Leave this as True if the type is stored in the database using a standard designer type such as string or integer.  Set it to False if it uses a non-standard type, such as a database‑defined type or a SQLCLR type.

·         Data Type: If you left Is Standard Data Type as True, set this to the standard type used for storing this type in the database.  In the Yes/No example, this would be String.  This is used for database synchronisation and does not affect the entity definition.

·         Database Type Name: If you set Is Standard Data Type to False, set this to the SQL name of the type in the database.  This is used for database synchronisation and does not affect the entity definition.

·         Converter Type: Set this to the name of the class which converts between the database representation and the CLR type, such as Mindscape.LightSpeed.FieldConverters.YNBooleanFieldConverter.  The class must implement the IFieldConverter interface (see also the FieldConverter class).  See Mapping Database Types to Domain Types in the chapter Working with Legacy Databases for more information.

Custom mappings are primarily intended for existing databases where the data format is already established.  When creating new databases, prefer to use standard LightSpeed conventions, and where it’s appropriate to use a domain type such as Money, consider mapping it using a value object rather than a custom mapping.

Using a User‑Defined Type

Once you have declared a user-defined type, you can use it just like any other type.  It appears in the Data Type drop‑down, and can be entered or shown against the property in the usual way.