# Your First Forge Application

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

[TOC]

---

## 📋 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:

```bash
dotnet --version
```

You should see version **10.0** or later. If not, download from [dot.net](https://dot.net).

### 1.2 Install SAIF CLI

Follow the [SAIF CLI installation guide](../development/install-saif-cli.md) to install the CLI tool.

Verify installation:

```bash
saif --version
```

### 1.3 Install Docker Desktop

Docker is required for running dependencies locally. See the [Docker Desktop setup guide](../../reference/tools/docker-desktop.md).

---

## Step 2: Create Your Project

Now let's create a new Forge API project.

### 2.1 Run the Project Generator

```bash
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:

```bash
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:

```bash
# Visual Studio
start Tutorial.sln

# VS Code
code .
```

### 3.2 Start the Aspire Host

Navigate to the AppHost directory and run:

```bash
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:

```bash
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:

```csharp
[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:

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

Expected response:

```json
{ "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

```bash
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, follow the guided path to add real capabilities:

**👉 [Build on Your App](build-on-your-app.md)** — 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](../security/index.md)                      |
| Configure database    | [Cosmos DB NoSQL](../development/data/cosmos-nosql.md)          |
| Call external APIs    | [Downstream API Calls](../development/calling-apis.md)         |
| Add event handling    | [Event Service](../development/eventing/event-service.md)      |
| Deploy your app       | [Aspire Publish](../development/aspire-publish.md)             |

---

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

---

## 📚 Related Documentation

- [SAIF CLI Reference](../development/install-saif-cli.md)
- [Aspire Overview](../../reference/tools/aspire.md)
- [Version Compatibility](../../reference/version-compatibility.md)