Kull.GenericBackend 2.5.4

There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Kull.GenericBackend --version 2.5.4
                    
NuGet\Install-Package Kull.GenericBackend -Version 2.5.4
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Kull.GenericBackend" Version="2.5.4" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Kull.GenericBackend" Version="2.5.4" />
                    
Directory.Packages.props
<PackageReference Include="Kull.GenericBackend" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Kull.GenericBackend --version 2.5.4
                    
#r "nuget: Kull.GenericBackend, 2.5.4"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Kull.GenericBackend@2.5.4
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Kull.GenericBackend&version=2.5.4
                    
Install as a Cake Addin
#tool nuget:?package=Kull.GenericBackend&version=2.5.4
                    
Install as a Cake Tool

The Kull Generic Backend

This package allows Integration of a generic Stored Procedure-based Backend to Asp.Net MVC Core It uses Swashbuckle, Version 5+

Nearly everything can be customized. It's designed to be extensible.

Installation

NuGet Badge

It's on Nuget: https://www.nuget.org/packages/Kull.GenericBackend/ Basically, just use:

dotnet add package Kull.GenericBackend

Configuration

In Startup.cs, add the following services:

using Kull.GenericBackend;
// ...

var services = builder.Services;
services.AddMvcCore().AddApiExplorer(); //Or AddMvc() depending on your needs
services.AddGenericBackend()
    .ConfigureMiddleware(m =>
    { // Set your options
        m.AlwaysWrapJson = true; // Recommended
        m.RequireAuthenticated = true; // default since 2.0. for local development, you might want to use false
    })
    .ConfigureOpenApiGeneration(o =>
    { // Set your options
    })
    .AddFileSupport()
    //.AddXmlSupport() if needed
    .AddSystemParameters(); // You probably want to configure these, see https://github.com/Kull-AG/kull-generic-backend/wiki/System-Parameters
	
// You might have to register your Provider Factory
if (!DbProviderFactories.TryGetFactory("Microsoft.Data.SqlClient", out var _))
        DbProviderFactories.RegisterFactory("Microsoft.Data.SqlClient", Microsoft.Data.SqlClient.SqlClientFactory.Instance);
	
// IMPORTANT: You have to inject a DbConnection somehow
services.AddTransient(typeof(DbConnection), (s) =>
{
    var conf = s.GetRequiredService<IConfiguration>();
    var constr = conf["ConnectionStrings:DefaultConnection"];
    return new Microsoft.Data.SqlClient.SqlConnection(constr);
});
services.AddSwaggerGen(c=> {
	c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
	c.AddGenericBackend();
});

//...
var app = builder.Build();
//...


app.UseSwagger(o =>
{
// Depending on your client, set this to true (eg, ng-swagger-gen)
    o.SerializeAsV2 = false;
});
app.UseRouting();
app.UseGenericBackend(); 

// If needed, Swagger UI, see https://github.com/domaindrivendev/Swashbuckle.AspNetCore
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

In a File called backendconfig.json, set the URI's:

{
   "$schema": "https://raw.githubusercontent.com/Kull-AG/kull-generic-backend/master/backendconfig.schema.json",
   "Entities": {
        "Cases": {
            "Get": "api.spGetSomeCases"
        },
        "Cases/{CaseId|int}/Brands": {
            "Get": "api.spGetBrands",
            "Post": {
                "SP": "api.spAddUpdateBrands",
                "OperationId": "AddOrUpdateBrands",
                "IgnoreParameters":["AParameterMyApiDoesnotCare"],
                "ExecuteParameters": {
                    "ParamterName": "Set this object for strange cases where SQL Server does not return meta",
                    "AnotherParamter": "Be sure not to edit any data."
                }
            }
        },
        "Sample": {
            "GET": {
                "View": "dbo.[use a view if you want]" //  (currently readonly, get only)
            }
        },
        "SampleFunction": {
            "GET": {
                "Function": "dbo.[use a table valued function if you want]" //  (currently readonly, get only)
            }
        }
    }
}

You can place this in appsettings.json as well if you don't like a separate file. However having a separate file seems more appropriate here as it enables IntelliSense with VS Code. Also you usually do not have different configs per environment for this file.

In the "Entities" Section, the URL's are configured. Each entry correspondends to a URL. Each URL can be accessed by multiple HTTP Methods. Common methods are:

  • GET for getting data, shoud NEVER update something
  • POST for adding/updating. Maybe misused for getting data if the url gets longer then 2000 chars otherwise), but then set the OperationId as seen above
  • PUT for updating data
  • DELETE for deleting data

In the URL there can be route constraints as in MVC, however the | is used instead of : because of limitations of appsettings.json For a full documentation of allowed route constraints, please see here

For best practices for defining a REST Api, see here

Further features

For usage on Output Parameters, Table Valued Parameters and multiple Result Sets, view the wiki

Main parts of the generic API

Middleware for handling the requests

The main part of the project is the Middleware that handles stored procedures. It is responsible for handling a request against some URL defined in the Entities Section, as seen above.

Middleware for Swagger

The other part is the middleware that is responsible for generating a swagger.json file out of the information of the database. This is done by using the sp_describe_first_result_set and INFORMATION_SCHEMA.parameters. There is a separate Package for the Metadata: Kull-AG/kull-databasemetadata

