Zum Hauptinhalt springen

TIS API Development Guide - Projektstruktur

🤖 Generated with Claude Code

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 (TIS Standard)​

Regel: Ausschließlich LTS-Versionen 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 nur in 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)​

  • Eine Solution pro Service
  • Alle verwandten Projekte eingebunden
  • Klare Ordnerstruktur in Solution Explorer

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

Best Practices​

Namenskonventionen​

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

Ordnerstruktur​

  • Feature-basiert: Gruppierung nach Geschäftslogik
  • Trennung: API, Storage, Extensions getrennt
  • Konsistenz: Gleiche Namen zwischen ähnlichen Services

Versionierung​

  • Semantic Versioning über MinVer
  • 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