Skip to content

Minimal Technical Documentation: Getting an overview of the code

Jump to bottom
Adrian Ehrsam edited this page Oct 25, 2022 · 1 revision

Code Structure

The Code is structured in Folders which map to C# Namespaces.

Builder

The Generic Backend Builder which allows toggling features during initialization of a Program. Also used if you write an Extension.

Common

Contains Classes used among the project:

  • Entity: Defines a HTTP Entity which consists of one more Methods.
  • Method: A HTTP Method (GET/POST/PUT/DELETE/PATCH) for an Entity(such as "dog" or "customer" or whatever). Maps the Stored Procedure/View/Function that is to be executed

Config

Responsible for parsing the backendconfig.json file and the IConfiguration Section if used.

Error

Classes for rendering Errors/Exceptions.

Execution

Code for Database Execution. Creates the concret DbCommand instance for a specific invocation.

Filter

Built-in Filters & Interfaces used to define custom Filters.

  • IParameterInterceptor: Used to change parameters for an opteration
  • IRequestInterceptor: Used to filter out Requests if certain precondition is met. See also sample in Test

The RequestLogger class can be used to log on certain events during request lifetime. You can extend it and add it with the builder:

services.AddGenericBackend().AddRequestLogger<YourClassExtendingRequestLogger>()

The SystemParameters Filters are responsible for handling globally valid Parameters such as Identity Parameters or the like. The implementation is a pretty good example for an IParameterInterceptor

Middleware

The actual code that handles the execution of a request. For historic reason that class is named GenericSPMiddleware though the Generic Backend can now also execute Views and Functions.

Parameters

Contains a number of Parameter Utility classes, some of which are used for the integrated Filters. The Base Class for all Parameters is WebApiParameter. It contains two main properties: SqlName which is the name of the Parameter in SQL. This can be null if a parameter does not map to a SQL Parameter (rather an edge case). On the other side there is WebApiName which is the name of the Parameter in the OpenApi Spec, which can be Null, too in case the Parameter is not visible to OpenApi.

The DbApiParameter is kind of the default implementation of a WebApiParameter and is just what will be used by default. It can be replaced by one of the interceptors.

The two File Parameters (FileValueParameter and FileDescriptorParameter) work together to model files, they are used from the Filter.FileParameterInterceptor.

The SystemParameter is used by the Filter.SystemParamters Interceptor. This is an example where WebApiName will be null as the value is provided by the System and not by the user.

The TableValuedParameter will be used by GenericBackend for Table Valued Parameters - like the name tells you already.

The OutputParameter is a special case which model OUT Parameters from SQL which can be returned in Generic Backend.

Serialization

Used for generating the actual Response Body. Can be something like Json (default), Xml (not really a good thing, but why not), a File or nothing (meaning just HTTP Response Code, no content). You can also write your own Serializer if you want.

The process to determine what serializer is chosen, the following process applies:

  • It the Method has a specific ResultType specified, than the Serializer must support that ResultType. Usually that's only the case for one serializer
  • Each serializer has a method named GetSerializerPriority which returns a priority based on the Accept Header. Browsers usally send generic stuff like / which is acually supported by all serializers. Then the one with lowest priority is chosen which is usually Json. A serializer may decide not to support an Accept Header at all in which case the priority is null . It may also decide to return priority 0 which means not to look for a lower priority and force usage of that serializer.

That logic is implemented in SerializerResolver.cs

There are a number of built-in Serializers:

  • Json.Net Serializer which is included in .Net 4.8 only
  • System.Text.Json which is included in .Net Core only
  • None Serializer which does not return a body
  • Xml Serializer
  • File Serializer

A serializer is also responsible for providing the OpenApi Schema for the Result which will be called by OpenApi/Swagger. See also the IGenericSPSerializer

SwaggerGeneration

Responsible for generating the OpenApi Code using Microsoft.OpenApi

Utils

Just some small, generic helper classes

Third Party Packages

This package relies on a number of packages:

Clone this wiki locally