Skip to content

README.md

Latest commit

 

History

History
240 lines (164 loc) · 11.5 KB

README.md

File metadata and controls

240 lines (164 loc) · 11.5 KB
Raw

TCSystem — C# Utility Libraries

Quality Gate Status

API documentation

TCSystemCS is a collection of reusable .NET libraries for logging, image metadata, GPS data, SQLite metadata storage, threading, and general utilities. The repository also contains two command-line tools and NUnit test projects.

Projects

Libraries

Package Purpose NuGet
TCSystem.Util General extension methods and equality/math helpers NuGet
TCSystem.Logging Serilog-based logging facade NuGet
TCSystem.MetaData Immutable image metadata models and JSON serialization NuGet
TCSystem.MetaDataDB SQLite persistence for image metadata NuGet
TCSystem.Gps Google Takeout location-history reader and lookup helpers NuGet
TCSystem.Thread Worker-thread, semaphore, and async update helpers NuGet

Library projects target netstandard2.1, net8.0, and net10.0.

Tools

Project Purpose Target
TCSystem.Tools.DBConverter Convert and validate a metadata database net10.0
TCSystem.Tools.TakeoutReader Import missing GPS coordinates from Google Takeout net10.0

Unit Tests

Test project Project under test
TCSystem.Gps.Tests TCSystem.Gps
TCSystem.MetaData.Tests TCSystem.MetaData
TCSystem.MetaDataDB.Tests TCSystem.MetaDataDB
TCSystem.Thread.Tests TCSystem.Thread
TCSystem.Util.Tests TCSystem.Util

All test projects target both net8.0 and net10.0. There is currently no dedicated TCSystem.Logging.Tests project.

Dependency Overview

  • TCSystem.Util has no external dependencies.
  • TCSystem.Logging depends on Serilog, Serilog.Enrichers.Thread, Serilog.Sinks.Async, Serilog.Sinks.Console, Serilog.Sinks.Debug, and Serilog.Sinks.File.
  • TCSystem.MetaData depends on TCSystem.Util and Newtonsoft.Json.
  • TCSystem.Thread depends on TCSystem.Logging.
  • TCSystem.Gps depends on TCSystem.MetaData and System.Text.Json.
  • TCSystem.MetaDataDB depends on TCSystem.Logging, TCSystem.MetaData, TCSystem.Thread, Microsoft.Data.Sqlite, and SQLitePCLRaw.lib.e_sqlite3 for the native SQLite bundle.
  • The tools compose these libraries through project references.

Build from Source

All commands below are intended to run from the repository root.

Prerequisites

  • .NET 10 SDK for C# 14, net10.0, and .slnx support.
  • .NET 8 runtime as well as the .NET 10 runtime to execute the complete two-framework unit-test matrix.
  • No additional workloads or external database server are required. SQLite is supplied through NuGet.

The repository does not pin an SDK with global.json. Confirm the selected SDK and installed runtimes with:

dotnet --version
dotnet --list-runtimes

Restore and Build the Complete Solution

dotnet restore TCSystem.slnx
dotnet build TCSystem.slnx --configuration Release --no-restore

The build compiles libraries for all three target frameworks, tools for net10.0, and tests for net8.0 and net10.0. Warnings are treated as errors. Compiled output is written below each project's bin/Release directory.

For an ordinary development build, omit --configuration Release (the default configuration is Debug):

dotnet build TCSystem.slnx

Build One Project

Pass a project path when only one library, tool, or test project needs to be built. For example:

dotnet build Tools/DBConverter/TCSystem.Tools.DBConverter.csproj --configuration Release

Build API Documentation

DocFX generates a searchable static site from the library projects and their XML comments:

dotnet tool restore
dotnet restore TCSystem.slnx
dotnet docfx docs/docfx.json --warningsAsErrors

The generated site is written to the ignored docs/_site directory. To build and preview it locally, use:

dotnet docfx docs/docfx.json --serve

The docs.yml workflow builds and deploys this site when changes reach main, and it can also be run manually. In the GitHub repository settings, select GitHub Actions as the Pages source. The published project site is https://tgoessler.github.io/TCSystemCS/.

