ASP.NET Core для C# (.NET): полное руководство с примерами

Что такое ASP.NET Core и зачем он нужен?

ASP.NET Core — это современный, кроссплатформенный, высокопроизводительный веб-фреймворк с открытым исходным кодом от Microsoft, предназначенный для создания веб-приложений, API, микросервисов и облачных решений на языке C# (.NET). В отличие от классического ASP.NET (Framework), который работал только на Windows, ASP.NET Core полностью кроссплатформенный: он запускается на Windows, Linux и macOS.

Зачем он нужен? ASP.NET Core предоставляет разработчикам мощный инструментарий для создания современных веб-приложений. Он включает в себя встроенную поддержку внедрения зависимостей (Dependency Injection), middleware (промежуточное ПО), маршрутизацию, аутентификацию, работу с базами данных через Entity Framework Core и многое другое. Фреймворк оптимизирован для высокой производительности и масштабируемости, что делает его идеальным выбором для создания как небольших сайтов, так и крупных корпоративных систем.

Ключевые преимущества ASP.NET Core:

• Кроссплатформенность: Работает на Windows, Linux и macOS.
• Высокая производительность: Один из самых быстрых веб-фреймворков.
• Модульность: Вы подключаете только те компоненты, которые нужны вашему приложению.
• Встроенная поддержка Dependency Injection: Упрощает тестирование и поддержку кода.
• Open Source: Исходный код доступен на GitHub, сообщество активно развивает фреймворк.
• Единая модель программирования: Можно создавать MVC приложения, Web API, Razor Pages, Blazor и SignalR.

Установка ASP.NET Core

Для начала работы с ASP.NET Core необходимо установить .NET SDK (Software Development Kit). Это не пакет, устанавливаемый через pip или npm, а полноценная среда разработки.

Шаги по установке:

1. Скачайте .NET SDK: Перейдите на официальный сайт dotnet.microsoft.com/download и скачайте последнюю версию .NET SDK для вашей операционной системы (Windows, Linux, macOS).
2. Установите SDK: Запустите установщик и следуйте инструкциям. После установки перезагрузите компьютер (или терминал).
3. Проверьте установку: Откройте терминал (командную строку) и выполните команду:

   dotnet --version

   Если вы видите номер версии (например, 8.0.100), установка прошла успешно.

После установки SDK у вас будет доступ к команде dotnet, которая используется для создания, сборки и запуска проектов.

Быстрый старт с примером кода

Создадим простое веб-приложение ASP.NET Core (Web API), которое будет возвращать "Hello, World!".

Шаг 1: Создание проекта

Откройте терминал и выполните команду:

dotnet new webapi -n MyFirstApi
cd MyFirstApi

Эта команда создаст новый проект Web API с именем MyFirstApi и перейдет в его папку.

Шаг 2: Структура проекта

В папке проекта вы увидите несколько файлов. Основные из них:

• Program.cs — точка входа в приложение, где настраивается конвейер обработки запросов.
• MyFirstApi.csproj — файл проекта, содержащий зависимости и настройки сборки.
• Controllers/ — папка для контроллеров (по умолчанию там уже есть WeatherForecastController.cs).

Шаг 3: Запуск приложения

Выполните команду в терминале:

dotnet run

После запуска вы увидите сообщение, что приложение работает на http://localhost:5xxx (порт может отличаться). Откройте браузер и перейдите по адресу http://localhost:5xxx/weatherforecast. Вы должны увидеть JSON-массив с прогнозом погоды.

Шаг 4: Создадим свой контроллер

Создайте новый файл HelloController.cs в папке Controllers и добавьте следующий код:

using Microsoft.AspNetCore.Mvc;

namespace MyFirstApi.Controllers;

[ApiController]
[Route("[controller]")]
public class HelloController : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok(new { message = "Hello, World!" });
    }
}

Теперь перезапустите приложение (остановите его с помощью Ctrl+C и снова выполните dotnet run). Перейдите по адресу http://localhost:5xxx/hello. Вы увидите JSON: {"message":"Hello, World!"}. Поздравляю, ваше первое API готово!

Основные методы и функции ASP.NET Core

Ниже приведены ключевые методы и функции, которые вы будете использовать при работе с ASP.NET Core. Для каждого метода дано описание, параметры и рабочий пример.

