24.2 Properties Reference

Boolean allowDBNull = DataColumn.AllowDBNull;
DataColumn.AllowDBNull = allowDBNull;

Gets or sets whether null values can be stored in the column.

Example

The following example creates a new DataColumn that doesn't allow null values:

DataColumn col = new DataColumn("MyColumn", typeof(System.String));
col.AllowDBNull = false;

Notes

The schema information to set the AllowDBNull property isn't retrieved from the data source using the Fill( ) method of the DataAdapter. The FillSchema( ) method of the DataAdapter does, however, set the AllowDBNull property based on the data source schema.

The AllowDBNull property is automatically set to false when a column is identified as the primary key or as part of the primary key.

A NoNullAllowedException is raised if an attempt is made to set the column value to null for a column in which the AllowDBNull property is set to false.

The default value for this property is true.

Boolean autoIncrement = DataColumn.AutoIncrement;
DataColumn.AutoIncrement = autoIncrement;

Gets or sets whether the column value automatically increments with each new row added to the table.

Example

The following example shows how to set the AutoIncrement, AutoIncrementSeed, and AutoIncrementStep properties of the DataColumn:

DataColumn col = new DataColumn("MyColumn", typeof(System.Int32));
col.AutoIncrement = true;
col.AutoIncrementSeed = -1;
col.AutoIncrementStep = -1;

Notes

The starting value for an AutoIncrement column in defined by the AutoIncrementSeed property. The subsequent values for the column are determined by the AutoIncrementStep property.

If the column type isn't an integer type (i.e., Int16, Int32, or Int64) and the AutoIncrement property is set to true, the DataType property of the column is coerced to Int32. If the column is computed (i.e., Expression property is set), and an attempt is made to set the AutoIncrement property to true, an exception is raised.

A new row can be created by using the ItemArray property of the DataRow and passing in an array of column values. Pass a null reference for AutoIncrement columns.

This property isn't set by calling either the Fill( ) or FillSchema( ) of the DataAdapter, regardless of the settings in the data source.

The default value of this property is false.

Int64 autoIncrementSeed = DataColumn.AutoIncrementSeed;
DataColumn.AutoIncrementSeed = autoIncrementSeed;

Gets or sets the starting value for a column with its AutoIncrement property set to true.

Example

See the Example in the AutoIncrement property section of this chapter.

Note

The default value for this property is 0.

Int64 autoIncrementStep = DataColumn.AutoIncrementStep;
DataColumn.AutoIncrementStep = autoIncrementStep;

Gets or sets the amount that an AutoIncrement column is incremented each time a row is added to the table.

Example

See the Example in the AutoIncrement property section of this chapter.

Note

The default value of this property is 1.

String caption = DataColumn.Caption;
DataColumn.Caption = caption;

Gets or sets the caption for the column.

Example

The following example sets the caption for the DataColumn.

DataColumn col = new DataColumn("MyColumn", typeof(System.Int32));
col.Caption = "MyColumnCaption";

Notes

This value is used as the default value for the Caption of controls that support its display.

If not explicitly set, the Caption property defaults to the ColumnName value.

MappingType columnMapping = DataColumn.ColumnMapping;
DataColumn.ColumnMapping = columnMapping;

Gets or sets the MappingType for the column.

Example

The following example shows how to set the MappingType for a column so that the data for the column is output as an attribute.

DataColumn col = new DataColumn("MyColumn", typeof(System.String))
col.ColumnMapping = MappingType.Attribute;

Notes

The MappingType determines how the column data is written when it is saved to XML using the WriteXml method of the DataSet. It can be set to one of the MappingType enumeration values described in Table 24-3.

Table 24-3. MappingType enumeration

Value	Description
Attribute	XML attribute
Element	XML element
Hidden	A structure that isn't included in the output
SimpleContent	XmlText node

Using the first record in the Customers table in Northwind as an example, if the ColumnMapping for each column is set to Element, the following XML is produced:

<Customers>
    <CustomerID>ALFKI</CustomerID>
    <CompanyName>Alfreds Futterkiste</CompanyName>

    ...

    <Fax>030-0076545</Fax>
</Customers>

If, on the other hand, the ColumMapping for each column is set to Attribute, the following XML is produced:

