Setup

Prerequisites

Before you begin, ensure you have the following installed on your development machine.

Required Software

.NET 10 SDK

Download and install the .NET 10 SDK from dotnet.microsoft.com.Verify installation:

dotnet --version

Expected output: 10.0.x or higher

Git

Install Git for version control:

Windows: Download from git-scm.com
macOS: brew install git or download from git-scm.com
Linux: sudo apt-get install git (Debian/Ubuntu) or sudo yum install git (Red Hat/CentOS)

Verify installation:

git --version

Code Editor (Optional but Recommended)

Choose one of the following:

Visual Studio 2022 - Full-featured IDE with excellent C# support
Visual Studio Code - Lightweight editor with C# extension
JetBrains Rider - Cross-platform .NET IDE

For VS Code, install the C# extension:

code --install-extension ms-dotnettools.csharp

Clone the Repository

Clone the project from GitHub:

git clone https://github.com/redox11223/ServiciosWebPreliminar.git
cd ServiciosWebPreliminar

Project Structure

After cloning, you’ll see the following structure:

ServiciosWebPreliminar/
├── Controllers/           # API controllers
│   ├── CitaController.cs
│   ├── PacienteController.cs
│   ├── MedicoController.cs
│   └── EspecialidadController.cs
├── Models/                # Data models
│   ├── Entities/          # Domain entities
│   ├── Dtos/              # Data transfer objects
│   └── Enums/             # Enumerations
├── Services/              # Business logic layer
│   ├── IPacienteService.cs
│   ├── PacienteService.cs
│   └── ...
├── Properties/
│   └── launchSettings.json # Launch configuration
├── Program.cs             # Application entry point
├── appsettings.json       # Configuration
├── preliminarServicios.csproj
└── preliminarServicios.sln

Restore Dependencies

Restore NuGet packages:

dotnet restore

This will download:

Microsoft.AspNetCore.OpenApi - OpenAPI specification support
Scalar.AspNetCore - API documentation UI

Build the Project

Compile the project to verify everything is set up correctly:

dotnet build

You should see:

Build succeeded.
    0 Warning(s)
    0 Error(s)

Run the API

Start the development server:

dotnet run

The API will start on:

HTTPS: https://localhost:5001
HTTP: http://localhost:5000

Output:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:5001
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.

The first run may take longer as NuGet packages are restored and the project is compiled.

Access the API Documentation

Open your browser and navigate to:

https://localhost:5001/scalar/v1

You’ll see the Scalar API documentation interface with:

All available endpoints
Request/response schemas
Interactive testing
Code generation for multiple languages

Configuration

appsettings.json

The default configuration file:

appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*"
}

appsettings.Development.json

Development-specific settings:

appsettings.Development.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

launchSettings.json

Defines how the application runs:

Properties/launchSettings.json

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "scalar/v1",
      "applicationUrl": "http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "launchUrl": "scalar/v1",
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Custom Port Configuration

If the default ports are in use, specify custom ports:

Option 1: Command Line

dotnet run --urls "https://localhost:7001;http://localhost:7000"

Option 2: Environment Variable

Linux/macOS:

export ASPNETCORE_URLS="https://localhost:7001;http://localhost:7000"
dotnet run

Windows (PowerShell):

$env:ASPNETCORE_URLS="https://localhost:7001;http://localhost:7000"
dotnet run

Option 3: appsettings.json

{
  "Urls": "https://localhost:7001;http://localhost:7000",
  "Logging": { /* ... */ }
}

SSL Certificate Setup

For HTTPS in development, trust the .NET development certificate:

dotnet dev-certs https --trust

This prevents SSL warnings when accessing https://localhost:5001.

Certificate issues on macOS/Linux

If you encounter certificate trust issues:macOS:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Linux:

dotnet dev-certs https --clean
dotnet dev-certs https

On Linux, you may need to manually trust the certificate in your browser.

IDE-Specific Setup

Visual Studio 2022

Open preliminarServicios.sln
Set the startup project to preliminarServicios
Press F5 to run with debugging or Ctrl+F5 without debugging
The browser will automatically open to the Scalar documentation

Visual Studio Code

Open the folder: File > Open Folder > ServiciosWebPreliminar
Install the C# extension if prompted
Open the terminal: Ctrl+`
Run: dotnet run
Open browser to https://localhost:5001/scalar/v1

Debugging in VS Code:

Press F5 or click Run > Start Debugging
Select C# as the environment
VS Code will generate .vscode/launch.json and .vscode/tasks.json

JetBrains Rider

Open preliminarServicios.sln
Click the Run button or press Shift+F10
The browser will automatically open to the API documentation

Testing the Setup

Verify your setup by making a test API call:

curl https://localhost:5001/api/Especialidad

Expected response:

[]

An empty array indicates the API is running correctly.

Hot Reload

.NET 10 supports hot reload for faster development:

dotnet watch run

Now when you save changes to .cs files, the application automatically reloads without restarting.

Common Issues

Port already in use

Error: System.IO.IOException: Failed to bind to address https://127.0.0.1:5001Solution: Use a different port:

dotnet run --urls "https://localhost:7001;http://localhost:7000"

SSL certificate not trusted

Error: Browser shows “Your connection is not private”Solution: Trust the development certificate:

dotnet dev-certs https --trust

'dotnet' command not found

Error: bash: dotnet: command not foundSolution:

Ensure .NET 10 SDK is installed
Verify it’s in your PATH
Restart your terminal

Build errors after cloning

Error: Various build errorsSolution: Restore packages and clean build:

dotnet restore
dotnet clean
dotnet build

Next Steps

Quickstart

Make your first API calls

Development Guide

Learn how to extend the API

Architecture

Understand the project structure

API Reference

Explore all endpoints

Get Started

Core Concepts

Guides

Prerequisites

Required Software

Clone the Repository

Project Structure

Restore Dependencies

Build the Project

Run the API

Access the API Documentation

Configuration

appsettings.json

appsettings.Development.json

launchSettings.json

Custom Port Configuration

Option 1: Command Line

Option 2: Environment Variable

Option 3: appsettings.json

SSL Certificate Setup

IDE-Specific Setup

Visual Studio 2022

Visual Studio Code

JetBrains Rider

Testing the Setup

Hot Reload

Common Issues

Next Steps

Quickstart

Development Guide

Architecture

API Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Prerequisites

​Required Software

​Clone the Repository

​Project Structure

​Restore Dependencies

​Build the Project

​Run the API

​Access the API Documentation

​Configuration

​appsettings.json

​appsettings.Development.json

​launchSettings.json

​Custom Port Configuration

​Option 1: Command Line

​Option 2: Environment Variable

​Option 3: appsettings.json

​SSL Certificate Setup

​IDE-Specific Setup

​Visual Studio 2022

​Visual Studio Code

​JetBrains Rider

​Testing the Setup

​Hot Reload

​Common Issues

​Next Steps

Quickstart

Development Guide

Architecture

API Reference

Build docs developers (and LLMs) love

Prerequisites

Required Software

Clone the Repository

Project Structure

Restore Dependencies

Build the Project

Run the API

Access the API Documentation

Configuration

appsettings.json

appsettings.Development.json

launchSettings.json

Custom Port Configuration

Option 1: Command Line

Option 2: Environment Variable

Option 3: appsettings.json

SSL Certificate Setup

IDE-Specific Setup

Visual Studio 2022

Visual Studio Code

JetBrains Rider

Testing the Setup

Hot Reload

Common Issues

Next Steps