Создание Docker-образа для .NET 5 Web API

Одно из главных преимуществ Docker — возможность запускать проекты без сложной настройки окружения. В этом руководстве вы научитесь создавать Docker-образ для .NET 5 Web API и запускать бэкенд на любой машине с установленным Docker, а затем обращаться к API из фронтенда или мобильного приложения.

Создание проекта .NET 5 Web API

Docker и .NET 5 кросс‑платформенны и с открытым исходным кодом, поэтому инструкция применима на macOS, Windows и Linux.

Создайте проект ASP.NET Web API через консоль с помощью dotnet CLI:

 dotnet new webapi -o aspdockerapi 

Эта команда создаёт проект с именем aspdockerapi и папку с тем же именем. Шаблон содержит пример контроллера с набором данных прогноза погоды.

Важно: если на вашей машине отсутствует .NET 5, установите подходящую версию с официального сайта Microsoft или используйте более новую поддерживаемую версию .NET (см. раздел о совместимости).

Перейдите в корневую папку проекта:

cd aspdockerapi

Запустите приложение локально для проверки:

 dotnet run 

По умолчанию приложение обслуживается на порту 5001. Откройте в браузере https://localhost:5001/weatherforecast — вы увидите тестовые данные контроллера.

Подробнее: что такое API и как с ним работать.

Инструкции по созданию Docker-образа

Чтобы Docker Engine умел собирать образ, опишите шаги в файле с именем Dockerfile (без расширения).

Создайте Dockerfile в корне проекта:

touch Dockerfile  

После этого структура папок проекта должна выглядеть примерно так:

Скопируйте и вставьте следующий Dockerfile в созданный файл (если ваш проект называется иначе — замените имена файлов):

FROM mcr.microsoft.com/dotnet/aspnet:5.0-focal AS base  
WORKDIR /app  
EXPOSE 80  
FROM mcr.microsoft.com/dotnet/sdk:5.0-focal AS build  
WORKDIR /src  
COPY ["aspdockerapi.csproj", "./"]  
RUN dotnet restore "./aspdockerapi.csproj"  
COPY . .  
WORKDIR "/src/."  
RUN dotnet build "aspdockerapi.csproj" -c Release -o /app/build  
FROM build AS publish  
RUN dotnet publish "aspdockerapi.csproj" -c Release -o /app/publish  
  
FROM base AS final  
WORKDIR /app  
COPY --from=publish /app/publish .  
ENTRYPOINT ["dotnet", "aspdockerapi.dll"]  

Важно: в Dockerfile указаны имена проекта и сборки aspdockerapi.csproj и aspdockerapi.dll. Если ваше приложение имеет другое имя, замените эти значения.

Понимание инструкций в Dockerfile

Dockerfile состоит из инструкций (обычно прописных слов). Они определяют слои и команды для сборки образа. Разберём ключевые директивы, используемые выше.

FROM

FROM указывает базовый образ, на котором строится ваш образ. В примере используются два образа Microsoft: runtime (aspnet) для «финального» образа и sdk для этапа сборки.

WORKDIR

WORKDIR задаёт рабочую директорию внутри образа. После установки WORKDIR все относительные команды будут выполняться относительно этой директории.

COPY

COPY копирует файлы из контекста сборки (локальной папки) в образ. В нашем Dockerfile сначала копируется файл проекта для более эффективного кэширования слоёв при restore.

RUN

RUN выполняет команду в момент сборки образа. Здесь RUN используется для dotnet restore, dotnet build и dotnet publish.

ENTRYPOINT

ENTRYPOINT определяет команду, которая будет запускаться при старте контейнера. В примере это запуск собранной dll через dotnet.

EXPOSE

EXPOSE документирует, какие порты контейнера «слушают» приложение. EXPOSE не пробрасывает порт наружу — это делает опция -p при запуске контейнера.

Сборка Docker-образа

Чтобы собрать образ из Dockerfile, выполните в корне проекта:

docker build -t dockerwebapi -f Dockerfile .

Ключ -t задаёт тег (имя) образа dockerwebapi, -f указывает файл Dockerfile (можно опустить, если файл называется Dockerfile).

Проверьте локальные образы:

docker images

Пример вывода покажет ваш образ dockerwebapi в списке.

Если Docker не установлен, следуйте официальной инструкции по установке Docker для вашей ОС.

Подробнее: как устроено кэширование слоёв Docker и почему COPY отдельных файлов ускоряет сборку.

Запуск Docker-образа

Запустите контейнер так, чтобы порт 80 внутри контейнера мапился на порт 8080 хоста:

docker run -ti --rm -p 8080:80 dockerwebapi

Опции:

• -ti — интерактивный терминал (можно убрать в проде);
• –rm — автоматически удалить контейнер после остановки;
• -p 8080:80 — проброс порта: хост:контейнер.

Откройте в браузере http://localhost:8080/WeatherForecast — вы получите те же данные, что и при локальном запуске dotnet run.

Почему стоит использовать Docker

