new-component

name

new-component

description

Creating new components: Controllers, Providers, Services, Facades, Orchestrators, Validators. Use when creating a new UTP Facade, StatusDatabase provider, controller, service, orchestrator, or choosing which architectural pattern to use. Covers: ModuleFacadeBase boilerplate, GetBooleanResult not GetResult, StatusDatabaseProviderBase, provider SRP, pattern selection decision tree, primary constructors, XML documentation. stages: test-implementation, test-validation

Creating New Components

When to Use

• Creating a new Facade, Controller, Provider, Service, Orchestrator, or Validator
• Choosing which architectural pattern to use for new code
• Extending an existing component

Pattern Selection Decision Tree

Need	Pattern
Wrap or simplify a UTP module	Facade inheriting ModuleFacadeBase
Orchestrate a game feature or flow	Controller (UTP-based where possible)
Read game/bank state (no side effects)	Provider inheriting StatusDatabaseProviderBase
Multi-step workflow coordinating several components	Orchestrator
Reusable business logic with no external state	Service

Creating a Facade

Location

Shared/Facades/

Mandatory Boilerplate

Every new facade MUST start with this exact skeleton:

namespace Tests.Shared.Facades;

// IUtpCommandService, IModuleFacade, and extension methods are available via GlobalUsings.
// Add 'using System.Text.Json.Nodes;' ONLY if the facade returns JsonNode
// Add 'using IGT.Utp.Framework;' ONLY if the facade references IGT types directly

/// <summary>
/// Facade for interacting with the {ModuleName} UTP module.
/// </summary>
public class {Name}Facade(IUtpCommandService utpService)
    : ModuleFacadeBase(utpService)
{
    protected override string ModuleName => "{ModuleName}";

    private const string SomeCmd = "CommandName";

    // For string results:
    public async Task<string> SomeStringMethodAsync()
    {
        var response = await SendCommandGetResponseAsync(SomeCmd);
        return response.GetStringResult();
    }

    // For boolean results — ALWAYS use GetBooleanResult():
    public async Task<bool> SomeBoolMethodAsync()
    {
        var response = await SendCommandGetResponseAsync(SomeCmd);
        return response.GetBooleanResult();
    }

    // For JSON results:
    public async Task<JsonNode> SomeJsonMethodAsync()
    {
        var response = await SendCommandGetResponseAsync(SomeCmd);
        return response.GetJsonNodeResult();
    }

    // For fire-and-forget commands:
    public async Task SomeVoidMethodAsync()
    {
        await SendCommandAsync(SomeCmd);
    }
}

Critical Facade Rules

• NEVER use GetResult<T>() — it is broken for capitalized bool strings ("True", "False"). Always use the specific typed extension methods: GetBooleanResult(), GetStringResult(), GetJsonNodeResult(), GetStringArrayResult(), GetImageArrayResult(), GetFirstParameterValue(), IsErrorResponse()
• All extension methods are auto-imported via GlobalUsings — no explicit using needed
• Before generating, read an existing facade (e.g., MptFacade.cs, ButtonsFacade.cs) to confirm the pattern

Creating a Controller

Location

Shared/Controllers/ or Shared/Controllers/Egm/ for direct EGM operations

Steps

1. Inject dependencies via primary constructor
2. Implement business logic using facades/services
3. Add XML documentation
4. Extend before creating: Check if an existing controller already covers part of the flow

Creating a Provider

Location

Shared/Providers/ or Shared/Providers/StatusDatabase/

Steps

1. Inherit from StatusDatabaseProviderBase, implement IProvider
2. Use primary constructor for dependencies
3. Use GetStatusValueAsync<T>() for typed retrieval
4. Add XML documentation

Rules

• One module per provider: Each provider maps to exactly one StatusDatabasePaths nested class
• Naming convention: {StatusDatabaseNestedClassName}StatusProvider
• Search before creating: Not all game data comes from StatusDatabase — some comes from UTP module responses (e.g., reel data from MptFacade)
• Provider simplicity: One GetStatusValueAsync<T>() call per method. No candidate-path arrays or try/catch fallbacks

Creating a Service

Location

Shared/Services/ for reusable, Features/<Feature>/Services/ for feature-specific

Steps

1. Keep stateless when possible
2. Define interface in Shared/Interfaces/ if needed
3. Use primary constructor
4. Add XML documentation

Creating a Test

Location

Features/<Feature>/ — NEVER in Tests/ root

Steps

1. Inherit from EgmTestBase
2. Add using BugSweeper.Tests; (not in GlobalUsings)
3. Add XML documentation
4. Reuse over duplication: Check if logic belongs in an existing controller/provider/orchestrator
5. Extract common preconditions: Repeated preambles belong in controllers or shared helpers