Agent Skills: RemoteFactory Development Guide

RemoteFactory Development Guide

RemoteFactory is a Roslyn Source Generator-powered factory for 3-tier .NET applications. It generates factories, handles serialization, and creates ASP.NET Core endpoints at compile time — eliminating DTOs, manual factories, and API controllers.

RemoteFactory works with any .NET class. It does not require Neatoo base classes. Use it with Neatoo entities for full DDD persistence, or with plain ViewModels, POCOs, and static classes for client-server communication without a domain model.

Works With Any Class

RemoteFactory generates factories for whatever class has [Factory]:

// ViewModel — no Neatoo base class, just a plain class
[Factory]
public partial class DashboardViewModel
{
    public partial List<OrderSummary> RecentOrders { get; set; }
    public partial CustomerStats Stats { get; set; }

    [Fetch][Remote]
    internal void Fetch([Service] IOrderRepo orders, [Service] IStatsService stats)
    {
        RecentOrders = orders.GetRecent();
        Stats = stats.GetForDashboard();
    }
}

// Neatoo entity — same factory attributes, adds change tracking + validation
[Factory]
public partial class Order : EntityBase<Order>
{
    public Order(IEntityBaseServices<Order> services) : base(services) { }
    [Create] public void Create() { }
}

Both generate an IXxxFactory with the appropriate methods. The factory pattern is the same whether the target class inherits from EntityBase<T>, ValidateBase<T>, or nothing at all.

What RemoteFactory Does

• Generates factory interfaces and implementations from attributed classes
• Handles serialization automatically — objects cross client/server boundary without DTOs
• Generates ASP.NET Core endpoints — no manual controller code
• Supports three factory patterns for different use cases

The Three Factory Patterns

| Pattern | Use When | Example | Reference | |---------|----------|---------|-----------| | Class Factory | Aggregate roots with lifecycle | Order, Customer | references/class-factory.md | | Interface Factory | Remote services without entity identity | IOrderRepository | references/interface-factory.md | | Static Factory | Stateless commands | EmailCommands | references/static-factory.md |

Quick Decisions Reference

| Question | Answer | |----------|--------| | Should this method be [Remote]? | Only aggregate root entry points | | Must [Remote] methods be internal? | Yes - [Remote] public is error NF0105; [Remote] internal promotes to public on factory interface | | Can I use private setters? | No - breaks serialization | | Should interface methods have attributes? | No - interface IS the boundary; op attributes emit NF0106 | | Which [AuthorizeFactory] scopes apply on an interface factory? | Execute / Read only. CRUD scopes silently never fire. Use parameter matching on the auth class for per-method auth. See references/interface-factory.md. | | Do I need partial keyword? | Yes, always | | Should child entities have [Remote]? | No - causes N+1 remote calls | | Should child entity methods be internal? | Yes - server-only, trimmable, invisible to client | | Can [Execute] return void? | No, must return Task<T> | | Can [Execute] go on a class factory? | Yes, if public static and returns containing type | | How do I handle a factory event on the server? | [FactoryEventHandler<T>] class with a static matching method — runs in the caller's scope (shared DbContext/transaction), sequentially, awaited | | How do I handle a factory event on the client? | Implement IFactoryEventRelay and register it in DI — RemoteFactory invokes Relay(IReadOnlyList<FactoryEventBase>) once per [Remote] call | | Does [FactoryEventHandler<T>] need [Factory]? | No — separate generator pipeline | | I want a handler that participates in the factory's DB transaction | Use [FactoryEventHandler<T>] + IFactoryEvents.Raise — shared scope, sequential, exceptions propagate and roll back | | I want to fire-and-forget external IO (email, webhook, queue) inside a factory method | Call Task.Run + IServiceScopeFactory.CreateScope() directly. RemoteFactory does not own this — snapshot any ambient context (correlation ID, tenant) before the Task.Run body and re-assign inside the child scope. | | How do I stop an event from relaying to the client? | Pass RaiseOptions.ServerOnly to IFactoryEvents.Raise | | Where must factory events be raised? | Inside a factory method via [Service] IFactoryEvents | | Where does business logic go? | In the entity, not the factory | | Can multiple types share a generic base? | Yes — use CRTP constraint (where T : MyBase<T>), [Factory] on base | | How do I reduce Blazor WASM bundle size? | Enable IL trimming (strongly recommended) | | How do I defer loading of related data? | Use LazyLoad<T> with ILazyLoadFactory | | Can I use BCL Lazy<T>? | No — use LazyLoad<T> (has serialization support) |

Reference Files

Consult these files for detailed patterns and examples:

Core Patterns

• references/class-factory.md - Aggregate roots, IFactorySaveMeta, lifecycle hooks
• references/interface-factory.md - Remote service proxies
• references/static-factory.md - Execute commands on static factory classes
• references/factory-events.md - [FactoryEventHandler<T>] mediator + server-to-client relay, IFactoryEvents.Raise, RaiseOptions.ServerOnly, IFactoryEventRelay

Implementation Details

• references/lazyload.md - Deferred async loading with LazyLoad<T>, ILazyLoadFactory
• references/service-injection.md - Constructor vs method injection, child entities
• references/setup.md - Server and client configuration
• references/anti-patterns.md - Common mistakes to avoid

Advanced Topics

• references/advanced-patterns.md - Authorization, correlation context, complex aggregates, testing
• references/polymorphic-hierarchy.md - Generic base class hierarchy with multiple concrete types, CRTP constraint, routing pattern
• references/trimming.md - IL trimming setup (removes server code from deployed client)

Code Sample Sources

This skill contains two types of code examples:

Compiled Code (via MarkdownSnippets)

Code blocks marked with <!-- snippet: name --> are extracted from the reference application and are guaranteed to compile and work. These include:

• Complete class/interface examples
• Full working implementations
• Configuration samples

Hand-Written Code

The following code blocks are intentionally hand-written and NOT extracted from compiled source:

1. Anti-pattern examples (references/anti-patterns.md)

   • All code in this file shows intentionally wrong patterns
   • Marked with // WRONG comments
   • Cannot come from compiled source because they demonstrate errors

2. Partial/illustrative snippets (various files)

   • Short excerpts showing just properties or method signatures
   • Usage examples that aren't full compilable units
   • Inline comparisons (WRONG vs RIGHT patterns)

When updating this skill, edit anti-patterns and partial examples directly in the markdown files. For compiled examples, update the reference application code and run mdsnippets to re-extract.