The numeric value uniquely identifies the selected choice across all languages. The formatted text (or label), on the other hand, is displayed to the user and is localized based on their language settings in Dynamics 365.
With xrm-ex, optionset fields can be set by directly assigning the property names as text or by using properties defined in the model. These model-defined properties function like enums, offering clear, readable code and providing IntelliSense support in the IDE for quick access to available options.
Setting Optionset Values by Property Name
When setting an optionset field by text, xrm-ex matches the provided text with the property name defined in the model. This means your optionset model must define each choice with a property name, allowing you to set the value by name instead of needing the numeric value or actual label from Dynamics 365.
fields.PreferredContactMethod.Value = "Phone"; // Sets the choice to "Phone", matched by property name
In this case, "Phone" refers to the Phone property in the model for PreferredContactMethod.
Setting Optionset Values Using Enum-Like Properties
Using properties defined in the model provides the additional benefit of IntelliSense suggestions in your IDE. As you type fields.PreferredContactMethod.Option., IntelliSense will suggest available properties such as Any, Email, Phone, making it easy to select the correct property without guessing or referencing documentation.
Using a Switch Statement with Optionset (Choice) Fields
With xrm-ex, you can also use a switch statement to handle different optionset values. This is particularly helpful when you want to execute specific logic based on the selected option. By using the enum-like properties defined in your model, you avoid hard-coding literal values and instead rely on readable property names, which enhances code clarity.
Example: Handling Different Contact Methods with a Switch Statement
switch (fields.PreferredContactMethod.Value) {
case fields.PreferredContactMethod.Option.Email:
// Execute logic for "Email" contact method
break;
case fields.PreferredContactMethod.Option.Phone:
// Execute logic for "Phone" contact method
break;
}
In this example:
- Each
case uses the enum-like properties (e.g., fields.PreferredContactMethod.Option.Email), rather than literal values. This makes it immediately clear which choice each case corresponds to.
- Using property names provides IntelliSense support, which helps you avoid errors and increases development efficiency.
Defining Enum-Like Options in a Model
To enable IntelliSense and make setting values simpler, define optionset choices in a model as shown below:
class Fields {
PreferredContactMethod = new XrmEx.Class.OptionsetField(
"preferredcontactmethodcode",
{
Any: 1,
Email: 2,
Phone: 3,
Fax: 4,
Mail: 5,
}
);
}
fields = new Fields(); //exeute during OnLoad event
This setup means you can access fields.PreferredContactMethod.Option.Email and see available options suggested by IntelliSense, improving development speed and accuracy.
Clearing Optionset (Choice) Fields
To clear an optionset field, set its value to null. This removes any current selection, resetting the field to an unselected state.
fields.PreferredContactMethod.Value = null; // Clears the optionset field
This is useful when you need to reset a field or allow users to make a new choice without retaining the previous selection.
Summary of Key Points
- Retrieving Values: Use
.Value for the numeric representation or getText() for the text label.
- Setting Values: Set optionsets by assigning the text label directly (matched with the property name in the model) or by using enum-like properties defined in the model for consistency and IntelliSense support.
- Switch-Case Logic: Use a switch statement with enum-like properties (e.g.,
fields.PreferredContactMethod.Option.Email) to execute specific logic for each choice without hard-coding literal values.
- Clearing Optionsets: Set an optionset field’s
Value to null to clear the current selection.
- Using Models: Define optionset fields in a model to reference options consistently.