It works by adding an IDocumentFilter to Swashbuckle. Swashbuckle generates the swagger.json/openapi.json This means you can mix this backend and your own Controllers and it will just work in the swagger.json.

Special parameters

There are so called System Parameters, which are parameters defined in any Stored Procedure which should be resolved by the Webserver and not by the Consumer of the API.

More info here in the wiki

Error Handling

In order to inform the client about an error, use RAISERROR('SOMEERROR', 16,1,1); If there is another exception on the server, code 500 is sent whenever possible. However, when the error occurs during execution and not right at the start, the response will be aborted and the status code cannot be guaranteed. In this case the result will be invalid JSON.

If you want to set the status code, use throw with code 50000 + Http Status Code between 400 and 599:

throw 50503, 'No access to this', 1 

.Net 4.8

It works, but requires a lot of #if's and is not integration-tested. It's used in a number of projects though and does it's job. See wiki

.Net Core is definitely the way to go, .Net 4.8 support is mainly to make porting to .Net Core easier.

Performance

The performance should be very good as for the invocation very few Reflection is needed (if at all). Of course as this is IO-Bound/Database-Bound Code in practice the main bottleneck will be the database and the network. Meanwhile the Generic Backend should be as fast as it gets.

Possible futher development

  • Direct manipulation of views without Stored Procedures (while staying secure)
  • Support for other databases, eg. Sqlite for Testing (Might works already, tests pending)
  • Even More Unit Tests
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp3.1 is compatible. 
.NET Framework net48 is compatible.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (3)

Showing the top 3 NuGet packages that depend on Kull.GenericBackend:

Package Downloads
Kull.GenericBackend.OData

Package Description

Kull.GenericBackend-Sanitizer

Package Description

Kull.GenericBackend.Sanitizer

Package Description

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.6.0-alpha 262 12/4/2023
2.5.4 1,795 11/29/2022
2.5.3 381 11/29/2022
2.5.2 377 11/29/2022
2.5.1 398 11/29/2022
2.5.0 466 11/22/2022
2.4.2 513 11/18/2022
2.4.1 503 11/17/2022
2.4.0-beta5 293 9/22/2022
2.4.0-beta4 208 9/22/2022
2.4.0-beta3 237 9/8/2022
2.4.0-beta2 260 7/19/2022
2.4.0-beta1 229 7/19/2022
2.3.0 932 7/1/2022
2.2.0-beta9 230 6/14/2022
2.2.0-beta8 632 5/27/2022
2.2.0-beta7 267 5/4/2022
2.2.0-beta6 271 2/17/2022
2.2.0-beta4 265 2/17/2022
2.2.0-beta3 297 1/19/2022
2.2.0-beta2 338 1/18/2022
2.2.0-beta1 273 1/14/2022
2.1.4 957 1/13/2022
2.1.3 563 1/12/2022
2.1.2 714 1/11/2022
2.1.1 951 12/3/2021
2.1.0 1,090 12/3/2021
2.1.0-beta1 830 12/1/2021
2.0.3 428 12/1/2021
2.0.2 425 12/1/2021
2.0.1 400 12/1/2021
2.0.0 410 11/30/2021
2.0.0-beta9 5,000 11/24/2021
2.0.0-beta8 343 11/13/2021
2.0.0-beta7 468 10/25/2021
2.0.0-beta6 300 10/25/2021
2.0.0-beta5 352 10/25/2021
2.0.0-beta4 295 10/6/2021
2.0.0-beta3 337 10/5/2021
2.0.0-beta2 341 9/30/2021
1.5.3 536 8/13/2021
1.5.2 463 8/11/2021
1.5.1 504 8/9/2021
1.5.0 576 8/1/2021
1.4.4 574 8/1/2021
1.4.3 544 7/29/2021
1.4.2 629 4/13/2021
1.4.1 490 4/13/2021
1.4.0 510 4/6/2021
1.3.9 519 2/11/2021
1.3.8 665 1/25/2021
1.3.7 532 1/15/2021
1.3.6 532 1/15/2021
1.3.5 650 12/8/2020
1.3.4 583 12/8/2020
1.3.2 756 9/9/2020
1.3.1 641 9/9/2020
1.3.0 621 8/19/2020
1.2.4 640 8/18/2020
1.2.3 670 8/12/2020
1.2.2 624 8/12/2020
1.2.1 635 7/16/2020
1.2.0 632 7/16/2020
1.1.0 745 6/1/2020
1.1.0-beta3 464 5/25/2020
1.1.0-beta2 439 5/20/2020
1.1.0-beta1 424 5/20/2020
1.1.0-alpha3 449 5/20/2020
1.1.0-alpha2 447 5/20/2020
1.1.0-alpha1 450 5/20/2020
1.0.0-rc3 438 5/19/2020
1.0.0-rc2 434 5/14/2020
1.0.0-rc1 411 5/14/2020
1.0.0-beta3 460 5/6/2020
1.0.0-beta2 454 5/4/2020
1.0.0-beta1 466 4/30/2020
0.15.4 763 3/18/2020
0.15.3 705 3/18/2020
0.14.2 771 11/22/2019
0.14.1 1,335 10/2/2019
0.13.5 735 9/25/2019
0.13.4 739 9/12/2019
0.13.3 699 9/11/2019
0.13.2 705 9/10/2019
0.13.1 724 9/10/2019
0.13.0 773 8/14/2019