Commands

Commands represent actions you want to perform against the system. They are encapsulated as objects that serve as the payload for HTTP Post controller actions in the backend. Commands can have validation and business rules associated with them, and controllers can have authorization policies that apply to commands.

Overview

Commands provide a structured way to:

• Encapsulate business operations and state changes
• Validate input before execution
• Track changes from original values
• Integrate with React’s rendering pipeline
• Handle authorization and error scenarios

Quick Start

Backend Command (C#):

public record OpenDebitAccount(AccountId AccountId, AccountName Name, CustomerId Owner);

Generated TypeScript:

import { OpenDebitAccount } from './generated/commands';

const [command] = OpenDebitAccount.use({
    accountId: 'a23edccc-6cb5-44fd-a7a7-7563716fb080',
    name: 'My Account',
    owner: '84cda809-9201-4d8c-8589-0be37c6e3f18'
});

await command.execute();

HTTP Headers

Commands automatically include HTTP headers provided by the httpHeadersCallback configured in Arc. This allows you to include authentication cookies, authorization tokens, or other custom headers with every command request.

Proxy Generation

Commands are automatically generated from your backend using the proxy generator. The generator scans HTTP Post actions during compile time and creates TypeScript classes that:

• Match your backend command structure
• Provide type-safe properties
• Include validation support
• Offer a .use() method for React integration
• Track changes automatically

See Proxy Generation for setup details.

Command Result

When executed, commands return a CommandResult with detailed information about the outcome:

const result = await command.execute();

if (result.isSuccess) {
    console.log('Success!', result.response);
} else {
    if (!result.isAuthorized) {
        // Handle authorization failure
    }
    if (!result.isValid) {
        // Handle validation errors
    }
}

For comprehensive details, see Command Result documentation.

Topics

Topic	Description
React Usage	Using the .use() hook in React components (recommended).
Data Binding	Binding to command properties and managing initial values for change tracking.
Validation	Pre-flight validation, progressive validation, and error handling.
Command Scope	Tracking changes across multiple commands in composite UIs.
Imperative Usage	Advanced direct instantiation for non-React scenarios.

Related Documentation

• CommandForm - Declarative form component for commands
• Queries - Data retrieval operations
• Core Commands - Lower-level command concepts- Proxy Generation - Setting up command generation