How to: Create an Action Using the Action Attribute

• Nov 13, 2023
• 6 minutes to read

This example demonstrates how to create an Action within a persistent class declaration (i.e., how to convert a persistent class method into a SimpleAction or PopupWindowShowAction).

Important Notes on Using the Action Attribute

Actions created with the ActionAttribute are not designed to operate in List Views without any selected objects. The attribute’s ActionAttribute.SelectionDependencyType parameter can be set either to RequireSingleObject or RequireMultipleObjects (see MethodActionSelectionDependencyType). To create an Action that does not require the selected object, add a Controller and implement an Action in it (see Add a Simple Action and Add an Action that Displays a Pop-Up Window).

ActionAttribute is primarily used in simple scenarios when you execute logic based on data available within the business class context (for instance, modify class properties). ActionAttribute is not suitable for any UI-related logic and complex user interactions. It is also not possible to access XafApplication, Views, and other XAF UI-related entities within the business class code, because it violates the separation of concerns principle and is against the MVC architecture (your data model should not be tied to the UI). To access XafApplication, Views, and other UI-related entities, implement Controllers with Actions.

Create A Simple Action

Add a Task business class to your project.

C# (EF Core)

[DefaultClassOptions,ImageName("BO_Task"),DefaultProperty(nameof(Subject))]
public class Task : BaseObject {
    public virtual string Subject { get; set; }
    public virtual bool IsCompleted { get; set; }
}

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)

[DefaultClassOptions, ImageName("BO_Task"), DefaultProperty(nameof(Subject))]
public class Task : BaseObject {
    public Task(Session session) : base(session) { }
    private string subject;
    public string Subject {
        get { return subject; }
        set { SetPropertyValue(nameof(Subject), ref subject, value); }
    }
    private bool isCompleted;
    public bool IsCompleted {
        get { return isCompleted; }
        set { SetPropertyValue(nameof(IsCompleted), ref isCompleted, value); }
    }
}

VB.NET (XPO)

Public Class Task
    Inherits BaseObject
    Public Sub New(ByVal session As Session)
        MyBase.New(session)
    End Sub
    Private _subject As String
    Public Property Subject() As String
        Get
            Return _subject
        End Get
        Set(ByVal value As String)
            SetPropertyValue(NameOf(Subject), _subject, value)
        End Set
    End Property
    Private _isCompleted As Boolean
    Public Property IsCompleted() As Boolean
        Get
            Return _isCompleted
        End Get
        Set(ByVal value As Boolean)
            SetPropertyValue(NameOf(IsCompleted), _isCompleted, value)
        End Set
    End Property
End Class

Implement an Action that changes the IsCompleted property to true. Add the following Complete method to the Task class and decorate it with the ActionAttribute.

C#

[Action(Caption="Complete", TargetObjectsCriteria = "Not [IsCompleted]")]
public void Complete() {
    IsCompleted = true;
}

VB.NET

<Action(Caption:="Complete", TargetObjectsCriteria := "Not [IsCompleted]")> _
Public Sub Complete()
    IsCompleted = True
End Sub

Such methods are automatically collected from business classes by the ObjectMethodActionsViewController. This controller creates the Task.Complete Action, that invokes the Complete method for each selected Task. Note the use of the ActionAttribute.TargetObjectsCriteria parameter. The Action is disabled for Tasks that are already completed (the IsCompleted property is true). You can pass other parameters to customize the Action’s look and behavior.

The images below illustrate the Complete Action in the UI.

ASP.NET Core Blazor

WinForms

ASP.NET Web Forms

Create an Action that Displays a Pop-up Dialog

Extend the Task class with two additional properties (Deadline and Comments) to demonstrate a more complex scenario.

C# (EF Core)

using DevExpress.ExpressApp.Model;
// ...
public virtual DateTime? Deadline { get; set; }

[FieldSize(FieldSizeAttribute.Unlimited),ModelDefault("AllowEdit", "False")]
public virtual string Comments { get; set; }

// Make sure that you use options.UseChangeTrackingProxies() in your DbContext settings.

C# (XPO)

using DevExpress.ExpressApp.Model;
// ...
private DateTime? deadline;
public DateTime? Deadline {
    get { return deadline; }
    set { SetPropertyValue(nameof(Deadline), ref deadline, value); }
}
private string comments;
[Size(SizeAttribute.Unlimited), ModelDefault("AllowEdit", "False")]
public string Comments {
    get { return comments; }
    set { SetPropertyValue(nameof(Comments), ref comments, value); }
}

