Zum Hauptinhalt springen

TIS API Development Guide - Projektstruktur

🤖 Generated with Claude Code

⚠️ Not yet reviewed

Co-Authored-By: Claude (noreply@anthropic.com)

Übersicht​

TIS API-Projekte folgen einer standardisierten Projektstruktur basierend auf .NET Standards.

Aktuelle TIS API-Projekte (Referenz-Implementierungen)​

Modernste Standards (2024/2025)​

  • tis.identity.api (.NET 9) - Vollständige REST API mit Contracts Package
  • tis.gf.boaapi (.NET 8) - ⭐ Empfohlenes Template für neue API-Projekte - Minimale, saubere Struktur mit modernen Standards
  • tis.gf.wgp (.NET 8) - Service mit Frontend-Integration
  • tis.userabgleich (.NET 8) - Standard API-Struktur

Standard-Projektstruktur​

Basis-Layout (basierend auf tis.identity.api):

tis.[servicename].api/
├── src/ # Quellcode
│ ├── tis.[servicename].api/ # Haupt-API-Projekt (lowercase)
│ ├── Tis.[ServiceName].Api.Contracts/ # OpenAPI Contracts (optional)
│ └── Tis.[ServiceName].Api.Client/ # Generated Client (optional)
├── tests/ # Tests
│ ├── Tis.[ServiceName].Api.UnitTests/
│ ├── Tis.[ServiceName].Api.IntegrationTests/
│ └── *.http # HTTP Test Files
├── contracts/rest/ # Generated OpenAPI Specs
├── docs/ # Erweiterte Dokumentation
├── azure-pipelines.yml # Standard CI/CD Pipeline
├── Directory.Build.props # Zentrale Build-Konfiguration (optional)
├── Tis.[ServiceName].Api.sln # Solution File (PascalCase)
└── README.md # Service-Dokumentation

Projekt-Typen und Namenskonventionen​

1. Haupt-API-Projekt​

Name: tis.[servicename].api
Beispiele:
- tis.identity.api
- tis.userabgleich.api
- tis.gf.wgp

Eigenschaften:

  • Framework: .NET 6/8/10 (aktuellstes LTS bevorzugt)
  • SDK: Microsoft.NET.Sdk.Web
  • Struktur: Feature-basierte Ordner

Interne Struktur:

tis.[servicename].api/
├── Program.cs # Application Entry Point
├── appsettings.json # Basis-Konfiguration
├── appsettings.[environment].json # Umgebungsspezifisch
├── nlog.config # Logging-Konfiguration
├── [FeatureName]Api/ # Feature-Module
│ ├── Controllers/
│ ├── Models/
│ └── Services/
├── Storage/ # Data Access Layer
│ ├── Entities/
│ ├── Stores/
│ └── DbContext/
├── Extensions/ # Service Extensions
├── Internal/ # Interne Utilities
└── Observability/ # Telemetry & Health Checks

2. Contracts-Projekt (optional)​

Name: Tis.[ServiceName].Api.Contracts
Framework: .NET Standard/Current
Zweck: OpenAPI Specs als NuGet Package

3. Client-Projekt (optional)​

Name: Tis.[ServiceName].Api.Client  
Framework: .NET Standard/Current
Zweck: Generated API Client

4. Test-Projekte​

Tis.[ServiceName].Api.UnitTests     # Unit Tests
Tis.[ServiceName].Api.IntegrationTests # Integration & Performance Tests

Spezielle Projekt-Typen​

YARP Reverse Proxy​

Beispiel: api.servicebytogether.at
Framework: .NET 6+ (bevorzugt .NET 10 LTS)
Packages: Yarp.ReverseProxy

Service-with-Frontend​

Beispiel: tis.gf.wgp (mit webclient)
Zusätzliche Ordner:
├── webclient/ # Frontend Code
│ └── dist/ # Build Output

.NET Framework Standards & Packages​

Framework-Versionen (MUSS)​

Ein Projekt MUSS eine LTS-Version verwenden:

  • ✅ .NET 10.0 LTS (aktueller Standard für neue Projekte)
  • ✅ .NET 8.0 LTS (bestehende Projekte)
  • ✅ .NET 6.0 LTS (bestehende Projekte)
  • ❌ .NET 7.0, .NET 9.0 — Non-LTS-Versionen SOLLTEN NICHT verwendet werden, und nur in begründeten Ausnahmefällen

Projekt-Konfiguration (LTS Standard):

<PropertyGroup>
<TargetFramework>net10.0</TargetFramework> <!-- LTS Version -->
<LangVersion>latest</LangVersion>
<Nullable>enable</Nullable> <!-- Modern Standard -->
<ImplicitUsings>enable</ImplicitUsings>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

Standard-Package-Dependencies​

TIS Platform Basis:

