Skip to main content

Record Class

The Record object is a container for holding and transferring a variable number of values. Fields within the record are numerically indexed and can contain strings, integers, streams, and null values. Record fields are indexed starting with 1. Field 0 is a special format field.

Methods

MethodDescription
Clear()Sets all fields in a record to null.
FromHandle(handle, ownsHandle)Creates a new Record object from an integer record handle.
GetDataSize()Gets the length of a record field. The count does not include the terminating null.
GetDataSize(fieldName)Gets the length of a record field. The count does not include the terminating null.
GetInteger(field)Gets a field value as an integer.
GetInteger(fieldName)Gets a field value as an integer.
GetNullableInteger(field)Gets a field value as an integer.
GetNullableInteger(fieldName)Gets a field value as an integer.
GetStream(field, filePath)Reads a record stream field into a file.
GetStream(fieldName, filePath)Reads a record stream field into a file.
GetStream(field)Gets a record stream field.
GetStream(fieldName)Gets a record stream field.
GetString(field)Gets a field value as a string.
GetString(fieldName)Gets a field value as a string.
IsNull(field)Reports whether a record field is null.
IsNull(fieldName)Reports whether a record field is null.
SetInteger(field, value)Sets the value of a field to an integer.
SetInteger(fieldName, value)Sets the value of a field to an integer.
SetStream(field, filePath)Sets a record stream field from a file. Stream data cannot be inserted into temporary fields.
SetStream(fieldName, filePath)Sets a record stream field from a file. Stream data cannot be inserted into temporary fields.
SetStream(field, stream)Sets a record stream field from a Stream object. Stream data cannot be inserted into temporary fields.
SetStream(fieldName, stream)Sets a record stream field from a Stream object. Stream data cannot be inserted into temporary fields.
SetString(field, value)Sets the value of a field to a string.
SetString(fieldName, value)Sets the value of a field to a string.
ToString()Gets a formatted string representation of the Record.
ToString(provider)Gets a formatted string representation of the Record, optionally using a Session to format properties.
ToString(format)Gets a formatted string representation of the Record.
ToString(format, provider)Gets a formatted string representation of the Record, optionally using a Session to format properties.

Properties

PropertyDescription
FieldCountGets the number of fields in a record.
FormatStringGets or sets field 0 of the Record, which is the format string.
ItemGets or sets a record field value.
ItemGets or sets a record field value.

Remarks

Most methods on the Record class have overloads that allow using either a number or a name to designate a field. However note that field names only exist when the Record is directly returned from a query on a database. For other records, attempting to access a field by name will result in an InvalidOperationException.

WixToolset.Dtf.WindowsInstaller.dll version 5.0.1+2f00cbe680fb01ab485d56f16de9cd19b133f875

Clear() Method

Sets all fields in a record to null.

Declaration

public void Clear()

Remarks

Win32 MSI API: MsiRecordClearData

FromHandle(handle, ownsHandle) Method

Creates a new Record object from an integer record handle.

Declaration

public static Record FromHandle(
IntPtr handle,
bool ownsHandle
)

Parameters

ParameterTypeDescription
handleIntPtrInteger record handle
ownsHandlebooltrue to close the handle when this object is disposed or finalized

Remarks

This method is only provided for interop purposes. A Record object should normally be obtained by calling «see M:WixToolset.Dtf.WindowsInstaller.View.Fetch» other methods.The handle will be closed when this object is disposed or finalized.

GetDataSize() Method

Gets the length of a record field. The count does not include the terminating null.

Declaration

public int GetDataSize()

Remarks

The returned data size is 0 if the field is null, non-existent, or an internal object pointer. The method also returns 0 if the handle is not a valid Record handle. If the data is in integer format, the property returns 2 or 4. If the data is in string format, the property returns the character count (not including the NULL terminator). If the data is in stream format, the property returns the byte count. Win32 MSI API: MsiRecordDataSize

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

GetDataSize(fieldName) Method

Gets the length of a record field. The count does not include the terminating null.

Declaration

