remotefactory - SKILL.md Agent Skill

name: RemoteFactory description: | This skill should be used when the user mentions "RemoteFactory", "Neatoo.RemoteFactory", "[Factory] attribute", "[Remote] attribute", "[Execute] attribute", "[FactoryEventHandler]", "FactoryEventBase", "IFactoryEvents", "IFactoryEventRelay", "factory event relay", "ServerOnly", "RaiseOptions", "IFactorySaveMeta", "[AspAuthorize]", "[AuthorizeFactory]", "Save routing", "domain events", "client-server factory", "IL trimming", "bundle size", "PublishTrimmed", "NeatooRuntime", "ViewModel factory", "LazyLoad", "ILazyLoadFactory", "deferred loading", "lazy loading", or asks about factory patterns for 3-tier .NET applications. RemoteFactory works with any .NET class — Neatoo entities, ViewModels, POCOs, or static commands. It does NOT require Neatoo base classes. Provides guidance for building enterprise line-of-business applications using RemoteFactory's source-generated factory patterns. version: 1.0.0

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
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  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:

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
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.