Skip to content

Your First Forge Application

Build a complete API project from scratch using Forge platform tools and templates.

On this page

📋 What You'll Learn

In this tutorial, you will:

  • ✅ Set up your local development environment
  • ✅ Create a new Forge API project using the SAIF CLI
  • ✅ Understand the project structure and key files
  • ✅ Run the application locally with Aspire
  • ✅ Make your first code changes
  • ✅ Explore the development workflow

Prerequisites:

  • Windows, macOS, or Linux computer
  • Basic familiarity with .NET development
  • Access to SAIF Corporation Azure DevOps

Time to complete: ~45 minutes

🎯 What We're Building

By the end of this tutorial, you'll have a working API project with:

  • A .NET API with proper authentication structure
  • Aspire orchestration for local development
  • TypeSpec API definitions
  • Infrastructure-as-code with Terraform
  • Unit and integration test projects

Step 1: Install Prerequisites

Before creating your first project, ensure you have the required tools installed.

1.1 Verify .NET SDK

Open a terminal and check your .NET version:

dotnet --version

You should see version 10.0 or later. If not, download from dot.net.

1.2 Install SAIF CLI

Follow the SAIF CLI installation guide to install the CLI tool.

Verify installation:

saif --version

1.3 Install Docker Desktop

Docker is required for running dependencies locally. See the Docker Desktop setup guide.

Step 2: Create Your Project

Now let's create a new Forge API project.

2.1 Run the Project Generator

saif new saif-api-exp --no-publish

The --no-publish flag creates the project locally without setting up Azure DevOps repositories or pipelines.

The CLI will guide you through an interactive experience, prompting you for:

  • Project ID (e.g., it-api-exp-tutorial)
  • Project display name (e.g., Tutorial API)
  • Description (e.g., My first Forge application)
  • Team email (e.g., your-team@saif.com)
  • Additional configuration options

2.3 Explore the Generated Structure

Navigate to your new project:

cd it-api-exp-tutorial

The project structure includes:

it-api-exp-tutorial/
├── src/
│   ├── Tutorial/              # Main API project
│   ├── Tutorial.AppHost/      # Aspire orchestration
│   ├── Tutorial.TypeSpec/     # API definitions
│   └── Tutorial.UnitTests/    # Unit tests
├── infra/
│   ├── api/                   # API infrastructure
│   └── auth/                  # Authentication config
├── scripts/                   # Setup scripts
└── Tutorial.sln               # Solution file

Step 3: Run Locally

Let's start the application using Aspire.

3.1 Open in Your IDE

Open the solution in Visual Studio or VS Code:

# Visual Studio
start Tutorial.sln

# VS Code
code .

3.2 Start the Aspire Host

Navigate to the AppHost directory and run:

cd src/Tutorial.AppHost
aspire run

This starts the Aspire orchestrator, which manages all your application resources.

3.3 Open the Aspire Dashboard

The terminal will display URLs. Open the Aspire Dashboard (typically http://localhost:15888).

You'll see:

  • Resources - Your API and dependencies
  • Console - Live log output
  • Traces - Request traces for debugging

3.4 Test the API

The API runs on a dynamic port shown in the dashboard. Click the endpoint link to open Swagger UI.

Try the /health endpoint to verify everything works:

curl http://localhost:{port}/health

You should see: Healthy

Step 4: Make Your First Change

Now let's modify the API to add a new endpoint.

4.1 Open the API Controller

Navigate to src/Tutorial/Controllers/ and open the main controller file.

4.2 Add a Hello Endpoint

Add a new method:

[HttpGet("hello")]
public IActionResult Hello([FromQuery] string name = "World")
{
    return Ok(new { message = $"Hello, {name}!" });
}

4.3 Test Your Change

Save the file. If hot reload is enabled, the change applies automatically. Otherwise, restart the AppHost.

Test the new endpoint:

curl "http://localhost:{port}/hello?name=Developer"

Expected response:

{ "message": "Hello, Developer!" }

🎉 Congratulations! You've made your first change to a Forge application!

Step 5: Run the Tests

Forge projects include unit and integration tests. Let's run them.

5.1 Run Unit Tests

dotnet test src/Tutorial.UnitTests

5.2 Review Test Structure

Explore the test project to understand the testing patterns used in Forge applications.

🎓 What You Learned

In this tutorial, you:

  • ✅ Installed prerequisites (SAIF CLI, Docker)
  • ✅ Created a new Forge API project
  • ✅ Explored the project structure
  • ✅ Ran the application with Aspire
  • ✅ Made code changes and tested them
  • ✅ Ran the unit tests

🚀 Next Steps

Now that you have a working project, continue your learning:

Topic Guide
Configure database CosmosDB Guide
Add event handling Event Service
Set up authentication Security Overview
Manage secrets Settings and Secrets

🔍 Troubleshooting

Docker not running

Ensure Docker Desktop is started. Check the system tray icon.

Port conflicts

If ports are in use, stop other applications or modify the AppHost configuration.

CLI not found

Ensure SAIF CLI is installed and your terminal has the updated PATH. Try opening a new terminal window.