Perform Common Tasks With XAF Actions

• Apr 19, 2024
• 5 minutes to read

This article describes the most common tasks with XAF Actions.

• Use Action Settings
• Add an Action to a Controller
• Add an Action by applying the Action attribute to a business class method
• Customize an Action in the Application Model
• Customize an Action in code
• Create custom Action types and custom controls
• Troubleshoot Actions
• Execute Actions Programmatically

Add an Action to a Controller

Note

In .NET Core applications, it is impossible to add an Action to a Controller in the Controller’s Designer because of the changes in Visual Studio’s designer architecture. You can add an Action in code as described below.

If you require an Action that applies to multiple business objects and takes user input, add this Action to a Controller.

• Add a Parametrized Action
• Add an Action that Displays a Pop-Up Window
• Add an Action with Option Selection

You can also add an Action to a Controller in code.

C#

using DevExpress.ExpressApp;
using DevExpress.ExpressApp.Actions;
using DevExpress.Persistent.Base;
// ...
public class CustomViewController : ViewController {
    public CustomViewController() {
        SimpleAction customAction = new SimpleAction(this, "CustomAction", PredefinedCategory.View);
        // or
        customAction.Category = PredefinedCategory.View.ToString();
        // or 
        customAction.Category = "View";
        // or 
        customAction.Category = "MyCustomCategory";
    }
}

VB.NET

Imports DevExpress.ExpressApp
Imports DevExpress.ExpressApp.Actions
Imports DevExpress.Persistent.Base
' ...
Public Class CustomViewController
    Inherits ViewController
    Public Sub New()
        Dim customAction As New SimpleAction(Me, "CustomAction", PredefinedCategory.View)
        ' or
        customAction.Category = PredefinedCategory.View.ToString()
        ' or 
        customAction.Category = "View"
        ' or 
        customAction.Category = "MyCustomCategory"
    End Sub
End Class

After you add an Action to a Controller, you can use the Designer to customize the Action.

Note

CodeRush allows you to add Actions and Controllers with a few keystrokes. To learn about the Code Templates for XAF, refer to the following help topic: XAF Templates.

Add an Action by Applying the Action Attribute to a Business Class Method

If you require an Action that applies to one business object and uses the business object’s parameters, apply the Action attribute to the business class’s method as shown below:

• Getting Started: Add a Simple Action Using an Attribute (.NET)
• How to: Create an Action Using the Action Attribute

Use the Action attribute only for simple scenarios similar to those described in the articles. For greater flexibility, you can add an Action to a Controller.

Use Action Settings

The base class for all Action types is the ActionBase class. This class exposes events, properties, and methods that support the common Action behavior.

Events

• The ActionBase.Executing and ActionBase.Executed events occur when an end user performs a specified action: clicks a button, selects an item in a combo box, etc.

Properties

• ActionBase.Controller provides access to the parent Controller.
• ActionBase.Active determines the Action’s active/inactive state and visibility.
• ActionBase.Enabled determines an Action’s enabled/displayed state. A Disabled Action is visible in the UI, but is grayed out.
• ActionBase.TargetViewType, ActionBase.TargetViewNesting, ActionBase.TargetViewId, ActionBase.TargetObjectType, ActionBase.TargetObjectsCriteria, ActionBase.TargetObjectsCriteriaMode and ActionBase.SelectionDependencyType specify conditions for Action activation.
• ActionBase.Category specifies an Action’s category. The category determines the Action’s placement in an Action Container.
• ActionBase.ConfirmationMessage specifies the confirmation message displayed when an end user executes an Action.
• ActionBase.Caption specifies the Action’s caption.

Tip

Access the ActionBase class’s members page for a complete list of available API.

Customize an Action in the Application Model

Information on Actions is available in the Application Model’s ActionDesign node.

• How to: Place an Action in a Different Location
• How to: Modify Action Properties in the Model Editor
• Include an Action in a Detail View Layout

Customize an Action in Code

You can access Actions and customize them in code.

• Customize Controllers and Actions
• How to: Customize ASP.NET Web Forms Layout Elements Using Custom CSS Classes
• How to: Customize Action Controls
• Hide or Disable an Action (Button, Menu Item) in Code
• How to: Reorder an Action Container's Actions Collection

Create Custom Action Types and Custom Controls

In XAF, you can create custom Action types and custom controls. See the examples below:

• Create a custom Action type with a custom control (BarCheckItem) associated with it
• Create a custom Action with a custom control in an XAF ASP.NET Web Forms application

Troubleshoot Actions

See the articles below to learn how to diagnose and fix the most frequently encountered problems.

• Determine Why an Action, Controller or Editor is Inactive
• Define the Scope of Controllers and Actions
• Determine an Action's Controller and Identifier
• ActionBase.DiagnosticInfo

Execute Actions Programmatically

We do not recommend that you use the DoExecute and other methods to execute Actions because such methods can contain UI-specific code. You can refactor your Action’s event handlers and extract the required code into separate methods. Call these separate methods directly without triggering UI-related Action code.

Programmatic execution of custom and built-in Actions is acceptable in rare advanced scenarios, for example, if you:

• Create a custom Action Container and call the DoExecute method inside the Action control. In this context, you have complete control over your custom code and can execute any action. Remember to trigger life-cycle events for your actions (such as Execute).
• Add new ways to invoke Actions from the UI (for example, support keyboard or voice control).
• Reuse a built-in Action in a specific context where you would need to write a lot of code to re-implement the Action’s internal business logic.

For more information on how to implement such complex requirements, refer to the following materials:

• XAF - How to execute Actions programmatically.
• “Related GitHub Examples” section of the SimpleAction.DoExecute topic.
• “Related GitHub Examples” section of the ParametrizedAction.DoExecute(Object) topic.