---
title: "IceGrid Property Set Semantics"
url: https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-property-set-semantics
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# IceGrid Property Set Semantics

Ice servers and clients are configured with [properties](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration.md). For servers [deployed](https://docs.zeroc.com/ice/3.8/services/icegrid/using-icegrid-deployment.md) with IceGrid, these properties are automatically generated into a configuration file from the information contained in the application descriptor. The settings in that configuration file are passed to the server via the [--Ice.Config](https://docs.zeroc.com/ice/3.8/property-reference/ice-properties.md#ice.config) command-line option.

[Property descriptors](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/properties-descriptor-element.md) allow you to define property sets to efficiently manage and specify properties. Here are some of the benefits of using property sets:

- You can define sets of properties at the [application](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/application-descriptor-element.md) or [node](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/node-descriptor-element.md) element level and reference these properties in other property sets.
- You can specify properties for a specific [server](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/server-instance-descriptor-element.md) or [service](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/service-instance-descriptor-element.md) instance.

## Defining and Referencing Property Sets

There are two kinds of property sets:

- Named property sets are defined at the application or node level. A named property set has no effect unless another property set references it.
- Unnamed property sets are defined in a [server](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/server-descriptor-element.md), [service](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/service-descriptor-element.md), [icebox](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/icebox-descriptor-element.md), [server-instance](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/server-instance-descriptor-element.md) or [service-instance](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/service-instance-descriptor-element.md) element and define the properties of that server or service. Unnamed property sets can reference named property sets.

Named and unnamed property sets are defined with the same [properties](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/properties-descriptor-element.md) descriptor. The context and the attributes of a `properties` element distinguish named property sets from unnamed property sets. Here is an example that defines a named and an unnamed property set:

```xml
<application name="App">
    <properties id="Debug">
        <property name="UseDebug" value="1"/>
    </properties>

    <node name="TheNode">
        <server id="TheServer" exe="./server">
            <properties>
                <property name="Identity" value="hello"/>
            </properties>
        </server>
    </node>
</application>
```

In this example, we define the named property set `Debug` and the unnamed property set of the server `TheServer`. The server configuration will contain only the `Identity` property because the server property set does not reference the `Debug` named property set.

The `properties` element is used to reference a named property set: if a `properties` element appears inside another `properties` element, it is a reference to another property set and it must specify the `refid` attribute. With the previous example, to reference the `Debug` property set, we would write the following:

```xml
<application name="App">
    <properties id="Debug">
        <property name="UseDebug" value="1"/>
    </properties>

    <node name="TheNode">
        <server id="TheServer" exe="./server">
            <properties>
                <properties refid="Debug"/>
                <property name="Identity" value="hello"/>
            </properties>
        </server>
    </node>
</application>
```

## Override Order

Property sets, whether named or unnamed, are evaluated as follows:

1. Within a `properties` element, IceGrid locates all references to named property sets and evaluates all property settings in the referenced property sets.
2. Explicit property definitions following any named references are then evaluated and added to the property set formed in the preceding step. This means that explicit property settings override corresponding settings in any referenced property sets.

It is illegal to define a reference to a property set after setting a property value, so references to property sets must precede property definitions. For example, the following is illegal:

```xml
<properties>
    <property name="Prop1" value="Value1"/>
    <properties refid="Ref1"/>
</properties>
```

Just as the order of the property definitions is important, the order of property set references is also important. For example, the following two property sets are not equivalent:

```xml
<properties>
    <properties refid="Ref1"/>
    <properties refid="Ref2"/>
</properties>

<properties>
    <properties refid="Ref2"/>
    <properties refid="Ref1"/>
</properties>
```

If `Ref1` sets `Prop` to `1` and `Ref2` sets `Prop` to `2`, the first property set yields `Prop=2` and the second yields `Prop=1`: the property set referenced last wins.

## Variable Scope

Named property sets are evaluated at the point of definition. If you reference other property sets or use variables in a named property set definition, you must make sure that the referenced property sets or variables are defined in the same scope. For example, the following is correct:

```xml
<application name="App">

    <variable name="level" value="1"/>

    <properties id="DebugApp">
        <property name="DebugLevel" value="${level}"/>
    </properties>

</application>
```

However, the following example is wrong because the `${level}` variable is not defined at the `application` scope:

```xml
<application name="App">

    <properties id="DebugApp">
        <property name="DebugLevel" value="${level}"/>
    </properties>

    <node name="TheNode">
        <variable name="level" value="1"/>
    </node>

</application>
```

If both the `application` and the `node` define the `${level}` variable, the value of the `${level}` variable in the `DebugApp` property set will be the value of the variable defined in the application descriptor.

## Customizing a Template Instance

You can also define an unnamed property set for server or service instances. This is a good way to specify or override properties specific to a server or service instance. For example:

```xml
<application name="TheApp">
  <server-template id="Template">

    <parameter name="instance-name"/>

    <server id="${instance-name}" exe="./server">
      <properties>
        <property name="Timeout" value="30"/>
      </properties>
    </server>
  </server-template>

  <node name="TheNode">
    <server-instance template="Template" instance-name="MyInst">
      <properties>
        <property name="Debug" value="1"/>
        <property name="Timeout" value="-1"/>
      </properties>
    </server-instance>
  </node>
</application>
```

Here, the server instance overrides the `Timeout` property and defines an additional `Debug` property.

The server or service instance properties are evaluated as follows:

1. The unnamed property set from the template server or service descriptor is evaluated.
2. The unnamed property set from the server or service instance descriptor is evaluated and the resulting properties are added to the property set formed in the preceding step. This means that property settings in a server or service instance descriptor override corresponding settings in a template server or service descriptor.

The server or service instance unnamed property set and its parameters provide two different ways to customize the properties of a server or service template instance. It might not always be obvious which method to use: is it better to use a parameter to parameterize a given property or is it better to just specify it in the server or service instance property set?

For example, in the descriptor above, we could have used a parameter with a default value for the `Timeout` property:

```xml
<application name="TheApp">
  <server-template id="Template">

    <parameter name="instance-name"/>
    <parameter name="timeout" default="30"/>

    <server id="${instance-name}" exe="./server">
      <properties>
        <property name="Timeout" value="${timeout}"/>
      </properties>
    </server>
  </server-template>

  <node name="TheNode">
    <server-instance template="Template" instance-name="MyInst" timeout="-1">
      <properties>
        <property name="Debug" value="1"/>
      </properties>
    </server-instance>
  </node>
</application>
```

Here are some guidelines to help you decide whether to use a parameter or a property:

- Use a parameter for a property that should always be set.
- Use a parameter if you want to make the property obvious to the reader and user of the template.
- Do not use a parameter for optional properties if you want to rely on a default value for the server.
- Do not use parameters for properties that are rarely used.

## See Also

- [Properties and Configuration](https://docs.zeroc.com/ice/3.8/runtime/properties-and-configuration.md)
- [Using IceGrid Deployment](https://docs.zeroc.com/ice/3.8/services/icegrid/using-icegrid-deployment.md)
- [Properties Descriptor Element](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/properties-descriptor-element.md)
- [Application Descriptor Element](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/application-descriptor-element.md)
- [Node Descriptor Element](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/node-descriptor-element.md)
- [Server-Instance Descriptor Element](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/server-instance-descriptor-element.md)
- [Service-Instance Descriptor Element](https://docs.zeroc.com/ice/3.8/services/icegrid/icegrid-xml-reference/service-instance-descriptor-element.md)
