AutoBackend.SDK
0.1.9
dotnet add package AutoBackend.SDK --version 0.1.9
NuGet\Install-Package AutoBackend.SDK -Version 0.1.9
<PackageReference Include="AutoBackend.SDK" Version="0.1.9" />
paket add AutoBackend.SDK --version 0.1.9
#r "nuget: AutoBackend.SDK, 0.1.9"
// Install AutoBackend.SDK as a Cake Addin #addin nuget:?package=AutoBackend.SDK&version=0.1.9 // Install AutoBackend.SDK as a Cake Tool #tool nuget:?package=AutoBackend.SDK&version=0.1.9
AutoBackend
DEVELOPER BUILDS | RELEASE BUILDS |
---|---|
This package provides infrastructure templates for facilitating the creation of backend services. It is a personal project without a commercial foundation and offers no guarantees regarding future development.
Features
Initialization
A sample usage scenario is available here. Copies of those samples are also provided.
Initialize AutoBackend from your Program.cs file
using AutoBackend.Sdk;
await new AutoBackendHost<Program>().RunAsync(args);
Define models to represent your domain relationships
Refer to the sample project models for examples.
public class Budget
{
public Guid Id { get; set; }
//..
}
public class Transaction
{
public Guid Id { get; set; }
//..
}
public class TransactionVersion
{
//..
}
public class User
{
public long Id { get; set; }
//..
}
public class Participating
{
public long UserId { get; set; }
public Guid BudgetId { get; set; }
//..
}
Configuration of all features is detailed below
Database
Currently supported relational databases (including in-memory) are:
- SqlServer
- Postgres
AutoBackend.SDK will generate tables and establish relationships for your configured entities.
Schema Modeling
There are typically three types of database tables:
- Keyless,
- Single-column primary key,
- Multi-column primary key.
Depending on the number of columns in your entity, follow the instructions below to enable AutoBackend.SDK to track changes.
Keyless Entities
Use the [GenericEntity]
attribute to designate a model as a keyless entity.
[GenericEntity]
public class TransactionVersion
{
//...
}
Single-PK Entities
Use the [GenericEntity(<primary key property name>)]
attribute to designate a model as an entity with a single
property primary key.
[GenericEntity(
nameof(Id)
)]
public class Budget
{
public Guid Id { get; set; }
// ...
}
Multi-PK Entities
Use the [GenericEntity(<primary key property names>)]
attribute to designate a model as an entity with a composite
primary key.
Currently, the maximum number of properties in a composite key is 8.
It is anticipated that this limit will suffice for most use cases.
[GenericEntity(
nameof(UserId),
nameof(BudgetId)
)]
public class Participating
{
public long UserId { get; set; }
public Guid BudgetId { get; set; }
// ...
}
Providers
For database connection management, configure the "Database" section.
"Database": {
"PrimaryProvider": "InMemory",
"Providers": {
"InMemory": "InMemory database name",
"SqlServer": "SqlServer database connection string",
"Postgres": "Postgres database connection string"
}
}
The PrimaryProvider
property accepts one of the following string values:
InMemory
,SqlServer
,Postgres
.
The Providers
property must contain an object with optional properties: InMemory
, SqlServer
, or Postgres
. The
property corresponding to the chosen PrimaryProvider
value is mandatory.
Migrations
First, install Entity Framework Core Tools. You can create a new migration with one of the following commands executed from the project root directory.
dotnet ef migrations add "<your migration name>" -o Migrations/SqlServer -c SqlServerGenericDbContext
for SqlServer.
dotnet ef migrations add "<your migration name>" -o Migrations/Postgres -c PostgresGenericDbContext
for Postgres.
Alternatively, use scripts to add a new migration or to remove the last migration for both database providers.
If you opt not to have AutoBackend manage database migrations (see above), you can perform migrations manually by
executing dotnet ef database update
from the project root directory.
Migrate on Startup
If using a relational database (e.g., SqlServer or Postgres), you can configure AutoBackend to either automatically
migrate the database at application startup or not, by passing the migrateRelationalOnStartup
parameter to
the RunAsync
method where AutoBackend is initialized. For example:
await new AutoBackend.Sdk.AutoBackendHost<Program>().RunAsync(args, migrateRelationalOnStartup: true);
API
AutoBackend.SDK currently supports two types of application interfaces:
- Traditional HTTP API
- Basic GraphQL
HTTP API
Use the [GenericController]
attribute on models to generate HTTP API endpoints by AutoBackend.
❗Disclaimer
The
[GenericController]
attribute is compatible only with models also marked with[GenericEntity]
.
Response Container and Endpoints
The current and only API version is v1. API v1 supports JSON and uses the following response container format:
{
"ok": boolean,
"error_code": number,
"description": string,
"request_time_ms": number,
"result": <response object>
}
For detailed information on generated endpoints, access /swagger
.
Endpoints
The [GenericController]
attribute generates the following HTTP API endpoints:
Method | Url | Keyless | Single-PK | Multi-PK | Description |
---|---|---|---|---|---|
GET |
/api/v1/<model name> |
✔️ | ✔️ | ✔️ | Retrieve all entities of a specific model |
GET |
/api/v1/<model name>/count |
✔️ | ✔️ | ✔️ | Retrieve the count of entities of a specific model |
GET |
/api/v1/<model name>/<pk1> |
❌ | ✔️ | ❌ | Retrieve an entity with the requested primary key of a specific model |
GET |
/api/v1/<model name>/<pk1>/<pk2>/.../<pkN> |
❌ | ❌ | ✔️ | Retrieve an entity with the requested composite primary key of a model |
POST |
/api/v1/<model name> |
✔️ | ❌ | ❌ | Create a new keyless entity of a specific model |
POST |
/api/v1/<model name>/<pk1> |
❌ | ✔️ | ❌ | Create a new entity with the specified primary key of a specific model |
POST |
/api/v1/<model name>/<pk1>/<pk2>/.../<pkN> |
❌ | ❌ | ✔️ | Create a new entity with the specified composite primary key of a model |
PUT |
/api/v1/<model name>/<pk1> |
❌ | ✔️ | ❌ | Update an entity with the specified primary key of a specific model |
PUT |
/api/v1/<model name>/<pk1>/<pk2>/.../<pkN> |
❌ | ❌ | ✔️ | Update an entity with the specified composite primary key of a model |
DELETE |
/api/v1/<model name>/<pk1> |
❌ | ✔️ | ❌ | Delete an entity with the specified primary key of a specific model |
DELETE |
/api/v1/<model name>/<pk1>/<pk2>/.../<pkN> |
❌ | ❌ | ✔️ | Delete an entity with the specified composite primary key of a model |
📘Filtering Capabilities
Refer to the following section for more information on filtering.
Code Samples
[GenericEntity(
nameof(Id)
)]
[GenericController]
public class User
{
public long Id { get; set; }
// ...
}
GraphQL
Use the [GenericGqlQuery]
and [GenericGqlMutation]
attributes on models to generate GraphQL queries and *
mutations*, respectively.
❗Disclaimer
The
[GenericGqlQuery]
and[GenericGqlMutation]
attributes are compatible only with models also marked with[GenericEntity]
.
For detailed information on generated queries and mutations, access /graphql
.
Queries
The [GenericGqlQuery]
attribute generates the following GraphQL queries:
Query | Arguments | Keyless | Single-PK | Multi-PK | Description |
---|---|---|---|---|---|
all |
filter : generic filter input model |
✔️ | ✔️ | ✔️ | Retrieve all entities of a specific model |
count |
filter : generic filter input model |
✔️ | ✔️ | ✔️ | Retrieve the count of entities of a specific model |
byKey |
key : entity primary key |
❌ | ✔️ | ❌ | Retrieve an entity with the requested primary key of a model |
byKey |
key1 , key2 , ..., keyN : entity PK-set |
❌ | ❌ | ✔️ | Retrieve an entity with the requested composite primary key |
📘Filtering Capabilities
Refer to the following section for more information on filtering.
Code Samples
[GenericEntity(
nameof(Id)
)]
[GenericGqlQuery]
public class User
{
public long Id { get; set; }
// ...
}
Mutations
The [GenericGqlMutation]
attribute generates the following GraphQL mutations:
Mutation | Arguments | Keyless | Single-PK | Multi-PK | Description |
---|---|---|---|---|---|
create |
request : generic entity input model |
✔️ | ❌ | ❌ | Create a new keyless entity of a specific model |
create |
key : entity primary key, request : generic entity input model |
❌ | ✔️ | ❌ | Create a new entity with the specified primary key of a model |
create |
key1 , key2 , ..., keyN : entity PK-set, request : generic entity input model |
❌ | ❌ | ✔️ | Create a new entity with the specified composite primary key |
update |
key : entity primary key, request : generic entity input model |
❌ | ✔️ | ❌ | Update an entity with the specified primary key of a model |
update |
key1 , key2 , ..., keyN : entity PK-set, request : generic entity input model |
❌ | ❌ | ✔️ | Update an entity with the specified composite primary key |
delete |
key : entity primary key (for PK-holder entities only) |
❌ | ✔️ | ❌ | Delete an entity with the specified primary key |
delete |
key1 , key2 , ..., keyN : entity PK-set |
❌ | ❌ | ✔️ | Delete an entity with the specified composite primary key |
Code Samples
[GenericEntity(
nameof(Id)
)]
[GenericGqlMutation]
public class User
{
public long Id { get; set; }
// ...
}
Modeling
AutoBackend.SDK generates request and response models for any entity with configured HTTP API or GraphQL generation. These models include all original entity properties, unless specific properties are explicitly included in request or response models, in which case non-specified properties will be omitted.
Request Models
The [GenericRequest]
attribute defines which properties are permitted for reflection from the request model to the
entity.
Code Samples
[GenericEntity(
nameof(Id)
)]
[GenericController]
[GenericGqlQuery]
[GenericGqlMutation]
[GenericRequest(
nameof(Id),
nameof(UserId),
nameof(BudgetId),
nameof(Amount),
nameof(DateTimeUtc),
nameof(Comment),
nameof(SecretKey)
)]
public class Transaction
{
// ...
}
Response Models
The [GenericResponse]
attribute defines which properties are permitted for reflection from the response model to the
entity.
Code Samples
[GenericEntity(
nameof(Id)
)]
[GenericController]
[GenericGqlQuery]
[GenericGqlMutation]
[GenericResponse(
nameof(Id),
nameof(UserId),
nameof(BudgetId),
nameof(Amount),
nameof(DateTimeUtc),
nameof(Comment)
)]
public class Transaction
{
// ...
}
Filtering
AutoBackend.SDK generates filter models for any entity with configured HTTP API or GraphQL generation. By default, these
models include only pagination management properties. To include specific entity properties in the filter model, use
the [GenericFilter]
attribute.
Defaults
By default, two filter parameters are always available for any GET request (returning a list of entities) or GraphQL queries, to manage pagination:
skipCount
: numbertakeCount
: number
Generic
The [GenericFilter]
attribute designates a model property as filterable in the generated entity.
[GenericEntity(
nameof(Id)
)]
[GenericController]
[GenericGqlQuery]
[GenericGqlMutation]
public class Budget
{
[GenericFilter]
public Guid Id { get; set; }
[GenericFilter]
public string Name { get; set; }
[GenericFilter]
public long? OwnerId { get; set; }
// ...
}
Consequently, AutoBackend will construct a filter model with parameters that can be utilized in API endpoints
like /api/v1/<model name>
or /api/v1/<model name>/count
, and in GraphQL queries.
- API filter parameter names are generated following the pattern:
<property's camelCase-name>.<condition name>
. - GraphQL queries will have filtering models with condition properties generated.
The following conditions are supported:
equal
, notEqual
, greaterThan
, greaterThanOrEqual
, lessThan
, lessThanOrEqual
, in
, isNull
, equal
.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. 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. |
-
net8.0
- Flurl.Http (>= 4.0.2)
- HotChocolate.AspNetCore (>= 13.9.0)
- HotChocolate.Data.EntityFramework (>= 13.9.0)
- Microsoft.EntityFrameworkCore (>= 8.0.4)
- Microsoft.EntityFrameworkCore.InMemory (>= 8.0.4)
- Microsoft.EntityFrameworkCore.SqlServer (>= 8.0.4)
- Npgsql.EntityFrameworkCore.PostgreSQL (>= 8.0.2)
- NSwag.AspNetCore (>= 14.0.7)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
### Changelog Summary:
#### Enhancements:
- Released version v0.1.9 with a comprehensive range of updates.
- Implemented full filter support for GraphQL queries and mutations.
- Introduced generic request and response models with support for primitive mapping.
- Conducted refactoring of directories, mappers, and overall codebase for optimization purposes.
- Updated issue templates, code of conduct, contribution, and security guidelines.
- Added a new CODE_OF_CONDUCT.md document.
- Enhanced the example project and detailed documentation within README.md.
- Refined GitHub Actions and workflow processes.
#### Package Updates:
- Upgraded Microsoft.EntityFrameworkCore packages from 7.0.3 to 8.0.4 incrementally.
- Updated Npgsql.EntityFrameworkCore.PostgreSQL from version 7.0.3 to 8.0.2.
- Incremented NSwag.AspNetCore from 13.18.2 to 14.0.7.
- Elevated coverlet.collector version from 3.2.0 to 6.0.2.
- Updated tj-actions/changed-files from version 35 to 41.
- Target framework advanced to .NET 8.0, with associated package versions updated accordingly.
#### Bug Fixes:
- Addressed and corrected mapper errors and instituted mapper caching enhancements.
- Resolved minor refactoring issues and remedied warning notifications.
#### Documentation and Organization:
- Finalized and refined README.md documentation.
- Systematized solution documents and rectified the location of the Contributor Covenant Code of Conduct.
- Edited [sample project](src/samples/Sample)