Add Endpoints for Business Object Methods

• Jan 03, 2024
• 3 minutes to read

The Web API Service allows you to automatically generate endpoints for business object methods that are decorated with an ActionAttribute. Such endpoints can accept a required number of parameters and are automatically displayed in the Swagger UI.

For general information on how to use the ActionAttribute to generate actions in an XAF application and how to design business object methods so that they can be used with this attribute, refer to the following topic: How to: Create an Action Using the Action Attribute.

Important

We intentionally disable endpoints for business object methods in our Web API Service for security reasons. Since these methods may make sensitive modifications to data, every Web API Service developer must be cautious and must verify every business object before exposing its methods to consumers. Refer to the Hide Action Methods from Web API section to see how to hide only certain endpoints generated for business object methods.

Enable Automatic Generation of Endpoints for Action Methods

To enable automatic generation of endpoints for action methods, specify the WebApiOptions.ConfigureBusinessObjectActionEndpoints delegate in the application’s Statup.cs file. In this delegate, enable the EnableActionEndpoints setting:

File: MySolution.WebApi\Startup.cs

C#

services.AddXafWebApi(builder => {
    builder.ConfigureOptions(options => {
        // ...
        options.ConfigureBusinessObjectActionEndpoints(options => {
            options.EnableActionEndpoints = true;
        });
    });
    // ...
});

Additionally, ensure that the MapXafEndpoints method is invoked within the UseEndpoints method call (the XAF Solution Wizard generates the required code automatically).

File: MySolution.WebApi\Startup.cs

C#

public void Configure(IApplicationBuilder app, IWebHostEnvironment env) {
    // ...
    app.UseEndpoints(endpoints => {
        // ...
        endpoints.MapXafEndpoints();
    });
}

When the EnableActionEndpoints option is enabled, the Web API Service registers endpoints for all methods decorated with an ActionAttribute. For example, consider the following business object implementation:

File: MySolution.WebApi\BusinessObjects\Task.cs

C#

public class Task : BaseObject {
    public virtual string Description { get; set; }
    public virtual bool IsComplete { get; set; }
    public virtual DateTime DueDate { get; set; }

    [Action(Caption = "Postpone a task for N days", 
        ToolTip = "Postpone a task. The \"Days\" parameter specifies the number of days the task should be postponed.", 
        TargetObjectsCriteria = "Not [IsComplete]")]
    public void Postpone(PostponeParameters parameters) {
        DueDate += TimeSpan.FromDays(parameters.Days);
    }
}

public class PostponeParameters {
    public PostponeParameters() { Days = 1; }
    public uint Days { get; set; }
}

The endpoints generated for the Postpone method are reflected by the Swagger UI as follows:

The ActionAttribute‘s Caption and ToolTip parameter values are used to fill the endpoint’s summary and description respectively, and the request body example correctly renders the names of the action’s parameters.

Change the Endpoint Base Path

Use the BusinessObjectActionEndpointOptions.BasePath option to customize the base URL path for the generated endpoints (the default setting is "/api/odata"). For example:

File: MySolution.WebApi\Startup.cs

C#

services.AddXafWebApi(builder => {
    builder.ConfigureOptions(options => {
        // ...
        options.ConfigureBusinessObjectActionEndpoints(options => {
            // ...
            options.BasePath = "/my-actions";
        });
    });
    // ...
});

In this configuration, endpoints are generated as shown below:

Hide Action Methods from Web API

Use the BusinessObjectActionEndpointOptions.MethodFilter property to filter out methods that you do not want to be available through Web API endpoints. This property can accept a predicate that takes a MethodInfo object as a parameter. In your implementation of the predicate, you can use the MethodInfo object to decide whether to hide (filter out) specific methods.

File: MySolution.WebApi\Startup.cs

C#

services.AddXafWebApi(builder => {
    builder.ConfigureOptions(options => {
        // ...
        options.ConfigureBusinessObjectActionEndpoints(options => {
            // ...
            options.MethodFilter = m => {
                return !m.Name.Contains("MethodToHide");
            };
        });
    });
    // ...
});

Limitations

• The Web API Service does not currently support validation for action method endpoints.