<Customers CustomerID=" ALFKI" CompanyName="
    Alfreds Futterkiste" ... Fax="030-0076545" />

The ColumnMapping property must be set explicitly on each column to set it to a value other than the default value.

The default value for ColumnMapping is Element.

String columnName = DataColumn.ColumnName;
DataColumn.ColumnName = columnName;

Gets or sets the name of the column.

Example

The following example shows how to set the name of the column:

DataColumn col = new DataColumn();
col.ColumnName = "MyColumn";

Notes

The value for the ColumnName property can also be set using the DataColumn constructor as shown in this sample:

DataColumn col = new DataColumn("MyColumn");

If the contents of the DataColumn are output as XML, the ColumnName is used as the name element or attribute tag in the XML document.

By default, ColumnName property has no value. If the ColumnName property has not been set when the column is added to the DataColumnCollection of a DataTable, the column name defaults to Column1, Column2, and so on.

Type dataType = DataColumn.DataType;
DataColumn.DataType = dataType;

Gets or sets the data type of the column data as a .NET Framework data type.

Example

The following example demonstrates how to set the data type for a column:

DataColumn col = new DataColumn();
col.DataType = typeof(Int32);

Notes

This DataType property supports the base .NET Framework data types described in Table 24-4.

Table 24-4. NET Framework data types

Data type	Description
Boolean	A Boolean value. Instances of this type have the value true or false.
Byte	An 8-bit unsigned integer with values ranging from 0 to 255.
Char	A Unicode character with values ranging from hexadecimal 0x0000 to 0xFFFF.
DateTime	Represents dates and times with values ranging from January 1, 0001 12:00:00 midnight to December 31, 9999 11:59:50 P.M.
Decimal	A decimal number ranging from -79,228,162,514,264,337,593,543,950,335 through +79,228,162,514,264,337,593,543,950,335. The Decimal value type eliminates rounding errors in large numbers, typical in financial calculations.
Double	A double-precision 64-bit number ranging from -1.79769313486232e308 through +1.79769313486232e308. The Double type can also contain values -0, +0, PositiveInfinity, NegativeInfinity, and Not-a-Number (NaN).
Int16	A 16-bit signed integer with values ranging from -32,768 through +32,767.
Int32	A 32-bit signed integer with values ranging from -2,147,483,648 through +2,147,483,647.
Int64	A 64-bit signed integer with values ranging from -9,223,372,036,854,775,808 through +9,223,372,036,854,775,807.
SByte	An 8-bit signed integer with values ranging from -128 through +127.
Single	A single precision floating-point number with values ranging from -3.402823e38 through +3.402823e38. The Single type can also contain values -0, +0, PositiveInfinity, NegativeInfinity, and Not-a-Number (NaN).
String	An object representing an immutable series of characters.
TimeSpan	A 64-bit time interval measured in ticks.
UInt16	A 16-bit unsigned integer with values ranging from 0 to 65,535.
UInt32	A 32-bit unsigned integer with values ranging from 0 to 4,294,967,295.
UInt64	A 64-bit unsigned integer with values ranging from 0 to 184,467,440,737,095,551,615.

The value for the DataType property can also be set using the DataColumn constructor as shown in this sample:

DataColumn col = new DataColumn("MyColumn", typeof(System.String));

If the AutoIncrement property of the column is set to true, the DataType property must be set to an integer type; an ArgumentException is raised if an attempt is made to set the DataType property to a noninteger data type.

An ArgumentException is raised if the value of the DataType property is changed once there is data in the table.

The default value for this property is String.

Object defaultValue = DataColumn.DefaultValue;
DataColumn.DefaultValue = defaultValue;

Gets or sets the value that is automatically assigned to the column when a new DataRow is created.

Example

The following example shows how to set the default value for a column:

DataColumn col = new DataColumn("MyColumn", typeof(System.String));
col.DefaultValue = "DefaultValue";

Notes

The default value is limited because it can only be set to a static value. There is no facility to, for example, set a DefaultValue that causes the date and time a column is created to be stored in the column.

If an attempt is made to set the DefaultValue to a value that isn't an instance of the data type of the column, an InvalidCastException is raised when a new row is added.

This value cannot be set if the AutoIncrement property is true.