Docker упрощает развертывание и делает окружение воспроизводимым: один и тот же образ работает везде, где есть Docker. Это ускоряет коллаборацию, CI/CD и уменьшает проблемы «у меня работает». Контейнеры легче и быстрее, чем полноценные виртуальные машины.

Когда Docker не лучший выбор

• Если нужно полное изолированное ядро ОС (тогда VM предпочтительнее).
• Для узкоспециализированных GUI-приложений с жёсткой зависимостью от локального оборудования.
• Для небольших одноразовых скриптов, где накладные расходы контейнеризации не оправданы.

Альтернативные подходы

• Виртуальные машины (VM): полная изоляция, большой размер образов.
• Podman — совместимый с Docker инструмент, не требующий daemon.
• Платформы PaaS (Azure App Service, Heroku) — развёртывание без управления контейнерами вручную.

Ментальные модели (как думать о контейнерах)

• Образ = слоёвая файловая система + инструкции; слои кэшируются.
• Контейнер = запущенная из образа среда, временная и воспроизводимая.
• Идемпотентность: повторная сборка образа при тех же входных данных даёт тот же результат.

Важно: храните секреты и конфигурацию вне образа (переменные окружения, секретные хранилища). Не встраивайте пароли в Dockerfile.

Фактбокс — ключевые команды и понятия

• dotnet new webapi -o <имя> — создать шаблон Web API;
• dotnet run — запустить проект локально;
• docker build -t <имя> -f Dockerfile . — собрать образ;
• docker images — список локальных образов;
• docker run -p <портхоста>:<портконтейнера> <образ> — запустить контейнер;
• ENTRYPOINT и CMD — команды старта контейнера;
• EXPOSE — документирует порты.

Быстрый чеклист (мини-методология)

1. Локально убедиться, что dotnet run работает и API отвечает.
2. Создать Dockerfile и адаптировать имена проектов.
3. docker build — собрать образ, проверить вывод сборки.
4. docker run -p … — запустить, проверить эндпоинты.
5. Настроить CI/CD для автоматической сборки и публикации образов.

Ролевые чеклисты

Разработчик:

• Проверить, что проект запускается локально;
• Минимизировать образы (многоступенчатая сборка);
• Не встраивать секреты.

Инженер по доставке/операциям:

• Настроить CI для сборки и сканирования образов;
• Обеспечить хранение образов в реестре (Docker Hub, GitHub Packages, Azure Container Registry);
• Настроить мониторинг контейнеров.

Тестировщик:

• Запускать контейнеры в тестовом окружении;
• Автоматические интеграционные тесты против контейнера;
• Проверять конфигурацию среды (переменные окружения).

Шпаргалка команд

• Сборка: docker build -t dockerwebapi -f Dockerfile .
• Список образов: docker images
• Запуск: docker run -d –name api -p 8080:80 dockerwebapi
• Остановить контейнер: docker stop <имя|id>
• Удалить контейнер: docker rm <имя|id>
• Удалить образ: docker rmi

Критерии приёмки

• docker build проходит без ошибок и образ создаётся;
• docker run успешно запускает контейнер и эндпоинт /WeatherForecast возвращает 200;
• В CI образ собирается и тесты проходят;
• Отсутствуют секреты в слоях образа.

Совместимость и миграция

.NET 5 — устаревшая версия платформы; рекомендуется рассмотреть поддерживаемые LTS‑версии .NET (например, .NET 6 или более новые LTS-релизы). При миграции:

• Обновите целевой TFM в .csproj (TargetFramework);
• Протестируйте зависимости и сторонние пакеты;
• Проверьте Dockerfile: используйте соответствующие тэги базовых образов (mcr.microsoft.com/dotnet/aspnet:<версия>-focal).

Глоссарий (в одну строку)

• Образ: снапшот файловой системы и инструкций для запуска.
• Контейнер: запущенный экземпляр образа.
• Registry: хранилище образов (Docker Hub, ACR).
• ENTRYPOINT: команда, выполняемая при старте контейнера.

Социальный предпросмотр

OG заголовок: Docker для .NET 5 Web API — как упаковать и запустить

OG описание: Пошаговое руководство по упаковке ASP.NET Core (.NET 5) в Docker-образ, сборке и запуску контейнера локально.

Короткое объявление (100–200 слов)

Упакуйте ваш ASP.NET Core Web API в Docker за несколько шагов: создайте проект через dotnet new webapi, добавьте Dockerfile с многоступенчатой сборкой, соберите образ docker build и запустите контейнер docker run -p 8080:80. Это упрощает развёртывание и делает среду воспроизводимой на любой машине с Docker. Руководство включает объяснение инструкций Dockerfile, полезные команды, контрольные списки для разработчиков, тестировщиков и инженеров по доставке, а также рекомендации по миграции на поддерживаемые версии .NET.

Краткое резюме

В руководстве описан полный путь: создание проекта, подготовка Dockerfile, сборка образа и запуск контейнера. Дополнительно приведены практические чеклисты, советы по безопасности (не хранить секреты в образах) и рекомендации по миграции на поддерживаемые версии .NET.

• Важное замечание: всегда проверяйте используемые теги базовых образов и используйте поддерживаемые версии платформы.