Kull.GenericBackend
2.2.0-beta6
See the version list below for details.
dotnet add package Kull.GenericBackend --version 2.2.0-beta6
NuGet\Install-Package Kull.GenericBackend -Version 2.2.0-beta6
<PackageReference Include="Kull.GenericBackend" Version="2.2.0-beta6" />
paket add Kull.GenericBackend --version 2.2.0-beta6
#r "nuget: Kull.GenericBackend, 2.2.0-beta6"
// Install Kull.GenericBackend as a Cake Addin #addin nuget:?package=Kull.GenericBackend&version=2.2.0-beta6&prerelease // Install Kull.GenericBackend as a Cake Tool #tool nuget:?package=Kull.GenericBackend&version=2.2.0-beta6&prerelease
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
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;
// ...
public void ConfigureServices(IServiceCollection 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()
.AddSystemParameters();
// 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();
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseSwagger(o =>
{
// Depending on your client, set this to true (eg, ng-swagger-gen)
o.SerializeAsV2 = false;
});
app.UseRouting();
app.UseEndpoints(endpoints =>
{
app.UseGenericBackend(endpoints);
endpoints.MapControllerRoute("default", "{controller=Home}/{action=Index}/{id?}");
});
// 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.
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 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. Built-in are the following System Parameters:
- ADLogin & NTLogin: The Username in the HttpContext
- IPAddress: The IP Adress of the User
- UserAgent: The UserAgent of the Browser
If you would like to add something to this, or remove the default ones, you can do this in startup.cs:
.AddSystemParameters(prms=>
{
prms.Clear();
//Usually you will want to set global system parameters
prms.AddSystemParameter("UserClaims", c => Newtonsoft.Json.JsonConvert.SerializeObject(c.User.Claims));
//But if you want one for just one SP, you can do this by using the dot
prms.AddSystemParameter("SchemaName.ProcecureName.ParameterNameInThere", c => c.GetType().ToString());
});
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 in theory, 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
Possible futher development
- Direct manipulation of views without Stored Procedures (while staying secure)
- Support for other databases, eg Sqlite for Testing (Sqlite requires View support)
- Support for Return Codes, though the benefit seems reasonable
- Even More Unit Tests
Product | Versions 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. |
.NET Core | netcoreapp3.1 is compatible. |
.NET Framework | net48 is compatible. net481 was computed. |
-
.NETCoreApp 3.1
- Kull.Data (>= 6.0.1)
- Kull.DatabaseMetadata (>= 1.4.1)
- Swashbuckle.AspNetCore.SwaggerGen (>= 6.2.3)
-
.NETFramework 4.8
- Kull.Data (>= 6.0.1)
- Kull.DatabaseMetadata (>= 1.4.1)
- Kull.MvcCompat (>= 0.2.1)
- Microsoft.AspNet.Mvc (>= 5.2.7)
- Microsoft.OpenApi (>= 1.2.3)
- Swashbuckle.Core (>= 5.6.0)
- Unity (>= 5.11.9)
-
net6.0
- Kull.Data (>= 6.0.1)
- Kull.DatabaseMetadata (>= 1.4.1)
- Swashbuckle.AspNetCore.SwaggerGen (>= 6.2.3)
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 | 179 | 12/4/2023 |
2.5.4 | 1,118 | 11/29/2022 |
2.5.3 | 307 | 11/29/2022 |
2.5.2 | 298 | 11/29/2022 |
2.5.1 | 323 | 11/29/2022 |
2.5.0 | 365 | 11/22/2022 |
2.4.2 | 413 | 11/18/2022 |
2.4.1 | 418 | 11/17/2022 |
2.4.0-beta5 | 225 | 9/22/2022 |
2.4.0-beta4 | 133 | 9/22/2022 |
2.4.0-beta3 | 161 | 9/8/2022 |
2.4.0-beta2 | 178 | 7/19/2022 |
2.4.0-beta1 | 150 | 7/19/2022 |
2.3.0 | 848 | 7/1/2022 |
2.2.0-beta9 | 146 | 6/14/2022 |
2.2.0-beta8 | 416 | 5/27/2022 |
2.2.0-beta7 | 180 | 5/4/2022 |
2.2.0-beta6 | 182 | 2/17/2022 |
2.2.0-beta4 | 162 | 2/17/2022 |
2.2.0-beta3 | 207 | 1/19/2022 |
2.2.0-beta2 | 244 | 1/18/2022 |
2.2.0-beta1 | 165 | 1/14/2022 |
2.1.4 | 770 | 1/13/2022 |
2.1.3 | 466 | 1/12/2022 |
2.1.2 | 606 | 1/11/2022 |
2.1.1 | 852 | 12/3/2021 |
2.1.0 | 991 | 12/3/2021 |
2.1.0-beta1 | 736 | 12/1/2021 |
2.0.3 | 328 | 12/1/2021 |
2.0.2 | 322 | 12/1/2021 |
2.0.1 | 304 | 12/1/2021 |
2.0.0 | 308 | 11/30/2021 |
2.0.0-beta9 | 4,906 | 11/24/2021 |
2.0.0-beta8 | 233 | 11/13/2021 |
2.0.0-beta7 | 364 | 10/25/2021 |
2.0.0-beta6 | 206 | 10/25/2021 |
2.0.0-beta5 | 258 | 10/25/2021 |
2.0.0-beta4 | 195 | 10/6/2021 |
2.0.0-beta3 | 231 | 10/5/2021 |
2.0.0-beta2 | 241 | 9/30/2021 |
1.5.3 | 430 | 8/13/2021 |
1.5.2 | 365 | 8/11/2021 |
1.5.1 | 403 | 8/9/2021 |
1.5.0 | 478 | 8/1/2021 |
1.4.4 | 478 | 8/1/2021 |
1.4.3 | 445 | 7/29/2021 |
1.4.2 | 526 | 4/13/2021 |
1.4.1 | 381 | 4/13/2021 |
1.4.0 | 398 | 4/6/2021 |
1.3.9 | 401 | 2/11/2021 |
1.3.8 | 549 | 1/25/2021 |
1.3.7 | 416 | 1/15/2021 |
1.3.6 | 422 | 1/15/2021 |
1.3.5 | 536 | 12/8/2020 |
1.3.4 | 462 | 12/8/2020 |
1.3.2 | 641 | 9/9/2020 |
1.3.1 | 527 | 9/9/2020 |
1.3.0 | 511 | 8/19/2020 |
1.2.4 | 530 | 8/18/2020 |
1.2.3 | 563 | 8/12/2020 |
1.2.2 | 488 | 8/12/2020 |
1.2.1 | 519 | 7/16/2020 |
1.2.0 | 521 | 7/16/2020 |
1.1.0 | 629 | 6/1/2020 |
1.1.0-beta3 | 343 | 5/25/2020 |
1.1.0-beta2 | 324 | 5/20/2020 |
1.1.0-beta1 | 312 | 5/20/2020 |
1.1.0-alpha3 | 333 | 5/20/2020 |
1.1.0-alpha2 | 334 | 5/20/2020 |
1.1.0-alpha1 | 331 | 5/20/2020 |
1.0.0-rc3 | 321 | 5/19/2020 |
1.0.0-rc2 | 323 | 5/14/2020 |
1.0.0-rc1 | 286 | 5/14/2020 |
1.0.0-beta3 | 336 | 5/6/2020 |
1.0.0-beta2 | 338 | 5/4/2020 |
1.0.0-beta1 | 354 | 4/30/2020 |
0.15.4 | 644 | 3/18/2020 |
0.15.3 | 590 | 3/18/2020 |
0.14.2 | 630 | 11/22/2019 |
0.14.1 | 1,209 | 10/2/2019 |
0.13.5 | 614 | 9/25/2019 |
0.13.4 | 613 | 9/12/2019 |
0.13.3 | 579 | 9/11/2019 |
0.13.2 | 581 | 9/10/2019 |
0.13.1 | 597 | 9/10/2019 |
0.13.0 | 646 | 8/14/2019 |