NuGet Packages Overview

Section: 16 — Packages
Last Updated: 2026-05-30
Scope: 16 NuGet packages, 4-tier hierarchy, Azure Artifacts feed, smart pipeline

---

At a Glance

Microtec ERP ships 16 NuGet packages that form a reusable platform layer shared across all microservices. These packages eliminate copy-paste of cross-cutting concerns and enforce architectural consistency.

Metric	Value
Total packages	16
Tiers	4 (Foundation → Infrastructure → Web → Feature)
Classes	300+
Interfaces	150+
Services	40+
DTOs	200+
Integration events	25+
Feed	Azure Artifacts (Azure DevOps)
Pipeline	azure-pipelines-smart.yml (change-detected rebuilds)

---

Package Groups

Tier 1 — Foundation (Zero Dependencies)

Package	Purpose
Microtec.Domain	Core entities, base classes, interfaces, value objects, exceptions
Microtec.Contracts	CQRS contracts, integration events, shared DTOs

These packages have no external dependencies and no Azure/EF Core references. They are the bedrock of the entire platform.

Tier 2 — Infrastructure

Package	Purpose
Microtec.Persistence	EF Core base classes, repositories, interceptors, multi-tenancy
Microtec.Messaging	MassTransit wrappers, Azure Service Bus, Redis (StackExchange)
Microtec.Keycloak	Keycloak admin client, provisioning helpers, token introspection
Microtec.PublicApi	Typed HTTP clients for inter-service communication
Microtec.Reporting	NuGet: Microtec.Reporting — report generation engine
Microtec.Attachment.Client	HTTP client for Attachment microservice
Microtec.Notifications.Client	HTTP client for Notification microservice

Tier 3 — Web

Package	Purpose
Microtec.Web.Core	Middleware, JWT auth, localization, error handling, ICurrentUserService
Microtec.Web.Hosting	OpenTelemetry, Serilog/Seq, health checks, startup configuration

Tier 4 — Feature Modules

Package	Purpose
Microtec.Import.Domain	Import domain models, interfaces
Microtec.Import.Infrastructure	Excel/CSV import engine, validation pipeline
Microtec.Import.Integration	Import events, integration contracts
Microtec.Zatca.Infrastructure	Saudi E-Invoicing (ZATCA) core implementation
Microtec.Zatca.Integration	ZATCA integration events, API contracts

---

Dependency Hierarchy (Summary)

Tier 1:  Domain ←── Contracts
                         │
Tier 2:  Persistence ───┤
         Messaging ─────┤──→ (all depend on Domain / Contracts)
         Keycloak ──────┤
         PublicApi ─────┤
         Reporting ─────┘
         Attachment.Client
         Notifications.Client

Tier 3:  Web.Core    → Domain + Contracts + Messaging + Keycloak
         Web.Hosting → Web.Core + Messaging + Persistence

Tier 4:  Import.*  → Web.Core + Persistence + Messaging
         Zatca.*   → Web.Core + Persistence + Contracts

See dependency-hierarchy.md for the full Mermaid diagram and ASCII tree.

---

Azure Artifacts Feed

Packages are published to an Azure DevOps Artifacts feed:

Feed:    https://pkgs.dev.azure.com/microtec-devops/_packaging/microtec-nuget/nuget/v3/index.json
Name:    microtec-nuget

Adding to a project

<!-- NuGet.Config -->
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="microtec-nuget"
         value="https://pkgs.dev.azure.com/microtec-devops/_packaging/microtec-nuget/nuget/v3/index.json" />
  </packageSources>
</configuration>

Authentication: uses $(System.AccessToken) in pipelines. Local dev: PAT with Packaging (Read) scope.
Full setup: Platforms/Solution Items/NUGET-SETUP.md

---

Smart Pipeline

The package pipeline (azure-pipelines-smart.yml) detects which packages changed using git diff and only rebuilds/publishes affected packages and their dependents.

Change Detection Logic

# azure-pipelines-smart.yml (simplified)
- script: |
    CHANGED=$(git diff --name-only HEAD~1 HEAD | grep -E '^Platforms/Src/Shared/|^Platforms/Src/Shared.Web/' | cut -d'/' -f3 | sort -u)
    echo "Changed packages: $CHANGED"
  displayName: Detect changed packages

Example: What rebuilds when Microtec.Domain changes

Changed: Microtec.Domain
Dependents (must rebuild):
  → Microtec.Contracts (depends on Domain)
  → Microtec.Persistence (depends on Domain)
  → Microtec.Messaging (depends on Domain)
  → Microtec.Keycloak (depends on Domain)
  → Microtec.PublicApi (depends on Contracts)
  → Microtec.Web.Core (depends on Domain + Contracts)
  → Microtec.Web.Hosting (depends on Web.Core)
  → Microtec.Import.* (depends on Web.Core)
  → Microtec.Zatca.* (depends on Web.Core)
Total: 14 of 16 packages rebuilt

WARNING

Changes to Microtec.Domain or Microtec.Contracts trigger a near-full rebuild. Minimize breaking changes to these foundation packages.

---

Versioning Strategy

Packages follow Semantic Versioning (MAJOR.MINOR.PATCH):

Change Type	Version Bump	Example
Breaking API change	MAJOR	1.x.x → 2.0.0
New feature (backward-compatible)	MINOR	1.2.x → 1.3.0
Bug fix	PATCH	1.2.3 → 1.2.4

All 16 packages are versioned together — they share the same version number to avoid compatibility matrix complexity.

---

Consuming Services

All microservices under Platforms/Src/ consume the packages. A typical service's .csproj references:

<ItemGroup>
  <PackageReference Include="Microtec.Web.Hosting" Version="2.3.1" />
  <PackageReference Include="Microtec.Persistence" Version="2.3.1" />
  <PackageReference Include="Microtec.Messaging" Version="2.3.1" />
</ItemGroup>

Transitive dependencies (Domain, Contracts, Web.Core) are pulled in automatically.

---

Related Sections

• Package Catalog — all 16 packages with key classes
• Dependency Hierarchy — full Mermaid graph
• Migration Guide — old God Package → new packages
• [NuGet Setup](../../Platforms/Solution Items/NUGET-SETUP.md)
• Backend Architecture — 03