Run Unit Tests

Complete Test Matrix

After the Release build above:

dotnet test TCSystem.slnx --configuration Release --no-build --no-restore

This runs every test project for both net8.0 and net10.0. To let dotnet test restore and build automatically, use the shorter command:

dotnet test TCSystem.slnx --configuration Release

One Target Framework

Use this when validating one runtime or when the .NET 8 runtime is not installed:

dotnet test TCSystem.slnx --configuration Release --framework net10.0

The SonarCloud analysis workflow uses the equivalent net8.0 test run.

One Test Project

dotnet test Gps/Tests/TCSystem.Gps.Tests.csproj --configuration Release
dotnet test MetaData/Tests/TCSystem.MetaData.Tests.csproj --configuration Release
dotnet test MetaDataDB/Tests/TCSystem.MetaDataDB.Tests.csproj --configuration Release
dotnet test Thread/Tests/TCSystem.Thread.Tests.csproj --configuration Release
dotnet test Util/Tests/TCSystem.Util.Tests.csproj --configuration Release

Append --framework net10.0 to any project command to run only one target framework. After the same configuration and target framework have already been built, append --no-build --no-restore for a faster repeat run.

Test Infrastructure

All test projects use NUnit 4, NUnit3TestAdapter, Microsoft.NET.Test.Sdk, and Coverlet MSBuild. They target net8.0 and net10.0; test source and naming conventions are defined in CodingStyle.md.

The regular MetaDataDB tests create isolated SQLite databases in the operating system's temporary directory and clean them up after each test. They require neither an external SQLite installation nor a database server.

Optional MetaDataDB Converter Fixtures

ConverterTests looks for the following legacy databases in MetaDataDB/Tests/TestData/:

  • MetaData2-v11.db
  • MetaData2-v12.db

These files are not stored in the repository. Converter cases are reported as skipped with DB file not available when the fixtures are absent; this is not a test failure.

Code Coverage

Coverlet MSBuild is referenced by every test project. To reproduce the CI coverage format for net8.0, first build Release and then run:

dotnet test TCSystem.slnx --configuration Release --no-build --no-restore --framework net8.0 -p:CollectCoverage=true -p:CoverletOutputFormat=opencover

To collect coverage for one test project, replace TCSystem.slnx with one of the test-project paths listed above. The generated, ignored reports are named coverage.net8.0.opencover.xml in the test project directories.

Run the Tools

Each tool README documents its arguments and data-safety considerations:

Maintenance

Dependency Vulnerability Audit

See SECURITY.md for the canonical vulnerability-audit command and security policy.

Clean Generated Build Output

dotnet clean TCSystem.slnx --configuration Release

If a local SonarScanner run was interrupted and later builds reference missing analyzer files, delete the ignored .sonarqube directory before rebuilding.

Coding and Contribution Guidance

NuGet Packaging

Library projects import Packaging.props for NuGet metadata, XML API documentation, symbol-package settings, and publish targets. Generated XML files are included beside the assemblies so IDEs can show documentation for public types and members. Test and tool projects import NoPackaging.props so ordinary builds do not generate or publish packages. Package versioning is defined in Version.props; IsCiBuild defaults to true and adds a timestamped -ci.* suffix. The manual nuget_deploy.yml workflow explicitly invokes the Pack and NugetPush targets and can select a stable or CI version. Do not invoke NugetPush for an ordinary local build.

CI/CD

Workflow Trigger Purpose
analyze.yml Push to develop or main; manual Release build, net8.0 tests with OpenCover output, and SonarCloud analysis
docs.yml Push to main; manual Build the DocFX site and deploy it to GitHub Pages
dotnet.yml Manual Release restore and build validation
nuget_deploy.yml Manual Release build, full test matrix, package, and NuGet publish

CI runs on windows-latest with the .NET 10 SDK. Dependabot checks NuGet packages and GitHub Actions weekly and targets develop.

License

MIT — Copyright © 2003–2026 Thomas Gößler