Skip to content

Client module

A Client Module is provided by the Positions Module for other microservices that need to integrate with Position can do so easily.

The main idea is that microservices depend on the PositionClientModule and it provides a materialized representation of a Position, the PositionMetadata, that we can use to relate our entities to.

The module will also keep the Position Metadata up to date with changes on the Position Service.

Currently, the PositionMetadata includes:

  • Position correlation id.
  • Position name.
  • Position code.
  • Position Type correlation id.
  • Assigned user correlation id (if any).
  • Parent Position correlation id (if any).

How to use it

The main idea behind the PositionsClientModule is that you create your own entity (i.e ServiceOrder) and can have relations to an entity PositionMetadata which is provided by the module.

The DB structure is included as your own service's migrations, and it is handled as another regular entity. The only difference is that we can share the class and it's mapping so that you don't need to write them!

Defining an Entity with a PositionMetadata

First we need to reference the PositionsClientModule's Abstraction assembly from our Domain layer.

XML
1
<ProjectReference Include="$(ServicesPath)Positions/ITsynch.Suite.Positions.Abstractions/ITsynch.Suite.Positions.Abstractions.csproj" />

This will allow us to create an entity which has a Position:

C#
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
using ITsynch.Suite.Positions.Domain;

namespace ITsynch.Suite.ServiceOrders.Domain
{
    public class ServiceOrder : BaseSagaStateMachineInstance
    {
        // [..]
        public PositionMetadata Assignee { get; private set; } = null!;
    }
}

We then need to add an EntityTypeConfiguration for this entity on our Persistence layer as usual:

C#
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
namespace ITsynch.Suite.ServiceOrders.Persistence
{
    internal class ServiceOrderConfiguration
        : IEntityTypeConfiguration<ServiceOrdersDbContext, ServiceOrder>
    {
        public void Configure(EntityTypeBuilder<ServiceOrder> builder)
        {
            // [..]
            builder.HasOne(x => x.Assignee)
                .WithMany()
                .IsRequired()
                .OnDelete(DeleteBehavior.NoAction);
        }
    }
}

After doing that, we must reference and configure the PositionsClientModule on our Application Module before we can generate migrations.

Configuring the Application Module

First, we need to reference the PositionsClientModule's assembly from in our Application layer project:

XML
1
2
<ProjectReference
    Include="$(ServicesPath)Positions/ITsynch.Suite.Positions.Client/ITsynch.Suite.Positions.Client.csproj" />

Then we need to depend on the PositionsClientModule and also configure the DbContext where we want the Position Metadata entity added to. This is usually the only DbContext that you have, which is the one generated by the microservice template:

C#
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
public class MyServiceApplicationModule : SuiteAspNetApplicationModule {

    public override void SetupModule(IModuleBuilder builder)
    {
        builder.DependsOn<PositionsClientModule, PositionsClientModuleOptions>(
            opts =>
            {
                opts.SetDbContext<ServiceOrdersDbContext>();
            });
    }
}

This is all that you need in order for the module to register the EntityTypeConfiguration for PositionMetadata against the DbContext you've just specified.

We can now generate migrations for our service as usual, and we should see the one to one relation we just added, and the table for PositionMetadata being created.