1. MapGet (Маршрутизация минимальных API)

Что делает: Определяет конечную точку (endpoint) для HTTP GET-запроса. Используется в минимальных API (Minimal APIs), где не требуется создание контроллера.

Параметры:

• pattern (string) — шаблон маршрута (например, "/hello").
• handler (Delegate) — делегат, который обрабатывает запрос и возвращает ответ.

Пример:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/hello", () => "Hello, World!");

app.Run();

2. MapPost (Маршрутизация минимальных API)

Что делает: Определяет конечную точку для HTTP POST-запроса. Используется для создания новых ресурсов.

Параметры:

• pattern (string) — шаблон маршрута.
• handler (Delegate) — делегат, обрабатывающий запрос.

Пример:

app.MapPost("/users", (User user) =>
{
    // Логика создания пользователя
    return Results.Created($"/users/{user.Id}", user);
});

3. UseAuthentication (Middleware аутентификации)

Что делает: Добавляет middleware аутентификации в конвейер обработки запросов. Позволяет проверять подлинность пользователей.

Параметры: Не принимает параметров, но требует предварительной настройки служб аутентификации (AddAuthentication).

Пример:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication("Bearer").AddJwtBearer();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.Run();

4. AddControllers (Регистрация контроллеров)

Что делает: Регистрирует службы, необходимые для работы контроллеров (MVC). Вызывается в методе ConfigureServices (или builder.Services).

Параметры: Необязательный параметр — делегат для настройки параметров MVC (например, фильтры).

Пример:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

5. UseCors (Настройка CORS)

Что делает: Добавляет middleware для обработки политик CORS (Cross-Origin Resource Sharing). Позволяет разрешить или запретить запросы с других доменов.

Параметры: Строка с именем политики CORS, которая была предварительно настроена через AddCors.

Пример:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCors(options =>
{
    options.AddPolicy("AllowAll", policy =>
    {
        policy.AllowAnyOrigin().AllowAnyMethod().AllowAnyHeader();
    });
});
var app = builder.Build();
app.UseCors("AllowAll");
app.Run();

6. UseStaticFiles (Статические файлы)

Что делает: Добавляет middleware для обслуживания статических файлов (HTML, CSS, JS, изображения) из папки wwwroot.

Параметры: Необязательный объект StaticFileOptions для настройки пути, кэширования и т.д.

Пример:

var app = builder.Build();
app.UseStaticFiles(); // Теперь файлы из wwwroot доступны по URL
app.Run();

7. AddDbContext (Регистрация контекста базы данных)

Что делает: Регистрирует контекст базы данных Entity Framework Core в контейнере DI. Позволяет работать с базами данных (SQL Server, PostgreSQL, SQLite и др.).

Параметры:

• TContext — тип контекста базы данных (наследуется от DbContext).
• optionsAction (Action<DbContextOptionsBuilder>) — делегат для настройки подключения (строка подключения, провайдер).

Пример:

builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

8. AddSwaggerGen (Документация Swagger)

Что делает: Регистрирует службы для генерации документации API в формате OpenAPI (Swagger). Позволяет автоматически создавать интерактивную документацию.

Параметры: Необязательный делегат для настройки Swagger (например, версия API, заголовок).

Пример:

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = "My API", Version = "v1" });
});
var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();
app.Run();

9. UseExceptionHandler (Обработка ошибок)

Что делает: Добавляет middleware для глобальной обработки исключений. Позволяет перенаправлять пользователя на специальную страницу ошибки или возвращать кастомный JSON.

Параметры:

• errorHandlingPath (string) — путь к странице ошибки (например, "/Home/Error").
• Или делегат для настройки поведения.

Пример:

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}
else
{
    app.UseExceptionHandler("/Home/Error");
}

10. MapControllerRoute (Настройка маршрутов MVC)

Что делает: Определяет шаблон маршрута для контроллеров MVC. Обычно используется в классическом MVC-подходе.

Параметры:

• name (string) — имя маршрута.
• pattern (string) — шаблон URL (например, "{controller=Home}/{action=Index}/{id?}").
• defaults (object) — значения по умолчанию для сегментов маршрута.

Пример:

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

Реальный практический пример использования