Unusable Nodes

• Apr 04, 2023
• 4 minutes to read

In XAF, an Application Model has a layered structure. Model generators and updaters create the first layer based on the current Business Objects Model. This layer is a base application structure without any differences. Refer to the Business Model in the Application Model topic for additional information.

Higher layers are built based on the custom Model settings from the modules’ and applications’ XAFML files and a user’s Model Differences (from a XAFML file or database). If a higher layer’s settings cannot be applied to a specified node from the first layer (node with this name does not exist), these setting are replaced in the UnusableNodes.xafml file.

If your application contains unusable nodes, it displays the following warning message when you customize your Application Model using the Model Editor:

You can also show unusable nodes in the Model Editor by clicking the Show Unusable Nodes button.

How It Works

Settings can be replaced in the UnusableNodes.xafml file in the following cases:

• There were changes in the default application model schema and the new schema does not recognize your nodes.

  Example:

  In the previous schema the “A” attribute was placed into the BOModel node’s “B” node. In the new XAF release, the “A” attribute is defined in the ListView node’s “C” node due to a breaking change. If there is no special model differences converter, your previous customizations affecting the “A” attribute are replaced in the UnusableNodes file.

• There were changes to your business classes’ structure regarding renaming and removing attributes from a class and its members, as well as declaring new and removing previous members in the class.

  Example:

  You renamed your class and lost all the changes you made to its class node in the BOModel, corresponding views nodes in the Views node, etc.

Example

This section explains in which case settings are moved to the UnusableNodes.xafml file and how you can restore them. Navigation items’ settings are used here for demonstration purposes.

In XAF, navigation items are generated from business classes marked with the DefaultClassOptionsAttribute or NavigationItemAttribute. The navigation items decorated with one of these attributes are placed in the corresponding navigation group. The DefaultClassOptions attribute places the navigation item to the Default group. The NavigationItem attribute allows you to specify the name of the target group (to learn more, refer to the attribute class topic.

You can modify the navigation item collection by the following ways:

1. Modify the created navigation items.
2. Add a new navigation item to the existing groups which a generator automatically created.
3. Add a new navigation item to the root navigation group or create a new navigation group and add an item to it.

Then, if you remove the DefaultClassOptionsAttribute and NavigationItemAttribute from all business classes, all differences which were applied to the first and second ways are moved to the UnusableNodes.xafml file. This occurs because the navigation items that were created for the classes decorated with these attributes are removed from the Application Model. So, these differences cannot be applied to the corresponding nodes. These differences are saved in a XAFML file as differences applied to the default NavigationItems node because there were classes marked with the DefaultClassOptions or NavigationItem attribute.

If there are no classes marked with these attributes in a solution and its modules, the group nodes with the DefaultGroupName name and names from the NavigationItem attribute are not generated by default, and model differences cannot be applied to these nodes. Note that model differences are applied to existing nodes only.

Follow the steps below to restore the lost settings:

1. Open the Model Editor, right click on the root Application node to add the NavigationItems, whose settings were moved into the UnusableNodes file, and save changes.
2. Open the UnusableNodes file in a text editor and copy certain customizations. Open the required Model Differences XAFML file as a text file and paste these settings in it.
3. Start your application and ensure that the replaced settings were applied correctly.
4. Remove the UnusableNodes file.

Note

You can use the approach described in the Convert Application Model Differences topic to automatically solve the problem with losing customizations after migrating to a new application version.