Your First Forge Application¶

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

On this page

📋 What You'll Learn
🎯 What We're Building
Step 1: Install Prerequisites
Step 2: Create Your Project
Step 3: Run Locally
Step 4: Make Your First Change
Step 5: Run the Tests
Step 6: From Local to Deployed
🎓 What You Learned
🚀 Next Steps
🔍 Troubleshooting
📚 Related Documentation

📋 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
✅ Publish your project to Azure DevOps and trigger its first deployment

Prerequisites:

Windows, macOS, or Linux computer
Basic familiarity with .NET development
Access to SAIF Corporation Azure DevOps, with permission to create repositories and pipelines in your team's project (needed for Step 6)

Request access before you start

Two prerequisites below are provisioning requests, not installs, and can take time to complete: Docker Desktop (via a ServiceNow request) and SAIFCorporation NuGet feed access. File both now, before you start Step 1, so they've landed by the time you need them. See Step 1.2 and Step 1.3 for details.

Time to complete: ~45 minutes for the local steps once prerequisite access is granted, plus pipeline run time for the deployment in Step 6

🎯 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
An Azure DevOps repository and registered pipelines, deployed to your first environment

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. If you haven't requested NuGet feed access yet, see Prerequisites first.

Verify installation:

saif --version

1.3 Install Docker Desktop¶

Docker is required for running dependencies locally. See the Docker Desktop setup guide for the request steps and install instructions.

1.4 Enable AI-Assisted Development (optional)¶

Forge ships an MCP server and Agent Skills that GitHub Copilot and VS Code can use to help you navigate the platform. Configure it once per machine:

saif agent init

This registers the Forge MCP server and Agent Plugins for VS Code and GitHub Copilot CLI. See AI Assistant Integration for details.

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 — including its pipeline YAML under .azdo/ — without creating the Azure DevOps repository or registering those pipelines in Azure DevOps.

Why saif-api-exp?

saif-api-exp creates an Experience-type API — the right default for APIs called directly by a frontend or another team's client, which covers most first projects. See API Type Options for the full decision guide when your own project fits a different pattern.

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.2 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.

Step 6: From Local to Deployed¶

So far, everything has run locally — saif new saif-api-exp --no-publish deliberately skipped creating an Azure DevOps repository and registering the pipelines already scaffolded under .azdo/. This step closes that gap.

6.1 Publish Your Project¶

From the project root, run:

saif publish

This reads the manifest that saif new wrote when it created the project, then:

Creates the Azure DevOps repository and pushes your local main branch to it
Registers the pipelines already scaffolded under .azdo/ (main and PR) as Azure DevOps pipeline resources
Applies branch policies and pipeline validations

For all options (including --directory), see the saif publish reference.

saif publish is safe to re-run — if a step fails partway through (for example, a pipeline creation error), running it again reuses the repository it already created instead of duplicating it.

This is different from re-running saif new

Re-running saif new would create a second, separate project and re-prompt for all its parameters. saif publish is the command that takes the project you already have and pushes it to Azure DevOps.

saif publish doesn't deploy the app by itself

saif publish pushes your code and registers the pipelines — it doesn't run them. Your application isn't deployed until the main pipeline actually runs, which happens automatically on this push or the next time you trigger/push to main (see 6.2 Verify the Deployment).

6.2 Verify the Deployment¶

Open the Azure DevOps project and confirm the repository now exists with your pushed code.
Confirm the main and PR pipelines were registered.
The main pipeline auto-triggers on the push saif publish made — if it didn't, run it manually. This is the step that actually deploys the application to your first environment (Test, per the environment flow).
Once the pipeline completes, confirm the deployment stage succeeded — that's your signal the app is live. The app's raw azurewebsites.net address isn't reachable directly; all traffic is routed through the shared Azure Front Door and APIM layer in front of it. By default, an internal API is reachable at https://app-int-test.saif.com/api/exp/<app-name>/health (see Call the API for the path pattern) — see Custom Subdomains if you need a dedicated hostname instead.

--no-publish is optional

This tutorial used --no-publish so you could inspect the project locally before deploying it. For future projects, you can skip that split and let saif new create the Azure DevOps repository and register the pipelines immediately — just omit --no-publish and answer the publish prompts as part of saif new.

🎓 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
✅ Published the project to Azure DevOps and triggered its first deployment

🚀 Next Steps¶

Now that you have a working project, follow the guided path to add real capabilities:

👉 Build on Your App — A step-by-step guide covering authentication, data, APIs, eventing, feature flags, deployment, and observability.

Or jump directly to a specific topic:

Topic	Guide
Set up authentication	Security Overview
Configure database	Cosmos DB NoSQL
Call external APIs	Downstream API Calls
Add event handling	Event Service
Add more services	Aspire Publish

🔍 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.