Pacx Command Writer

PACX Command Writer

Every PACX command is a pair of files in Greg.Xrm.Command.Core\Commands\<Domain>\. Executors need no manual DI registration: Extensions.RegisterCommandExecutors() auto-scans all ICommandExecutor<T> implementations at startup. Supporting services and repositories must be registered explicitly against their interfaces in IoCModule.

Rules

• Plan in advance — think through the command's options, validation, and usage examples before implementation.
• Draft an implementation plan in markdown in the /docs folder before coding.
  • The implementation plan must contain the list of steps required to implement the command.
  • When you start working on a single step, update the step title putting a 🕒 before the step title
  • When a step is completed, update the step title putting a ✅ before the step title
  • Implementation plan must include also unit tests for all implemented steps.
• Commit after each implementation step.
• Before pushing, run a code review of the changes to ensure adherence to project conventions and correctness.
• If in the code you need to use dataverse tables, create a model class in /Greg.Xrm.Command.Core/Model implementing EntityWrapper and a repository to manage the queries. Use Greg.Xrm.Command.Core\Model\WebResource.cs as a reference sample.

File 1 — <Verb>Command.cs (options holder)

This class declares CLI options via attributes and optionally handles cross-option validation and usage examples. It must not contain business logic.

using Greg.Xrm.Command.Parsing;             // ICanProvideUsageExample, MarkdownWriter
using Greg.Xrm.Command.Services;            // MarkdownWriter (via Parsing namespace)
using System.ComponentModel.DataAnnotations; // [Required], IValidatableObject

namespace Greg.Xrm.Command.Commands.<Domain>
{
    [Command("<noun>", "<verb>", HelpText = "One-sentence description.")]
    [Alias("<verb>", "<noun>")]   // only add when reversed order is natural
    public class <Verb>Command : IValidatableObject, ICanProvideUsageExample
    //           ─────────────────────────────────   ──────────────────────
    //           implement only when cross-option     implement for non-trivial
    //           constraints exist                    commands to aid discoverability
    {
        // Required options first — low Order values (1, 2, 3…)
        [Option("name", "n", Order = 1, HelpText = "...")]
        [Required]
        public string? Name { get; set; }

        // Optional options — grouped by concern, higher Order values
        [Option("description", "d", Order = 10, HelpText = "...")]
        public string? Description { get; set; }

        // Solution is always last (Order = 50+)
        [Option("solution", "s", Order = 50, HelpText = "Unmanaged solution name. Uses the current default solution if omitted.")]
        public string? SolutionName { get; set; }

        // Cross-option validation only — single-option guards go in the executor
        public IEnumerable<ValidationResult> Validate(ValidationContext validationContext)
        {
            if (/* mutually exclusive condition */)
                yield return new ValidationResult("...", new[] { nameof(OptionA), nameof(OptionB) });
        }

        public void WriteUsageExamples(MarkdownWriter writer)
        {
            writer.WriteParagraph("Minimal usage:");
            writer.WriteCodeBlock("pacx <noun> <verb> --name \"value\"", "Powershell");
        }
    }
}

[Option] conventions

[Command] and [Alias] conventions

• Verb order in [Command] is always noun first: [Command("table", "create", ...)].
• [Alias] reverses the order when natural: [Alias("create", "table")].
• Only add [Alias] when the reversed form is genuinely useful.

File 2 — <Verb>CommandExecutor.cs (business logic)

using Greg.Xrm.Command.Services.Connection;
using Greg.Xrm.Command.Services.Output;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Messages;
using System.ServiceModel; // FaultException<OrganizationServiceFault>

namespace Greg.Xrm.Command.Commands.<Domain>
{
    public class <Verb>CommandExecutor(
            IOutput output,
            IOrganizationServiceRepository organizationServiceRepository) : ICommandExecutor<<Verb>Command>
    {
        public async Task<CommandResult> ExecuteAsync(<Verb>Command command, CancellationToken cancellationToken)
        {
            // Step 1 — always connect first
            output.Write("Connecting to the current dataverse environment...");
            var crm = await organizationServiceRepository.GetCurrentConnectionAsync();
            output.WriteLine("Done", ConsoleColor.Green);

            try
            {
                // Step 2 — resolve default solution when the option is omitted
                var solutionName = command.SolutionName;
                if (string.IsNullOrWhiteSpace(solutionName))
                {
                    solutionName = await organizationServiceRepository.GetCurrentDefaultSolutionAsync();
                    if (solutionName == null)
                        return CommandResult.Fail("No solution name provided and no current solution name found in the settings.");
                }

                // Step 3 — report each logical step inline
                output.Write("Performing the operation...");
                var request = new OrganizationRequest(/* ... */);
                var response = await crm.ExecuteAsync(request);
                output.WriteLine(" Done", ConsoleColor.Green);

                // Step 4 — return success with key output values
                var result = CommandResult.Success();
                result["EntityId"] = response./* ... */;
                return result;
            }
            catch (FaultException<OrganizationServiceFault> ex)
            {
                return CommandResult.Fail(ex.Message, ex);
            }
        }

        // Non-trivial computations go in private static helpers to keep ExecuteAsync readable
        private static string ComputeSchemaName(string displayName, string publisherPrefix)
        {
            // ...
        }
    }
}

Executor conventions

• MUST: keep Greg.Xrm.Command.Commands namespaces limited to commands, command executors, and command-specific helpers. Put supporting service implementations and their interfaces under Greg.Xrm.Command.Services (with a domain subnamespace when useful), and models/repositories and their interfaces under Greg.Xrm.Command.Model. Never place services or their contracts in a command folder or namespace.
• MUST: inject every service, repository, resolver, and delegated executor through an interface, never a concrete implementation type. Reuse an existing interface where available; otherwise define one alongside the implementation, implement it, and register the mapping in IoCModule (for example builder.RegisterType<Team.Repository>().As<ITeamRepository>()). Apply this rule to supporting services' constructor dependencies as well. Delegate executors through ICommandExecutor<TCommand>. Do not instantiate dependencies or bypass injection with static methods that perform I/O; expose those operations through the injected interface. This is mandatory so executor unit tests can mock dependencies and run entirely locally. Pure static formatting/computation helpers are allowed.
• Command infrastructure (CommandRunnerBase) validates DataAnnotations and IValidatableObject before calling an executor. Do not call Validator.TryValidateObject again in executors or duplicate command validation there. Declare input constraints on the command; keep only business checks requiring resolved data (for example whether a privilege supports a depth) in the executor. Tests for command validation belong in the command test file, not in tests that invoke the executor directly.
• Never write to Console directly — always use IOutput.
• If you need additional output formatting you can use IAnsiConsole from Greg.Xrm.Command.Services.Output, which wraps Spectre.Console functionality.
• Inline progress pattern: output.Write("Step…") → do async work → output.WriteLine(" Done", ConsoleColor.Green).
• Highlight important user-provided values in yellow: output.Write(command.SchemaName, ConsoleColor.Yellow).
• Resolve omitted --solution via organizationServiceRepository.GetCurrentDefaultSolutionAsync().
• Catch FaultException<OrganizationServiceFault> at minimum. Catch Exception when non-Dataverse failures are possible.
• Put non-trivial computation in private static helper methods.
• Populate CommandResult with key/value output pairs for structured consumers.
• CommandResult output values must be scalars (strings, numbers, booleans, GUIDs), never arrays or collection objects: the CLI renders them via ToString() and displays .NET type names instead of their contents. Render detailed collections through IOutput.WriteTable and return counts or explicitly formatted summary strings. Keep collection-based view models internal; tests can inspect service results or capture table rows, rather than requiring collections in command output parameters.