Grad.CsLib 2.0.18

CsLib Core Package

This package contains utilities for C# API projects.

This package is very opinionated, as it's intended for Graduate College API projects:

• FastEndpoints is used, which is a thin layer on top of .NET Core minimal APIs.
• OpenAPI/Swagger docs are generated from endpoint definitions and XML documentation. The JSON is exported to the /spec folder for generating client libraries.
  • Kiota is used to generate the OpenAPI JSON, but not the client libraries.
• Authentication is through Entra.

For local development scenarios where involving Entra isn't desirable, CsLib also provides an opt-in combined authentication mode that accepts a simple Api-Key header (see AddAuthAzureAdOrDevApiKey()).

Requirements

• .NET Core 10

Dependencies

Outside of Microsoft packages, these are the main dependencies:

• FastEndpoints
• Mapperly
• Serilog

CsLibWeb

Here's an example of how to set up a Program.cs file for a web API project:

using ExampleData;
using ExampleServer;
using FastEndpoints.ClientGen.Kiota;
using Grad.CsLib;
using Grad.CsLib.ClientErrorLogging;
using Microsoft.EntityFrameworkCore;
using Serilog;

var builder = WebApplication.CreateBuilder(args);

builder.AddSwagger(args, "ExampleServer", "0.0.1", "Example Backend Server");

builder
 .AddSerilog()
 .AddCors()
 .AddAuth();
builder.Services
 .AddDbContext<ExampleContext>(options =>
 options.UseSqlServer(
 builder.Configuration.GetConnectionString("Example")))
 .AddAuthorization(AuthPolicy.AddAuthPolicy)
 .RegisterServicesFromExampleServer();

builder.AddEndpoints(DiscoveredTypes.All);

try
{
 var app = builder.BuildAndConfigureApp(b => b.ReflectionCache.AddFromExampleData().AddFromExampleServer());

 // Optional: Add client-side error logging endpoint
 app.MapClientErrorLogging("/api/client-errors");

 // This is only run with the --exportswaggerjson option
 await app.ExportSwaggerJsonAndExitAsync("ExampleServer", "../spec");

 app.Run();
}
catch (Exception ex)
{
 Log.Fatal(ex, "Application start-up failed");
}
finally
{
 Log.CloseAndFlush();
}

Development API key (optional)

If you want to allow a development-only API key as an alternative to Entra, replace AddAuth() with:

builder
 .AddSerilog()
 .AddCors()
 .AddAuthAzureAdOrDevApiKey();

Configure the expected key in configuration (for example via appsettings.Development.json):

{
 "CsLibWeb": {
 "DevApiKey": "your-dev-key"
 }
}

When the request includes the Api-Key header, API key authentication is used; otherwise CsLib falls back to Entra bearer authentication.

Client-Side Error Logging

CsLib provides a convenient endpoint for logging client-side errors. This allows frontend applications to send error information to the backend for centralized logging and analysis.

For detailed documentation, see .

Quick example:

// In Program.cs, after building the app
app.MapClientErrorLogging("/api/client-errors");

This creates an anonymous POST endpoint that accepts client errors with validation for error type, message, stack trace, and contextual data. All errors are logged to Serilog for collection by Splunk.