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
| Method | Description |
|---|---|
| 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
| Property | Description |
|---|---|
| FieldCount | Gets the number of fields in a record. |
| FormatString | Gets or sets field 0 of the Record, which is the format string. |
| Item | Gets or sets a record field value. |
| Item | Gets 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.0+41e11442b2ca93e444b60213b5ae99dcbab787d8
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
| Parameter | Type | Description |
|---|---|---|
| handle | IntPtr | Integer record handle |
| ownsHandle | bool | true 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies the field of the Record to get. |
| filePath | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The field is less than 0 or greater than the |
| number of fields in the Record. | |
| T:System.NotSupportedException | Attempt 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies the field of the Record to get. |
| filePath | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The field name does not match any |
| of the named fields in the Record. | |
| T:System.NotSupportedException | Attempt 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies the field to retrieve. |
Return value
string String value of the field, or an empty string if the field is null.
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies the field to check. |
Return value
bool True if the field is null, false otherwise.
Remarks
Win32 MSI API: MsiRecordIsNull
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies the field to check. |
Return value
bool True if the field is null, false otherwise.
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies the field to set. |
| value | int | new value of the field |
Remarks
Win32 MSI API: MsiRecordSetInteger
See also
- M:WixToolset.Dtf.WindowsInstaller.Record.SetNullableInteger(System.Int32,System.Nullable{System.Int32})
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies the field to set. |
| value | int | new value of the field |
See also
- M:WixToolset.Dtf.WindowsInstaller.Record.SetNullableInteger(System.String,System.Nullable{System.Int32})
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies the field of the Record to set. |
| filePath | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies the field name of the Record to set. |
| filePath | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies the field of the Record to set. |
| stream | System.IO.Stream | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies the field name of the Record to set. |
| stream | System.IO.Stream | Specifies the stream data. |
Remarks
The stream persists if the Record is inserted into the Database and the Database is committed.
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies the field to set. |
| value | string | new value of the field |
Remarks
Win32 MSI API: MsiRecordSetString
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies the field to set. |
| value | string | new value of the field |
Exceptions
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| provider | System.IFormatProvider | an 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
| Parameter | Type | Description |
|---|---|---|
| format | string | String 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
| Parameter | Type | Description |
|---|---|---|
| format | string | String to be used to format the data in the Record, instead of the Record's format string. |
| provider | System.IFormatProvider | an 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
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The 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
| Parameter | Type | Description |
|---|---|---|
| field | int | Specifies 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
| Exception | Description |
|---|---|
| T:System.ArgumentOutOfRangeException | The field is less than 0 or greater than the |
| number of fields in the Record. |