public int GetDataSize(
string fieldName
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field to check.

Remarks

The returned data size is 0 if the field is null, non-existent, or an internal object pointer. The method also returns 0 if the handle is not a valid Record handle. If the data is in integer format, the property returns 2 or 4. If the data is in string format, the property returns the character count (not including the NULL terminator). If the data is in stream format, the property returns the byte count.

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

GetInteger(field) Method

Gets a field value as an integer.

Declaration

public int GetInteger(
int field
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field to retrieve.

Return value

int Integer value of the field, or 0 if the field is null.

Remarks

Win32 MSI API: MsiRecordGetInteger

See also

  • M:WixToolset.Dtf.WindowsInstaller.Record.GetNullableInteger(System.Int32)

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

GetInteger(fieldName) Method

Gets a field value as an integer.

Declaration

public int GetInteger(
string fieldName
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field to retrieve.

Return value

int Integer value of the field, or 0 if the field is null.

See also

  • M:WixToolset.Dtf.WindowsInstaller.Record.GetNullableInteger(System.String)

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

GetNullableInteger(field) Method

Gets a field value as an integer.

Declaration

public System.Nullable<System.Int32> GetNullableInteger(
int field
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field to retrieve.

Return value

System.Nullable<System.Int32> Integer value of the field, or null if the field is null.

Remarks

Win32 MSI API: MsiRecordGetInteger

See also

  • M:WixToolset.Dtf.WindowsInstaller.Record.GetInteger(System.Int32)

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

GetNullableInteger(fieldName) Method

Gets a field value as an integer.

Declaration

public System.Nullable<System.Int32> GetNullableInteger(
string fieldName
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field to retrieve.

Return value

System.Nullable<System.Int32> Integer value of the field, or null if the field is null.

See also

  • M:WixToolset.Dtf.WindowsInstaller.Record.GetInteger(System.String)

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

GetStream(field, filePath) Method

Reads a record stream field into a file.

Declaration

public void GetStream(
int field,
string filePath
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field of the Record to get.
filePathstringSpecifies the path to the file to contain the stream.

Remarks

This method is capable of directly extracting substorages. To do so, first select both the Name and Data column of the _Storages table, then get the stream of the Data field. However, substorages may only be extracted from a database that is open in read-only mode. Win32 MSI API: MsiRecordReadStream

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.
T:System.NotSupportedExceptionAttempt to extract a storage from a database open
in read-write mode, or from a database without an associated file path

GetStream(fieldName, filePath) Method

Reads a record stream field into a file.

Declaration

public void GetStream(
string fieldName,
string filePath
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field of the Record to get.
filePathstringSpecifies the path to the file to contain the stream.

Remarks

This method is capable of directly extracting substorages. To do so, first select both the Name and Data column of the _Storages table, then get the stream of the Data field. However, substorages may only be extracted from a database that is open in read-only mode.

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.
T:System.NotSupportedExceptionAttempt to extract a storage from a database open
in read-write mode, or from a database without an associated file path

GetStream(field) Method

Gets a record stream field.

Declaration

public System.IO.Stream GetStream(
int field
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field of the Record to get.

Return value

System.IO.Stream A Stream that reads the field data.

Remarks

This method is not capable of reading substorages. To extract a substorage, use «see M:WixToolset.Dtf.WindowsInstaller.Record.GetStream(System.Int32,System.String)» . Win32 MSI API: MsiRecordReadStream

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

GetStream(fieldName) Method

Gets a record stream field.

Declaration

public System.IO.Stream GetStream(
string fieldName
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field of the Record to get.

Return value

System.IO.Stream A Stream that reads the field data.

Remarks

This method is not capable of reading substorages. To extract a substorage, use «see M:WixToolset.Dtf.WindowsInstaller.Record.GetStream(System.String,System.String)» .

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

GetString(field) Method

Gets a field value as a string.

Declaration

public string GetString(
int field
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field to retrieve.

Return value

string String value of the field, or an empty string if the field is null.

Remarks

Win32 MSI API: MsiRecordGetString

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

GetString(fieldName) Method

Gets a field value as a string.

Declaration

public string GetString(
string fieldName
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field to retrieve.

Return value

string String value of the field, or an empty string if the field is null.

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

IsNull(field) Method

Reports whether a record field is null.

Declaration

public bool IsNull(
int field
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field to check.

Return value

bool True if the field is null, false otherwise.

Remarks

Win32 MSI API: MsiRecordIsNull

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

IsNull(fieldName) Method

Reports whether a record field is null.

Declaration

public bool IsNull(
string fieldName
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field to check.

Return value

bool True if the field is null, false otherwise.

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

SetInteger(field, value) Method

Sets the value of a field to an integer.

Declaration

public void SetInteger(
int field,
int value
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field to set.
valueintnew value of the field

Remarks

Win32 MSI API: MsiRecordSetInteger

See also

  • M:WixToolset.Dtf.WindowsInstaller.Record.SetNullableInteger(System.Int32,System.Nullable{System.Int32})

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

SetInteger(fieldName, value) Method

Sets the value of a field to an integer.

Declaration

public void SetInteger(
string fieldName,
int value
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field to set.
valueintnew value of the field

See also

  • M:WixToolset.Dtf.WindowsInstaller.Record.SetNullableInteger(System.String,System.Nullable{System.Int32})

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

SetStream(field, filePath) Method

Sets a record stream field from a file. Stream data cannot be inserted into temporary fields.

Declaration

public void SetStream(
int field,
string filePath
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field of the Record to set.
filePathstringSpecifies the path to the file containing the stream.

Remarks

The contents of the specified file are read into a stream object. The stream persists if the Record is inserted into the Database and the Database is committed. To reset the stream to its beginning you must pass in null for filePath. Do not pass an empty string, "", to reset the stream. Setting a stream with this method is more efficient than setting a field to a FileStream object. Win32 MSI API: MsiRecordsetStream

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

SetStream(fieldName, filePath) Method

Sets a record stream field from a file. Stream data cannot be inserted into temporary fields.

Declaration

public void SetStream(
string fieldName,
string filePath
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field name of the Record to set.
filePathstringSpecifies the path to the file containing the stream.

Remarks

The contents of the specified file are read into a stream object. The stream persists if the Record is inserted into the Database and the Database is committed. To reset the stream to its beginning you must pass in null for filePath. Do not pass an empty string, "", to reset the stream. Setting a stream with this method is more efficient than setting a field to a FileStream object.

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

SetStream(field, stream) Method

Sets a record stream field from a Stream object. Stream data cannot be inserted into temporary fields.

Declaration

public void SetStream(
int field,
System.IO.Stream stream
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field of the Record to set.
streamSystem.IO.StreamSpecifies the stream data.

Remarks

The stream persists if the Record is inserted into the Database and the Database is committed. Win32 MSI API: MsiRecordsetStream

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

SetStream(fieldName, stream) Method

Sets a record stream field from a Stream object. Stream data cannot be inserted into temporary fields.

Declaration

public void SetStream(
string fieldName,
System.IO.Stream stream
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field name of the Record to set.
streamSystem.IO.StreamSpecifies the stream data.

Remarks

The stream persists if the Record is inserted into the Database and the Database is committed.

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

SetString(field, value) Method

Sets the value of a field to a string.

Declaration

public void SetString(
int field,
string value
)

Parameters

ParameterTypeDescription
fieldintSpecifies the field to set.
valuestringnew value of the field

Remarks

Win32 MSI API: MsiRecordSetString

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.

SetString(fieldName, value) Method

Sets the value of a field to a string.

Declaration

public void SetString(
string fieldName,
string value
)

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the field to set.
valuestringnew value of the field

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field name does not match any
of the named fields in the Record.

ToString() Method

Gets a formatted string representation of the Record.

Declaration

public string ToString()

Return value

string A formatted string representation of the Record.

Remarks

If field 0 of the Record is set to a nonempty string, it is used to format the data in the Record. Win32 MSI API: MsiFormatRecord

See also

  • P:WixToolset.Dtf.WindowsInstaller.Record.FormatString
  • M:WixToolset.Dtf.WindowsInstaller.Session.FormatRecord(WixToolset.Dtf.WindowsInstaller.Record)

ToString(provider) Method

Gets a formatted string representation of the Record, optionally using a Session to format properties.

Declaration

public string ToString(
System.IFormatProvider provider
)

Parameters

ParameterTypeDescription
providerSystem.IFormatProvideran optional Session instance that will be used to lookup any properties in the Record's format string

Return value

string A formatted string representation of the Record.

Remarks

If field 0 of the Record is set to a nonempty string, it is used to format the data in the Record. Win32 MSI API: MsiFormatRecord

See also

  • P:WixToolset.Dtf.WindowsInstaller.Record.FormatString
  • M:WixToolset.Dtf.WindowsInstaller.Session.FormatRecord(WixToolset.Dtf.WindowsInstaller.Record)

ToString(format) Method

Gets a formatted string representation of the Record.

Declaration

public string ToString(
string format
)

Parameters

ParameterTypeDescription
formatstringString to be used to format the data in the Record, instead of the Record's format string.

Return value

string A formatted string representation of the Record.

Remarks

Win32 MSI API: MsiFormatRecord

ToString(format, provider) Method

Gets a formatted string representation of the Record, optionally using a Session to format properties.

Declaration

public string ToString(
string format,
System.IFormatProvider provider
)

Parameters

ParameterTypeDescription
formatstringString to be used to format the data in the Record, instead of the Record's format string.
providerSystem.IFormatProvideran optional Session instance that will be used to lookup any properties in the Record's format string

Return value

string A formatted string representation of the Record.

Remarks

Win32 MSI API: MsiFormatRecord

See also

  • P:WixToolset.Dtf.WindowsInstaller.Record.FormatString
  • M:WixToolset.Dtf.WindowsInstaller.Session.FormatRecord(WixToolset.Dtf.WindowsInstaller.Record)

FieldCount Property

Gets the number of fields in a record.

Declaration

public int FieldCount { get; set; } 

Remarks

Win32 MSI API: MsiRecordGetFieldCount

FormatString Property

Gets or sets field 0 of the Record, which is the format string.

Declaration

public string FormatString { get; set; } 

Item Property

Gets or sets a record field value.

Declaration

public System.Object Item[
string fieldName
] { get; set; }

Parameters

ParameterTypeDescription
fieldNamestringSpecifies the name of the field of the Record to get or set.

Remarks

When getting a field, the type of the object returned depends on the type of the Record field. The object will be one of: Int16, Int32, String, Stream, or null. When setting a field, the type of the object provided will be converted to match the View query that returned the record, or if Record was not returned from a view then the type of the object provided will determine the type of the Record field. The object should be one of: Int16, Int32, String, Stream, or null.

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe name does not match any known field of the Record.

Item Property

Gets or sets a record field value.

Declaration

public System.Object Item[
int field
] { get; set; }

Parameters

ParameterTypeDescription
fieldintSpecifies the field of the Record to get or set.

Remarks

Record fields are indexed starting with 1. Field 0 is a special format field. When getting a field, the type of the object returned depends on the type of the Record field. The object will be one of: Int16, Int32, String, Stream, or null. If the Record was returned from a View, the type will match that of the field from the View query. Otherwise, the type will match the type of the last value set for the field. When setting a field, the type of the object provided will be converted to match the View query that returned the Record, or if Record was not returned from a View then the type of the object provided will determine the type of the Record field. The object should be one of: Int16, Int32, String, Stream, or null. The type-specific getters and setters are slightly more efficient than this property, since they don't have to do the extra work to infer the value's type every time. Win32 MSI APIs: MsiRecordGetInteger , MsiRecordGetString , MsiRecordSetInteger , MsiRecordSetString

Exceptions

ExceptionDescription
T:System.ArgumentOutOfRangeExceptionThe field is less than 0 or greater than the
number of fields in the Record.