Frequently Asked Questions

General Questions

What is RoomSharp?

RoomSharp is a high-performance ORM for .NET inspired by Android's Room library. It uses source generators to create compile-time implementations of your DAOs, eliminating runtime reflection and providing excellent performance.

Why use RoomSharp instead of Entity Framework Core?

RoomSharp is ideal when you need:

• Maximum performance with zero runtime reflection
• Compile-time code generation and validation
• Fine-grained control over SQL queries
• Lightweight footprint
• Simpler migration story for smaller apps

Use EF Core when you need change tracking, complex LINQ queries, or a full-featured ORM.

Why use RoomSharp instead of Dapper?

RoomSharp offers:

• Compile-time code generation (catch errors at build time)
• Type-safe queries and DAOs
• Built-in migration system
• Better performance for batch operations (2-5X faster)
• IL-based mapping (zero boxing)

Use Dapper when you prefer dynamic SQL and runtime flexibility.

Is RoomSharp production-ready?

RoomSharp is currently in Preview. The core features are stable, but the API may change before 1.0. We recommend thorough testing before using in production.

Installation & Setup

Which package should I install?

Start with the core package:

• RoomSharp - Includes SQLite support
• RoomSharp.SqlServer - For SQL Server
• RoomSharp.PostgreSql - For PostgreSQL
• RoomSharp.MySql - For MySQL/MariaDB
• RoomSharp.DependencyInjection - Optional DI extensions

Do I need to install multiple provider packages?

No, only install the provider(s) you actually use. The core RoomSharp package includes SQLite support.

Can I switch database providers later?

Yes! RoomSharp supports multiple database providers through a unified API. Just change the builder configuration:

// From
.UseSqlite("app.db")
// To
.UsePostgreSql(connectionString)

Performance

How fast is RoomSharp compared to alternatives?

See our benchmarks page for detailed comparisons. Key highlights:

• ~15% faster than Dapper for single queries
• 2-5X faster for batch inserts
• Zero allocations in hot loops
• IL-based mapping (no boxing)

Why is batch insert so fast?

RoomSharp's BatchInsertEngine uses:

• Prepared statement reuse
• Zero allocations in loops
• Static column name arrays
• Automatic transaction management

Does RoomSharp use reflection?

No! RoomSharp uses source generators to create all implementations at compile-time. There's zero runtime reflection.

Features

Does RoomSharp support async operations?

Yes, fully! All DAO methods support Task, Task<T>, and ValueTask<T> return types.

Can I use raw SQL queries?

Yes, use the [Query] attribute for static queries or [RawQuery] for dynamic SQL built at runtime.

Does RoomSharp support migrations?

Yes, RoomSharp includes both manual migrations and auto-migration support with declarative attributes.

Can I use stored procedures?

Yes, use [RawQuery] or [Query] to call stored procedures depending on your database provider.

Does RoomSharp support relations (joins)?

Yes, using [Relation] and [Embedded] attributes with the RelationLoader utility.

Development

How do I view generated code?

In Visual Studio or Rider:

1. Expand your project in Solution Explorer
2. Navigate to Dependencies → Analyzers → RoomSharp.SourceGenerator
3. View the .g.cs files

My changes aren't being picked up by the generator

Try these steps:

1. Clean and rebuild the solution
2. Restart Visual Studio/Rider
3. Delete bin and obj folders
4. Check for build errors

Can I debug generated code?

Yes, enable source generation output in your .csproj:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

Database-Specific

Does SQLite support concurrent writes?

Enable WAL mode for better concurrent access:

.UseSqlite("app.db")
.SetJournalMode(JournalMode.WAL)
.EnableMultiInstanceInvalidation()

How do I handle large datasets?

Use:

• Batch operations for inserts/updates
• IAsyncEnumerable for streaming
• Pagination with LIMIT/OFFSET
• Chunking for very large datasets

Can I use TransactionScope?

Yes, but we recommend using RoomSharp's built-in transaction methods (RunInTransaction) for better performance and control.

Troubleshooting

I'm getting "Database is locked" errors

For SQLite:

• Enable WAL mode
• Reduce transaction duration
• Ensure connections are properly disposed
• Use SetAutoCloseTimeout

Generate code has compilation errors

Check:

• All entities have [PrimaryKey]
• Query parameter names match method parameters
• Return types are valid for the operation
• Build output for generator warnings

Performance is slower than expected

Ensure you're:

• Using async methods
• Using batch operations for multiple inserts
• Wrapping multiple operations in transactions
• Using indexes on queried columns
• Selecting only needed columns

Source Code & Community

Is RoomSharp open source?

RoomSharp will be published as open source after the Preview stage. See the Roadmap for timeline.

How can I report bugs or request features?

During the Preview phase, feedback channels will be announced. After open source publication, use GitHub Issues.

Can I contribute to RoomSharp?

Yes! Once the source code is published, we welcome contributions. See the Roadmap for areas where help is needed.

Still Have Questions?

Check out these resources:

• Documentation - Comprehensive guides
• Error Handling - Common error solutions
• Benchmarks - Performance comparisons
• Roadmap - Future plans