basic-usage.md

Basic Usage

Database model

create table "unit_tests"."test_entity"
(
	id serial not null
		constraint test_entity_pk primary key,
	record_id text,
	sensor_id text,
  value integer
);

C# model

public class TestEntity
{
    public int Id { get; set; }

    public string RecordId { get; set; }

    public string SensorId { get; set; }

    public int Value { get; set; }
}

Configuration and type mapping

In Startup.cs class add service registration that recieves an bulk service options. BulkServiceOptions class defines options for whole bulk service; however, some settings could be overriten for a particular entities, this will be describes further.

public class Startup
{
    ...
    public void ConfigureServices(IServiceCollection services)
    {
        ...
        services.AddPostgreSqlBulkService(options =>
        {
            options.AddEntityProfile<TestEntity>(new TestEntityProfile());
        });
    }
}

TestEntityProfile should extend EntityProfile class and it describes mapping and some additional settings that could be applied only to operation with TestEntity instances.

public class TestEntityProfile: EntityProfile
{
    public TestEntityProfile()
       :base(typeof(TestEntity))
    {
        this.ToTable("test_entity", "unit_tests");

        this.HasProperty<TestEntity, int>(entity => entity.Id)
            .ThatIsAutoGenerated()
            .ThatIsPrivateKey();
        this.HasProperty<TestEntity, string>(entity => entity.RecordId);
        this.HasProperty<TestEntity, string>(entity => entity.SensorId);
        this.HasProperty<TestEntity, int>(entity => entity.Value);
    }
}

Usage

All bulk operations are provided by IPostgreSqlBulkService, so it has to be injected into your class

[Route("api/[controller]")]
[ApiController]
public class TestEntityController: ControllerBase {
  private readonly IPostgreSqlBulkService _bulkService;
  private readonly string _connectionString;
  
  public MyService(IPostgreSqlBulkService bulkService, string connectionString) {
    _bulkService = bulkService;
    _connectionString = connectionString;
  }

  [HttpPost]
  public async Task Insert(ICollection<TestEntity> entities, CancellationToken cancellationToken)
  {
    using(var connection = new NpgsqlConnection(_connectionString))
    {
      // Will automatically receive generated ids and map them on existed entities.
      var result = await _bulkService.InsertAsync(connection, entities, cancellationToken);
      
      // here each entity in the collection "entities" will have an Id property already set.
      return result;
    }
  }
  
  [HttpPut]
  public async Task Update(ICollection<TestEntity> entities, CancellationToken cancellationToken)
  {
    using(var connection = new NpgsqlConnection(_connectionString))
    {
      var result = await _bulkService.UpdateAsync(connection, entities, cancellationToken);
      return result;
    }
  }
  
  [HttpDelete]
  public async Task Delete(ICollection<TestEntity> entities, CancellationToken cancellationToken)
  {
    using(var connection = new NpgsqlConnection(_connectionString))
    {
      var result = await _bulkService.DeleteAsync(connection, entities, cancellationToken);
      return result;
    }
  }
}

The insert and update operations could be joined in UpsertAsync operation, but it requise to set a unique columns. More details and examples of using UpsertAsync operation you will find in the Upsert section.