FreeSql Documentation

Before using repositories, you must initialize IFreeSql as a Singleton. Ensure you use UseAutoSyncStructure(true) if you want the database schema to automatically migrate to match your entities.

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    .UseConnectionString(FreeSql.DataType.Sqlite, @"Data Source=|DataDirectory|\document.db;Pooling=true;Max Pool Size=10")
    .UseAutoSyncStructure(true)
    .Build();

public class Song {
    [Column(IsIdentity = true)]
    public int Id { get; set; }
    public string Title { get; set; }
}

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    .UseConnectionString(FreeSql.DataType.Sqlite, @"Data Source=|DataDirectory|\document.db;Pooling=true;Max Pool Size=10")
    .UseAutoSyncStructure(true) //自动迁移实体的结构到数据库
    .Build(); //请务必定义成 Singleton 单例模式

public class Song {
    [Column(IsIdentity = true)]
    public int Id { get; set; }
    public string Title { get; set; }
}

Because AsyncLocal compatibility varies, transactions for BaseEntity must be managed externally. You provide a function to BaseEntity.Initialization that retrieves the current IUnitOfWork from an AsyncLocal storage.

Implementation Steps

1. Define a static AsyncLocal<IUnitOfWork>.
2. Initialize BaseEntity with a callback returning that value.
3. Wrap your operations in a using block with fsql.CreateUnitOfWork() and manage the AsyncLocal value within the scope.

static AsyncLocal<IUnitOfWork> _asyncUow = new AsyncLocal<IUnitOfWork>();

// Initialize with the provider callback
BaseEntity.Initialization(fsql, () => _asyncUow.Value);

// Usage in a scoped operation
using (var uow = fsql.CreateUnitOfWork())
{
    _asyncUow.Value = uow;

    try
    {
        // BaseEntity internal CRUD methods will now use this transaction
    }
    finally
    {
        _asyncUow.Value = null;
    }
    
    uow.Commit();
}

BaseEntity provides a CodeFirst approach that automatically handles common fields like CreateTime, UpdateTime, and soft delete logic.

• Integer/Long Primary Keys: If you specify int or long as the second generic parameter, the Id is treated as an auto-incrementing identity.
• Guid Primary Keys: If you specify Guid, the extension automatically generates ordered, unique Guid values during insertion.
• Customizing Identity: To disable auto-increment for integer keys, override the Id property and use the [Column(IsIdentity = false)] attribute.

// Integer auto-incrementing primary key
public class UserGroup : BaseEntity<UserGroup, int>
{
    public string GroupName { get; set; }
}

// Disabling auto-increment for integer primary key
public class UserGroup : BaseEntity<UserGroup, int>
{
    [Column(IsIdentity = false)]
    public override int Id { get; set; }
    public string GroupName { get; set; }
}

// Guid primary key (automatically generates ordered Guids)
public class User : BaseEntity<User, Guid>
{
    public string UserName { get; set; }
}

You can access repositories in three ways:

1. Extension Method: Use fsql.GetRepository<T>(). Note that Repository objects are not thread-safe.
2. Inheritance: Create a custom repository by inheriting from BaseRepository<TEntity, TKey>.
3. Dependency Injection: Register repositories in your service collection using AddFreeRepository to enable global filtering (e.g., for multi-tenancy or soft deletes).

Warning: Repository objects are not thread-safe.

// 1. IFreeSql extension method
var curd = fsql.GetRepository<Song>();

// 2. Inheritance implementation
public class SongRepository : BaseRepository<Song, int> {
    public SongRepository(IFreeSql fsql) : base(fsql, null, null) {}
}

// 3. Dependency Injection
public void ConfigureServices(IServiceCollection services) {
    services.AddSingleton<IFreeSql>(Fsql);
    services.AddFreeRepository(filter => filter
        .Apply<ISoftDelete>("SoftDelete", a => a.IsDeleted == false)
        .Apply<ITenant>("Tenant", a => a.TenantId == 1)
        ,
        this.GetType().Assembly
    );
}

// Usage in Controller
public SongsController(GuidRepository<Song> repos1) {
}