<!-- TIS Hosting & Logging (aktuelle Versionen mit .NET 10 Kompatibilität) -->
<PackageReference Include="Tis.Hosting.Extensions.Nlog" Version="10.0.*" />

<!-- Modern OpenAPI (.NET 10 LTS kompatibel) -->
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.*" />
<PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="10.0.*" />

Feature Management

<!-- Feature Flags (moderne TIS APIs) -->
<PackageReference Include="Microsoft.FeatureManagement.AspNetCore" Version="4.*" />

Datenbank & Legacy Support:

<!-- Entity Framework Core (LTS Version) -->
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.*" />

<!-- SOAP Support (für Legacy Kompatibilität) -->
<PackageReference Include="SoapCore" Version="1.1.*" />
<PackageReference Include="System.ServiceModel.Http" Version="10.*" />

Konfigurationsdateien​

Project Files (.csproj)​

Standardeinstellungen:

<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
<NoWarn>1701;1702;CS1591</NoWarn>
</PropertyGroup>

Solution (.sln)​

  • Ein Service SOLLTE genau eine Solution haben
  • Alle verwandten Projekte SOLLTEN eingebunden sein
  • Der Solution Explorer SOLLTE eine klare Ordnerstruktur zeigen

Directory.Build.props​

Zentrale Build-Konfiguration für:

  • Versionierung (MinVer)
  • NuGet Package Metadata
  • Shared Dependencies

Deployment-Struktur​

artifacts/ Ordner​

  • Build-Ausgabe
  • Generated Contracts
  • WebDeploy Packages

Konventionen (MUSS / SOLLTE)​

Namenskonventionen (MUSS)​

Namen MÜSSEN diesen Mustern folgen:

  • Solution: [ServiceName].Api.sln (PascalCase)
  • Hauptprojekt: Tis.[Servicename].Api (PascalCase)
  • Zusatzprojekte: Tis.[ServiceName].Api.* (PascalCase)

Ordnerstruktur (SOLLTE)​

  • Feature-basiert: Ordner SOLLTEN nach Geschäftslogik gruppiert sein
  • Trennung: API, Storage und Extensions SOLLTEN getrennt bleiben
  • Konsistenz: ähnliche Services SOLLTEN gleiche Namen verwenden

Versionierung (MUSS)​

  • Semantic Versioning MUSS über MinVer erfolgen
  • Tag Prefixes: v
  • (Alternativ) Tag Prefixes: service-v für Services, contracts-v für Contracts (sofern eine Trennung zwischen Service und Contract-Version notwendig ist)
  • Prerelease: Automatisch für Feature Branches

Beispiel-Implementierungen​

⭐ Template für neue API-Projekte: tis.gf.boaapi​

Empfohlen für: Neue API-Services mit modernen Standards

Charakteristika:

  • ✅ Minimal Setup - Nur notwendige Dependencies
  • ✅ Moderne Patterns - .NET 10, Minimal APIs, Extensions Pattern
  • ✅ TIS Hosting Integration - Tis.Hosting.Extensions für Standardkonfiguration
  • ✅ OAuth2 Introspection - Moderne Authentication mit Identity Server
  • ✅ Clean Architecture - Klar getrennte Extension-Pattern für Services
  • ✅ Feature Management - Microsoft.FeatureManagement integriert
  • ✅ Polly Resilience - HTTP Client Retry Patterns

Projektstruktur:

tis.gf.boaapi/
├── src/tis.gf.boaapi/
│ ├── Program.cs # Minimaler Program.cs mit Extension
│ ├── Extensions/
│ │ └── TisHostingApplicationBuilderExtensions.cs # Service Configuration
│ ├── ExampleCode/
│ │ └── Extensions/
│ │ └── TisGfBoaApiWebHostExtensions.cs # Endpoint Mapping
│ ├── Constants.cs # Authorization Policies
│ └── appsettings.json # Standard TIS Configuration
├── azure-pipelines.yml # Standard CI/CD mit IIS Deployment
└── Tis.Gf.BoaApi.sln # Single Project Solution

Key Dependencies (minimale):

<PackageReference Include="Microsoft.FeatureManagement.AspNetCore" Version="4.*" />
<PackageReference Include="Microsoft.Extensions.Http.Polly" Version="9.0.8" />
<PackageReference Include="Polly" Version="8.6.3" />
<PackageReference Include="Tis.Hosting.Extensions.Nlog" Version="6.0.25241.4" />

Vollständige Referenz-Implementierung: tis.identity.api​

Empfohlen für: Komplexe API-Services mit erweiterten Features

Charakteristika:

  • Vollständige Feature-Module (BenutzerApi, SessionApi, etc.)
  • Contracts Package mit OpenAPI Specs
  • Integration Tests mit Performance SLOs
  • Legacy SOAP Support
  • Multi-Environment Configuration