Agent Skills: RemoteFactory Development Guide

RemoteFactory Development Guide

RemoteFactory is a Roslyn Source Generator-powered Data Mapper Factory for 3-tier .NET applications. It eliminates the need for DTOs, manual factories, and API controllers by generating everything at compile time.

RemoteFactory + Neatoo together provide the complete DDD framework. For domain model, validation, properties, and collections, see the Neatoo skill. This skill covers factory generation, serialization, authorization, and client-server patterns.

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 and events | 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 | | 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 | | Do [Event] methods need CancellationToken? | Yes, as final parameter | | Where does business logic go? | In the entity, not the factory | | How do I reduce Blazor WASM bundle size? | Enable IL trimming (strongly recommended) |

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 and Event handlers

Implementation Details

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