String expression = DataColumn.Expression;
DataColumn.Expression = expression;

Gets or sets an expression that calculates the value of the column.

Example

The following example demonstrates how to create an expression column that returns the calculated ExtendedPrice based on the Quantity and Price columns:

DataColumn col1 = new DataColumn("Quantity", typeof(System.Int32));
DataColumn col2 = new DataColumn("Price", typeof(System.Decimal));

// create a column calculating the extended price
DataColumn col3 = new DataColumn("ExtendedPrice", typeof(System.Decimal));
col3.Expression = "Quantity * Price";

Notes

The value of an expression column is calculated each time the value of the column is requested.

If this property is set to anything other than an empty string, the ReadOnly property is automatically set to true.

Int32 maxLength = DataColumn.MaxLength;
DataColumn.MaxLength = maxLength;

Gets or sets the maximum length in characters for a column with a text data type.

Example

The following example creates a column with a data type of String and sets the maximum length to 50:

DataColumn col = new DataColumn("MyColumn", typeof(System.String));
col.MaxLength = 50;

Notes

This value is ignored for nontext columns.

The value for the MaxLength property can also be set using the DataColumn constructor as shown in this sample:

DataColumn col = new DataColumn("MyColumn", typeof(System.String), 50);

A value of -1, the default, indicates that the text column has no maximum length.

String namespace = DataColumn.Namespace;
DataColumn.Namespace = namespace;

Gets or sets the XML namespace for the XML representation of the data stored in the DataColumn.

Example

The following example sets the Namespace property of the DataColumn:

DataColumn col = new DataColumn();
col.Namespace = "AdoDotNetIan";

Note

The Namespace property scopes the XML attributes and elements when reading and writing the DataColumn using the ReadXml( ), WriteXml( ), ReadXmlSchema( ), and WriteXmlSchema( ) methods of the Dataset the column belongs to.

Int32 ordinal = DataColumn.Ordinal;

Gets the position of the column in the DataColumnCollection of a DataTable.

Example

The following example demonstrates how to determine the position of the column in the table:

int colOrdinal;

DataColumn col = new DataColumn("MyColumn", typeof(System.Int32));
colOrdinal = col.Ordinal;    // colOrdinal=-1 after this statement
DataTable dt = new DataTable("MyTable");
dt.Columns.Add(col);
colOrdinal = col.Ordinal;    // colOrdinal=0 after this statement

Note

The Ordinal property is zero-based and returns -1 if the column doesn't belong to a table.

String prefix = DataColumn.Prefix;
DataColumn.Prefix = prefix;

Gets or sets the XML prefix that aliases the namespace of the DataColumn.

Example

The following example sets the Prefix property of the DataColumn:

DataColumn col = new DataColumn();
col.Prefix = "adni";

Note

The Prefix is used within the XML document to identify attributes and elements that belong to the namespace of the DataColumn object defined by the Namespace property.

Boolean readOnly = DataColumn.ReadOnly;DataColumn.ReadOnly = readOnly;
DataColumn.ReadOnly = readOnly;

Gets or sets a value indicating whether the data in the column can be changed once the DataRow containing the column is added to a DataTable.

Example

The following example creates a column and makes it read-only:

DataColumn col = new DataColumn("MyColumn");
col.ReadOnly = true;

Note

The default value of this property is false.

DataTable table = DataColumn.Table;

Gets the DataTable to which the DataColumn belongs.

Example

The following example shows how to retrieve a reference to the DataTable object the DataColumn belongs to:

DataColumn col = new DataColumn();

// ... code to define the DataColumn col add it to the DataTable

DataTable dt = col.Table;

Note

This property returns a null reference if the DataColumn has not been assigned to a DataTable.

Boolean unique = DataColumn.Unique;DataColumn.Unique = unique;
DataColumn.Unique = unique;

Gets or sets a value indicating whether the column value for each row in the column must be unique.

Example

The following example creates a column and makes it unique:

DataColumn col = new DataColumn("MyColumn", typeof(System.Int32));
col.Unique = true;

Notes

Setting this property to true creates a unique constraint on the column.

The Fill( ) method of the DataAdapter doesn't set this value based on the underlying data source schema; the FillSchema( ) method of the DataAdapter does.

The default value of this property is false.