Retrieving Field Values

This section explains the basics of retrieving field values ​​for a model.

note

When retrieving or setting field values, the necessary model files are automatically loaded before processing continues. Therefore, execution time may be longer than before. However, model files with manually loaded settings will not be loaded even if field values ​​are referenced (value fields will return their default values, and changes will result in an error). For details, please refer to Changes in V5.1 and Behavior of Model Files with Manual Load Settings.

Metamodel Definition and Field Value Types

In Next Design, models are stored using C# language data types that correspond to the field types defined in the metamodel. The relationship between field types and the C# language data types exposed by the API is as follows:

Field Type	C# Language Data Type
String	string
Integer	int
Double	double
Boolean	bool
Enum Type	IEnumLiteral
Rich Text Type	*1
Class Type (Single)	IModel
Class Type (Multiple)	IModelCollection

*1

Rich text types are stored in a special data format that holds multiple texts for each format (text|html|xaml). This data format is not exposed by the API. Most field value retrieval APIs handle unformatted plain text as string type. For handling rich text field values ​​with formatting, see Working with Rich Text Fields.

The API exposes several methods in the IModel interface to retrieve field values ​​from a model.

Method	Description
GetField, GetFieldAt	Can be used when you want to retrieve values ​​in the C# language data type exposed by the API. See here for details.
GetFieldString, GetFieldStringAt	Can be used when you want to always retrieve values ​​as strings, regardless of the field type. See here for details.
GetFieldValues	Can be used when you want to retrieve a model collection of multiple class-type field types. See here for details.
GetRichTextField	Can be used when you want to retrieve rich text field values ​​with a specified format. See here for details.

Obtaining as object type

To obtain a field value as an object type, use the GetField method of the IModel object. The actual object type obtained will vary depending on the type of the metamodel field, so you will need to cast it. The relationship between the field type and the C# type is as follows:

Field Type	C# type that can cast object
String	string
Integer	int
Double	double
Boolean	bool
Enum Type	IEnumLiteral
Rich Text Type	string *2
Class Type (Single)	IModel
Class Type (Multiple)	IModel *3

*2

When the GetField method is called on a rich text type field, it obtains plain text without formatting as a string type.

*3

When the GetField method is called on a class type field with a multiplicity of 2 or more, the first model of that field is retrieved. To retrieve a model other than the first one, specify an index based on 0 with the GetFieldAt method, or use the GetFieldValues method to retrieve a collection of models.

public void GetField(ICommandContext c, ICommandParams p)
{
    IModel model = c.App.Workspace.CurrentModel;

    // For a field named "SomeField"
    object someFieldValue = model.GetField("SomeField");

    // ...
}

Retrieving as a String

Field values ​​can be retrieved as strings regardless of the field type. To retrieve as a string, use the GetFieldString method of the IModel object. The relationship between the field type and the retrieved string is as follows:

Field Type	Retrieved String
String	String representation of the field value
Integer	String representation of the field value (integer)
Double	String representation of the field value (real number). Depending on the real number value, it may be expressed in exponential notation.
Boolean	"True" or "False"
Enum Type	Name of the enumeration literal
Rich Text Type	Plain text without formatting
Class Type (Singular)	Name of the model
Class Type (Multiple)	Name of the models *4

*4

When the GetField method is called on a class type field with a multiplicity of 2 or more, the model name of the first entry in the field is retrieved. To retrieve a model other than the first entry, specify an index based on 0 using the GetFieldStringAt method.

public void GetFieldString(ICommandContext c, ICommandParams p)
{
    IModel model = c.App.Workspace.CurrentModel;
    string someFieldValue = model.GetFieldString("SomeField");

    // ...
}

Obtaining Enumeration Literal Values

In NextDesign, enumeration field values ​​are stored as enumeration literal types (IEnumLiteral).

Enumeration literal values ​​can be obtained as object type using the GetField method of the IModel object, then cast to the enumeration literal type (IEnumLiteral), and finally retrieved using the Name property of the IEnumLiteral object.

public void GetField(ICommandContext c, ICommandParams p)
{
    IModel model = c.App.Workspace.CurrentModel;
    IEnumLiteral someFieldValue = model.GetField("SomeField") as IEnumLiteral;

    if (someFieldValue == null)
    {
        c.App.Window.UI.ShowMessageBox("Not an enumeration field value.");
        return;
    }
    c.App.Window.UI.ShowMessageBox($"Literal for SomeField: {someFieldValue.Name}");

    // ...
}

note

You can also directly obtain literal values ​​using the GetFieldString method of the IModel object.

Obtaining Boolean Values

To obtain boolean values, first obtain them as object type using the GetField method of the IModel object, and then cast them to a boolean type.

public void GetField(ICommandContext c, ICommandParams p)
{ 
    IModel model = c.App.Workspace.CurrentModel;
    bool? someFieldValue = model.GetField("SomeField") as bool?;
    if (!someFieldValue.HasValue)
    {
        c.App.Window.UI.ShowMessageBox("This is not a boolean field value.");
    }

    //...
}

public void GetField(ICommandContext c, ICommandParams p)
{
    IModel model = c.App.Workspace.CurrentModel;

    //If the field name is "Actor"
    IModel actor = model.GetField("Actor") as IModel;

    if (actor == null)
    {
        c.App.Window.UI.ShowMessageBox("This is not a class type field value.");
    }

    //...
}

If the field type is a class type (the maximum multiplicity is not 1), you can obtain the model at any position by specifying an index based on 0 using the GetFieldAt method of the IModel object. Since the GetFieldAt method returns a value of type object, you cast it to type IModel. The number of field values ​​can be found using the Count method of the IModel object.

public void GetFieldAt(ICommandContext c, ICommandParams p)
{
    IModel model = c.App.Workspace.CurrentModel;

    // If the field name is "Usecases"
    var count = model.Count("Usecases");
    if (count > 0)
    {
        // Get the last model of the field
        // The index is 0 - based
        var index = count - 1;
        IModel usecase = model.GetFieldAt("Usecases", index) as IModel;
    }
}

note

The Count method does not load the model file. Value fields of unloaded models will always return 0. The number of reference fields to other models can be correctly obtained even before loading in model files with automatic loading settings, but will be 0 in model files with manual loading settings. For details, please refer to Changes in V5.1.

Retrieving a Collection of Models

If the field type is of multiple class types (with a multiplicity limit of more than 1), you can retrieve a collection of models using the GetFieldValues method of the IModel object.

public void GetField(ICommandContext c, ICommandParams p)
{
    IModel model = c.App.Workspace.CurrentModel;

    // If the field "SubComponents" is a collection of models
    IModelCollection subComponents = model.GetFieldValues("SubComponents");

    //subComponent will be of type IModel
    foreach (var subComponent in subComponents)
    {
        var someFieldValue = subComponent.GetFieldString("SomeField");
        //...
    }
}