Quick Start Guide

Goal: In under one hour, you'll create a working API application with automatic database migrations and event-driven business logic.

What we'll build: A simple Task Management API with tasks, projects, and automatic task numbering.

---

Prerequisites

Before you start, ensure you have:

• .NET 10.0 SDK installed (Download here)
• Visual Studio 2026 or VS Code with C# extension
• PostgreSQL database running locally
  • To install, run: winget install postgresql -s winget
  • For a nice PostgresSQL UI, you can install this extension in VS Code: PostgreSQL for Visual Studio Code
• Basic C# knowledge (classes, properties, attributes)

Build your first Benevia Core application

Step 1: Connect to the Benevia NuGet source

The following steps need to be done once on your computer.

1. Verify access to the repo: Benevia NuGet. If you don't, get access from Benevia's support.

2. Get a classic PAT from GitHub settings. Set the expiration to your preference. Select read:packages scope. Generate the PAT.

   

3. Run this command to add the NuGet source (Replacing YourGithubUsername and GithubPAT):

dotnet nuget add source --username YourGithubUsername --password GithubPAT --store-password-in-clear-text --name github-packages "https://nuget.pkg.github.com/beneviasoftware/index.json"

Step 2: Download the Benevia Core template

This only needs to be run once on your computer. However, if you want the latest template, you can re-run it. Install the Benevia.Templates package using the .NET CLI:

dotnet new install Benevia.Templates

Step 3: Create your solution with the Benevia Core Template

Replace MyNewApp with your app's name. Run

dotnet new benevia -n MyNewApp

Run your app

Build and run your app. Your app is a server with an API.

Check your app: https://localhost:7086/index.html or http://localhost:5205/index.html this will show a Swagger UI.

Using Postman as a client

1. Sign in to get a token (The API uses JWT authentication)
   GET http://localhost:5205/API/Auth/Signin or GET https://localhost:7086/API/Auth/Signin Body (Replace ServerApp with your app's name)

{
    "Username":"Admin",
    "Password":"Admin@123",
    "TenantId":"ServerApp"
}

Response:

{
    "message": "User signed in successfully.",
    "username": "admin",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnRJZCI6IlNlcnZlckFwcCIsInVzZXJJZCI6IjQ1ZWQ5MzM1LTBhMmQtNGUxMC04OThlLWQ1Y2Y1MmZjODAwOCIsIm5iZiI6MTc2OTAzNTc4MCwiZXhwIjoxNzY5MDM3NTgwLCJpYXQiOjE3NjkwMzU3ODAsImlzcyI6ImJlbmV2aWFzb2Z0d2FyZSIsImF1ZCI6ImJlbmV2aWFzb2Z0d2FyZSJ9.zlEMwf9O_3EFAOBxIBsSRB9xeuQHyGMnikRxloyS9xI",
    "refreshToken": "6JqA9PZqESxRkkKAbePhq2njiNuJeZyfvgBxiDsYNgI="
}

2. All requests thereafter, use bearer authentication with the token returned in the sign in. See Basic Tutorial · OData

   GET https://localhost:5205/api/Author?$select=Guid,Title,Id,Name,Bio,Email,ArticleCount
   

   Response:

   {
       "@odata.context": "http://localhost:5205/api/$metadata#Author(Guid,Title,Id,Name,Bio,Email,ArticleCount)",
       "value": [
           {
               "Guid": "30e83f1f-b927-40e8-8b5b-dcc59866cf5b",
               "ArticleCount": 2,
               "Title": "John Doe(JOHDOE)",
               "Id": "JOHDOE",
               "Name": "John Doe",
               "Bio": "Financial expert with over 10 years of experience in cryptocurrency and digital currencies.",
               "Email": "john.doe@example.com"
           },
           {
               "Guid": "8a5f4be7-cebb-4071-9292-6a8f8d2bd07b",
               "ArticleCount": 1,
               "Title": "Dr. Sarah Brown(DRSARBRO)",
               "Id": "DRSARBRO",
               "Name": "Dr. Sarah Brown",
               "Bio": "Health and wellness expert dedicated to promoting healthy lifestyles.",
               "Email": "sarah.brown@example.com"
           }
   }
   

What does creating a solution from the Benevia template do?

• Creates a solution and a server app project
• Adds Benevia Core NuGet dependencies
• Adds Benevia Core source generators which generates partial classes for the entities, the OData API, and the logic containers for business logic.
• Global usings for ASP.NET, etc.
• Creates sample (All of which can be replaced with your entities, logic, etc.) ...
  • Model. See 'Models' folder.
  • Business logic. See 'BLs' folder.
  • Code that creates demo data. See 'BLs\SeedData.cs'
  • An optional sample API Controller. See 'Controllers\ArticleController'
• Sets up services. See Program.cs
• Defines settings for first login account, connection string, JWT info, and data creation info. See appsettings.json.

What happens when your server app starts up

1. Database: If the database is not created, it will create the database. New entities will be created based on your appsettings.json (BlankData or DemoData). If the database already exists, it will check any changes in the model and apply that. If there are upgrade subscribers, those subscribers will run.

Next Steps

• Create your own entities and properties.
• Interact with the API through Odata.
• Write business logic subscribers.

Troubleshooting

"Cannot connect to database"

• Ensure PostgreSQL is running
• Check connection string in appsettings.json
• Test: psql -h localhost -U postgres

"Type or namespace not found"

• Run dotnet restore
• Check that NuGet packages are added
• Verify project references are correct

"Partial property must have implementation"

• Properties marked partial get generated implementations
• Ensure you're building the solution (not just the file)
• Check for build errors in generator projects

"Migration fails"

• Delete database and retry: DROP DATABASE ServerApp;
• Check entity configurations
• Look at generated migration in Migrations/ folder

Business logic not firing

• Ensure assemblies are registered in Program.cs.

  • Example: chsarp builder.Services.AddServerAppBL() (Replace 'ServerApp' with your project name)

• Check that logic class has [Logic] attribute and that methods have [RegisterLogic] attribute

• Look for runtime errors in console.

Happy coding! 🚀