VB.NET (XPO)

using DevExpress.ExpressApp.Model;
' ...
Private _deadline? As DateTime
Public Property Deadline() As DateTime?
    Get
        Return _deadline
    End Get
    Set(ByVal value? As DateTime)
        SetPropertyValue(NameOf(Deadline), _deadline, value)
    End Set
End Property
Private _comments As String
<Size(SizeAttribute.Unlimited), ModelDefault("AllowEdit", "False")> _
Public Property Comments() As String
    Get
        Return _comments
    End Get
    Set(ByVal value As String)
        SetPropertyValue(NameOf(Comments), _comments, value)
    End Set
End Property

Implement an Action that postpones the Deadline by a specified number of days and updates the Comments text. First, declare the following non-persistent class that holds parameters to be specified when a user postpones a Task.

C#

using DevExpress.ExpressApp.DC;
// ...
[DomainComponent]
public class PostponeParametersObject {
    public PostponeParametersObject() { PostponeForDays = 1; }
    public uint PostponeForDays { get; set; }
    [FieldSize(FieldSizeAttribute.Unlimited)]
    public string Comment { get; set; }
}

VB.NET

Imports DevExpress.ExpressApp.DC
' ...
<DomainComponent> _
Public Class PostponeParametersObject
    Public Sub New()
        PostponeForDays = 1
    End Sub
    Private _postponeForDays As UInteger
    Public Property PostponeForDays() As UInteger
        Get
            Return _postponeForDays
        End Get
        Set(ByVal value As UInteger)
            _postponeForDays = value
        End Set
    End Property
    Private _comment As String
    <Size(SizeAttribute.Unlimited)> _
    Public Property Comment() As String
        Get
            Return _comment
        End Get
        Set(ByVal value As String)
            _comment = value
        End Set
    End Property
End Class

Then, add the following Postpone method to the Task class. This method takes a parameter of the PostponeParametersObject type and is decorated with the Action attribute.

C#

[Action(Caption = "Postpone",
    TargetObjectsCriteria = "[Deadline] Is Not Null And Not [IsCompleted]")]
public void Postpone(PostponeParametersObject parameters) {
    if (Deadline.HasValue && !IsCompleted && (parameters.PostponeForDays > 0)) {
        Deadline += TimeSpan.FromDays(parameters.PostponeForDays);
        Comments += String.Format("Postponed for {0} days, new deadline is {1:d}\r\n{2}\r\n",
        parameters.PostponeForDays, Deadline, parameters.Comment);
    }
}

VB.NET

<Action(Caption := "Postpone", _
TargetObjectsCriteria := "[Deadline] Is Not Null And Not [IsCompleted]")> _
Public Sub Postpone(ByVal parameters As PostponeParametersObject)
    If Deadline.HasValue AndAlso (Not IsCompleted) AndAlso (parameters.PostponeForDays > 0) Then
        Deadline += TimeSpan.FromDays(parameters.PostponeForDays)
        Comments += String.Format("Postponed for {0} days, new deadline is {1:d}" & Constants.vbCrLf & _
        "{2}" & Constants.vbCrLf, parameters.PostponeForDays, Deadline, parameters.Comment)
    End If
End Sub

As a result, the Task.Postpone Action, that accompanies the Task Views, is automatically created. This Action invokes a dialog with the PostponeParametersObject Detail View and executes the Postpone method after a user specifies the parameters and clicks OK. The following images illustrate this.

ASP.NET Core Blazor

WinForms

ASP.NET Web Forms

Tip

If it is necessary to reorder parameters displayed in a popup dialog, modify the layout of a parameter object’s Detail View in the Model Editor. In the example above, the appropriate Detail View node is PostponeParametersObject_DetailView. Refer to the folowing topic to learn more about layout customizations: View Items Layout Customization.

Access the current object instance

If you declare a PostponeParametersObject constructor that takes a parameter of type Task, the current Task instance is passed to this constructor when a user initiates the Action.

C#

[DomainComponent]
public class PostponeParametersObject {
    private Task task;
    public PostponeParametersObject(Task task) {
        PostponeForDays = 1;
        this.task = task;
    }
    // ...
}

VB.NET

<DomainComponent> _
Public Class PostponeParametersObject
    Private task As Task
    Public Sub New(ByVal task As Task)
        PostponeForDays = 1
        Me.task = task
    End Sub
    ' ...
End Class