ArgTelecom.SharedKernel 1.0.0

ArgTelecom.SharedKernel

Reusable shared kernel for ArgTelecom .NET 10 microservices, published as a NuGet package.

The package follows Clean Architecture principles and is intentionally small: it contains abstractions, one sample domain, the Result pattern and DI registration only. There is no infrastructure, persistence or EF Core code, so every microservice can reference it without inheriting a technology choice.

Contents

Installation

From the GitLab Package Registry:

dotnet nuget add source "https://git.arg-eng.ir/api/v4/projects/<PROJECT_ID>/packages/nuget/index.json" \
  --name argtelecom \
  --username <USERNAME> \
  --password <PERSONAL_ACCESS_TOKEN> \
  --store-password-in-clear-text

dotnet add package ArgTelecom.SharedKernel

Or pin a version explicitly:

dotnet add package ArgTelecom.SharedKernel --version 1.0.0

Usage

Registration

builder.Services.AddSharedKernel();

// The consuming service supplies its own ICurrentUser implementation:
builder.Services.AddScoped<ICurrentUser, HttpContextCurrentUser>();

Every registration uses TryAdd semantics, so your own implementations always win. Options are available for advanced scenarios:

builder.Services.AddSharedKernel(options =>
{
    options.RegisterDefaultDateTimeProvider = true; // default
    options.TimeProvider = TimeProvider.System;     // swap for FakeTimeProvider in tests
});

Result pattern

public async Task<Result<Order>> GetAsync(Guid id, CancellationToken ct)
{
    Order? order = await _repository.FindAsync(id, ct);

    return order is null
        ? Error.NotFound($"Order '{id}' was not found.", "Order.NotFound")
        : Result.Ok(order);
}

// Composition
Result<string> reference = await GetAsync(id, ct)
    .MapAsync(order => order.Reference);

// Mapping to a transport response
IResult response = result.Match(
    order => Results.Ok(order),
    error => error.Type switch
    {
        ErrorType.NotFound => Results.NotFound(error),
        ErrorType.Validation => Results.BadRequest(error),
        ErrorType.Conflict => Results.Conflict(error),
        ErrorType.Unauthorized => Results.Unauthorized(),
        ErrorType.Forbidden => Results.Forbid(),
        _ => Results.Problem(error.Message),
    });

Entities and domain events

public sealed record OrderPlaced(Guid OrderId) : DomainEvent;

public sealed class Order : BaseEntity
{
    public Order(string reference) => Reference = reference;

    public string Reference { get; private set; } = string.Empty;

    public void Place() => RaiseDomainEvent(new OrderPlaced(Id));

    public void Rename(string reference, IDateTimeProvider clock)
    {
        Reference = reference;
        SetUpdated(clock);
    }
}

BaseEntity generates a sortable UUID v7 identity, compares entities by identity and type, and collects domain events that the consuming service dispatches after its unit of work is committed (entity.DomainEvents / entity.ClearDomainEvents()).

Local development

dotnet restore
dotnet build
dotnet test
dotnet pack -c Release -o artifacts

The build treats warnings as errors, generates XML documentation and enforces the rules in .editorconfig. Package versions are managed centrally in Directory.Packages.props.

Versioning and release

The version is never hard coded in the project file — it comes from the Git tag:

Untagged pipelines still pack a throwaway 0.0.0-ci.<pipeline> package so packaging is always validated, but they never publish.

git checkout master
git pull
git add .
git commit -m "Initial release"
git push

git tag v1.0.0
git push origin v1.0.0

The tag pipeline runs restore → build → test → pack → publish and pushes the package to the GitLab Package Registry using CI_JOB_TOKEN (no secrets required). Publishing to nuget.org is a manual job that only appears when a protected and masked NUGET_API_KEY variable is defined.

Publishing manually

dotnet pack -c Release -o artifacts -p:Version=1.0.0

dotnet nuget push "artifacts/*.nupkg" \
  --source "https://git.arg-eng.ir/api/v4/projects/<PROJECT_ID>/packages/nuget/index.json" \
  --api-key <PERSONAL_ACCESS_TOKEN> \
  --skip-duplicate

Repository layout

├── ArgTelecom.SharedKernel.slnx          # solution
├── src/ArgTelecom.SharedKernel/          # the published library
├── tests/ArgTelecom.SharedKernel.Tests/  # xUnit test suite
├── docs/init-SDD.md                      # original software design document
├── docs/design-decisions.md              # improvements made on top of the SDD
├── Directory.Build.props                 # shared build settings and versioning defaults
├── Directory.Packages.props              # central package version management
├── .editorconfig                         # formatting and analyzer configuration
└── .gitlab-ci.yml                        # restore / build / test / pack / publish pipeline