# Getting Started with Agility CMS and .NET

> Source: https://agilitycms.com/docs/dotNet/getting-started

This guide walks you through setting up your first Agility CMS website using .NET. By the end, you'll have a fully functional site running locally with content from your Agility CMS instance.

## Prerequisites

Before you begin, ensure you have:

- **.NET SDK 8.0 or higher** - [Download .NET](https://dotnet.microsoft.com/download)
- **Node.js** - [Download Node.js](https://nodejs.org/) (required for Tailwind CSS)
- **An Agility CMS account** - [Sign up free](https://agilitycms.com/sign-up)

## Step 1: Get Your API Keys

1. Log in to [Agility CMS](https://app.agilitycms.com)
2. Navigate to **Settings > API Keys**
3. Note down the following values:
   - **Instance GUID** - Your unique instance identifier
   - **Security Key** - Used for preview mode authentication
   - **Fetch API Key** - For accessing published content (starts with `defaultlive`)
   - **Preview API Key** - For accessing draft content (starts with `defaultpreview`)

## Step 2: Clone the Starter Repository

```bash
git clone https://github.com/agility/agilitycms-dotnet-starter.git
cd agilitycms-dotnet-starter
```

Choose your preferred starter:

```bash
# For Blazor SSR (recommended for modern apps)
cd Agility.NET.Blazor.Starter

# Or for MVC/Razor Pages (traditional approach)
cd Agility.NET.MVC.Starter
```

## Step 3: Configure Your Credentials

Create a file named `appsettings.local.json` in the project root:

```json
{
  "AppSettings": {
    "InstanceGUID": "your-instance-guid",
    "SecurityKey": "your-security-key",
    "FetchAPIKey": "defaultlive.your-fetch-api-key",
    "PreviewAPIKey": "defaultpreview.your-preview-api-key"
  }
}
```

> **Security Note**: The `appsettings.local.json` file is gitignored and won't be committed to version control. Never commit API keys to your repository.

## Step 4: Install Dependencies

```bash
# Install .NET dependencies
dotnet restore

# Install Node dependencies (for Tailwind CSS)
npm install
```

## Step 5: Run the Site

```bash
# Run with hot reload
dotnet watch
```

Your site will be available at `http://localhost:5000`.

## What's Next?

Now that your site is running, explore these topics:

### Understand the Architecture
- [How Pages Work](/docs/dotNet/how-pages-work) - Learn how Agility's sitemap drives page routing
- [How Components Work](/docs/dotNet/how-components-work) - Build reusable content modules
- [How Page Models Work](/docs/dotNet/how-page-models-work) - Define page layouts and zones

### Choose Your Starter
- [Blazor SSR Starter](/docs/dotNet/blazor-starter) - Deep dive into the Blazor implementation
- [MVC Starter](/docs/dotNet/mvc-starter) - Deep dive into the MVC/Razor Pages implementation

### Build Features
- [Fetching Content](/docs/dotNet/fetching-content) - Query content using REST and GraphQL
- [Configuration](/docs/dotNet/configuration) - Environment variables and caching

### Go to Production
- [Deploy to Azure](/docs/dotNet/deploy-to-azure) - One-click deployment guide

## Troubleshooting

### "No pages found" or blank site

1. Verify your API keys are correct in `appsettings.local.json`
2. Ensure your Agility instance has published pages
3. Check that `ChannelName` matches your sitemap channel (default: `website`)

### 403 Errors

Clear browser cookies for localhost or hard refresh (Ctrl+Shift+R / Cmd+Shift+R).

### CSS not loading

Run `npm install` to install Tailwind dependencies, then restart `dotnet watch`.

### Preview mode not working

1. Verify your `SecurityKey` is correct
2. Check the preview URL includes the correct `agilitypreviewkey` parameter
3. In development, preview mode is always enabled automatically

## Project Structure Overview

Both starters follow a similar structure:

```
├── Components/ or ViewComponents/   # Content modules
├── Models/                          # Content type definitions
├── Middleware/                      # URL redirects, caching
├── Services/                        # Agility API integration
├── appsettings.json                # Default configuration
├── appsettings.local.json          # Your API credentials (gitignored)
└── Program.cs                       # Application setup
```

See the starter-specific guides for detailed structure documentation:
- [Blazor SSR Structure](/docs/dotNet/blazor-starter#project-structure)
- [MVC Structure](/docs/dotNet/mvc-starter#project-structure)