Visual Studio Tools para Docker con ASP.NET CoreVisual Studio Tools for Docker with ASP.NET Core

En Visual Studio 2017 y versiones posteriores, se pueden compilar, depurar y ejecutar aplicaciones ASP.NET Core incluidas en un contenedor para .NET Core.Visual Studio 2017 and later versions support building, debugging, and running containerized ASP.NET Core apps targeting .NET Core. Se admiten contenedores de Windows y Linux.Both Windows and Linux containers are supported.

Vea o descargue el código de ejemplo (cómo descargarlo)View or download sample code (how to download)

Requisitos previosPrerequisites

Instalación y configuraciónInstallation and setup

Para instalar Docker, primero revise la información de Docker Desktop for Windows: What to know before you install (Docker Desktop para Windows: información previa a la instalación).For Docker installation, first review the information at Docker for Windows: What to know before you install. A continuación, instale Docker para Windows.Next, install Docker For Windows.

Las unidades compartidas de Docker para Windows deben configurarse para admitir la asignación y la depuración de volúmenes.Shared Drives in Docker for Windows must be configured to support volume mapping and debugging. Haga clic con el botón derecho en el icono de Docker de la bandeja del sistema, y seleccione Configuración y Unidades compartidas.Right-click the System Tray's Docker icon, select Settings, and select Shared Drives. Seleccione la unidad donde los archivos se almacenan en Docker.Select the drive where Docker stores files. Haga clic en Aplicar.Click Apply.

Cuadro de diálogo para seleccionar el uso compartido de la unidad C local para los contenedores

Sugerencia

Las versiones 15.6 y posteriores de Visual Studio 2017 le avisan si las unidades compartidas no están configuradas.Visual Studio 2017 versions 15.6 and later prompt when Shared Drives aren't configured.

Agregar un proyecto a un contenedor de DockerAdd a project to a Docker container

Para incluir un proyecto de ASP.NET Core en un contenedor, el proyecto debe ser para .NET Core.To containerize an ASP.NET Core project, the project must target .NET Core. Se admiten contenedores de Linux y Windows.Both Linux and Windows containers are supported.

Al agregar compatibilidad con Docker a un proyecto, elija un contenedor de Linux o Windows.When adding Docker support to a project, choose either a Windows or a Linux container. El host de Docker debe ejecutar el mismo tipo de contenedor.The Docker host must be running the same container type. Para cambiar el tipo de contenedor en la instancia de Docker en ejecución, haga clic con el botón derecho en el icono de Docker en la bandeja del sistema y elija Switch to Windows containers... (Cambiar a contenedores Windows) o Switch to Linux containers... (Cambiar a contenedores Linux).To change the container type in the running Docker instance, right-click the System Tray's Docker icon and choose Switch to Windows containers... or Switch to Linux containers....

Nueva aplicaciónNew app

Al crear una nueva aplicación con las plantillas de proyecto Aplicación web ASP.NET Core, active la casilla Enable Docker Support (Habilitar compatibilidad con Docker):When creating a new app with the ASP.NET Core Web Application project templates, select the Enable Docker Support check box:

Casilla Habilitar compatibilidad con Docker

Si la plataforma de destino es .NET Core, la lista desplegable de SO permite la selección de un tipo de contenedor.If the target framework is .NET Core, the OS drop-down allows for the selection of a container type.

Aplicación existenteExisting app

En los proyectos de ASP.NET Core para .NET Core, hay dos opciones para agregar compatibilidad con Docker mediante las herramientas.For ASP.NET Core projects targeting .NET Core, there are two options for adding Docker support via the tooling. Abra el proyecto en Visual Studio y elija una de las siguientes opciones:Open the project in Visual Studio, and choose one of the following options:

  • Seleccione Compatibilidad con Docker en el menú Proyecto.Select Docker Support from the Project menu.
  • Haga clic con el botón derecho en el proyecto, en el Explorador de soluciones, y seleccione Agregar > Compatibilidad con Docker.Right-click the project in Solution Explorer and select Add > Docker Support.

Visual Studio Tools para Docker no admite la adición de Docker a un proyecto de ASP.NET Core existente para .NET Framework.The Visual Studio Tools for Docker don't support adding Docker to an existing ASP.NET Core project targeting .NET Framework.

Información general sobre DockerfileDockerfile overview

Se agrega un Dockerfile, la receta para crear una imagen de Docker final, a la raíz del proyecto.A Dockerfile, the recipe for creating a final Docker image, is added to the project root. Vea Dockerfile reference (Referencia de Dockerfile) para obtener una descripción de los comandos que contiene.Refer to Dockerfile reference for an understanding of the commands within it. Este Dockerfile en concreto usa una compilación de varias fases, con cuatro fases de compilación distintas y cada una con un nombre asignado:This particular Dockerfile uses a multi-stage build with four distinct, named build stages:

FROM mcr.microsoft.com/dotnet/core/aspnet:2.1 AS base
WORKDIR /app
EXPOSE 59518
EXPOSE 44364

FROM mcr.microsoft.com/dotnet/core/sdk:2.1 AS build
WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app

FROM build AS publish
RUN dotnet publish HelloDockerTools.csproj -c Release -o /app

FROM base AS final
WORKDIR /app
COPY --from=publish /app .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

El Dockerfile anterior se basa en la imagen microsoft/dotnet.The preceding Dockerfile is based on the microsoft/dotnet image. Esta imagen base incluye el entorno de ejecución de ASP.NET Core y los paquetes NuGet.This base image includes the ASP.NET Core runtime and NuGet packages. Los paquetes están compilados Just-In-Time (JIT) para mejorar el rendimiento de inicio.The packages are just-in-time (JIT) compiled to improve startup performance.

Si la casilla Configurar para HTTPS del cuadro de diálogo del nuevo proyecto está marcada, el Dockerfile expondrá dos puertos.When the new project dialog's Configure for HTTPS check box is checked, the Dockerfile exposes two ports. Uno se utiliza para el tráfico HTTP, mientras que el otro se emplea para HTTPS.One port is used for HTTP traffic; the other port is used for HTTPS. Si la casilla no está marcada, se expondrá un único puerto (80) para el tráfico HTTP.If the check box isn't checked, a single port (80) is exposed for HTTP traffic.

FROM microsoft/aspnetcore:2.0 AS base
WORKDIR /app
EXPOSE 80

FROM microsoft/aspnetcore-build:2.0 AS build
WORKDIR /src
COPY HelloDockerTools/HelloDockerTools.csproj HelloDockerTools/
RUN dotnet restore HelloDockerTools/HelloDockerTools.csproj
COPY . .
WORKDIR /src/HelloDockerTools
RUN dotnet build HelloDockerTools.csproj -c Release -o /app

FROM build AS publish
RUN dotnet publish HelloDockerTools.csproj -c Release -o /app

FROM base AS final
WORKDIR /app
COPY --from=publish /app .
ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]

El Dockerfile anterior se basa en la imagen microsoft/aspnetcore.The preceding Dockerfile is based on the microsoft/aspnetcore image. Esta imagen base incluye los paquetes NuGet de ASP.NET Core, compilados Just-In-Time (JIT) para mejorar el rendimiento de inicio.This base image includes the ASP.NET Core NuGet packages, which are just-in-time (JIT) compiled to improve startup performance.

Agregar compatibilidad con un orquestador de contenedores a una aplicaciónAdd container orchestrator support to an app

Visual Studio 2017, versiones 15.7 o anteriores, es compatible con Docker Compose como única solución de orquestación de contenedores.Visual Studio 2017 versions 15.7 or earlier support Docker Compose as the sole container orchestration solution. Los artefactos de Docker Compose se agregan mediante Agregar > Compatibilidad con Docker.The Docker Compose artifacts are added via Add > Docker Support.

Visual Studio 2017, versiones 15.8 o posteriores, permite agregar una solución de orquestación de forma manual.Visual Studio 2017 versions 15.8 or later add an orchestration solution only when instructed. Haga clic con el botón derecho en el Explorador de soluciones y seleccione Agregar > Compatibilidad con el orquestador de contenedores.Right-click the project in Solution Explorer and select Add > Container Orchestrator Support. Se ofrecen dos opciones diferentes: Docker Compose y Service Fabric.Two different choices are offered: Docker Compose and Service Fabric.

Docker ComposeDocker Compose

Visual Studio Tools para Docker permite agregar un proyecto docker-compose a la solución con los archivos siguientes:The Visual Studio Tools for Docker add a docker-compose project to the solution with the following files:

  • docker-compose.dcproj: archivo que representa el proyecto.docker-compose.dcproj – The file representing the project. Incluye un elemento <DockerTargetOS> en el que se especifica el sistema operativo que se utilizará.Includes a <DockerTargetOS> element specifying the OS to be used.
  • .dockerignore: contiene una lista de los patrones de archivos y directorios que se excluirán al generar un contexto de compilación..dockerignore – Lists the file and directory patterns to exclude when generating a build context.
  • docker-compose.yml: archivo base de Docker Compose que se utiliza para definir la colección de imágenes compilada y ejecutada con docker-compose build y docker-compose run, respectivamente.docker-compose.yml – The base Docker Compose file used to define the collection of images built and run with docker-compose build and docker-compose run, respectively.
  • docker-compose.override.yml: archivo opcional que Docker Compose lee y que contiene las invalidaciones de configuración de los servicios.docker-compose.override.yml – An optional file, read by Docker Compose, with configuration overrides for services. Visual Studio ejecuta docker-compose -f "docker-compose.yml" -f "docker-compose.override.yml" para combinar estos archivos.Visual Studio executes docker-compose -f "docker-compose.yml" -f "docker-compose.override.yml" to merge these files.

El archivo docker-compose.yml hace referencia al nombre de la imagen que se crea al ejecutar el proyecto:The docker-compose.yml file references the name of the image that's created when the project runs:

version: '3.4'

services:
  hellodockertools:
    image: ${DOCKER_REGISTRY}hellodockertools
    build:
      context: .
      dockerfile: HelloDockerTools/Dockerfile

En el ejemplo anterior, image: hellodockertools genera la imagen hellodockertools:dev cuando se ejecuta la aplicación en modo de depuración.In the preceding example, image: hellodockertools generates the image hellodockertools:dev when the app runs in Debug mode. La imagen hellodockertools:latest se genera cuando se ejecuta la aplicación en modo de versión.The hellodockertools:latest image is generated when the app runs in Release mode.

Si tiene previsto colocar la imagen en el Registro, utilice el nombre de usuario de Docker Hub como prefijo, antes del nombre de imagen, por ejemplo, dockerhubusername/hellodockertools.Prefix the image name with the Docker Hub username (for example, dockerhubusername/hellodockertools) if the image is pushed to the registry. También puede cambiar el nombre de la imagen para incluir la dirección URL del Registro privado (por ejemplo, privateregistry.domain.com/hellodockertools) según la configuración.Alternatively, change the image name to include the private registry URL (for example, privateregistry.domain.com/hellodockertools) depending on the configuration.

Si quiere un comportamiento diferente basado en la configuración de compilación (por ejemplo, Debug o Release), agregue archivos docker-compose específicos de la configuración.If you want different behavior based on the build configuration (for example, Debug or Release), add configuration-specific docker-compose files. Los nombres de los archivos deben basarse en la configuración de compilación (por ejemplo, docker-compose.vs.debug.yml y docker-compose.vs.release.yml) y deben colocarse en la misma ubicación que el archivo docker-compose-override.yml.The files should be named according to the build configuration (for example, docker-compose.vs.debug.yml and docker-compose.vs.release.yml) and placed in the same location as the docker-compose-override.yml file.

Con los archivos de invalidación específicos de la configuración, puede especificar distintos valores de configuración (por ejemplo, variables de entorno o puntos de entrada) para las configuraciones de compilación de depuración y lanzamiento.Using the configuration-specific override files, you can specify different configuration settings (such as environment variables or entry points) for Debug and Release build configurations.

Service FabricService Fabric

Además de los requisitos previos base, la solución de orquestación de Service Fabric presenta los siguientes requisitos previos:In addition to the base Prerequisites, the Service Fabric orchestration solution demands the following prerequisites:

Service Fabric no admite la ejecución de contenedores de Linux en el clúster de desarrollo local de Windows.Service Fabric doesn't support running Linux containers in the local development cluster on Windows. Si el proyecto ya utiliza un contenedor de Linux, Visual Studio le solicitará que cambie a los contenedores de Windows.If the project is already using a Linux container, Visual Studio prompts to switch to Windows containers.

Visual Studio Tools para Docker permite realizar las siguientes tareas:The Visual Studio Tools for Docker do the following tasks:

  • Agregar un proyecto Aplicación de Service Fabric <nombre_proyecto>Aplicación a la solución.Adds a <project_name>Application Service Fabric Application project to the solution.

  • Agregar un Dockerfile y un archivo .dockerignore al proyecto de ASP.NET Core.Adds a Dockerfile and a .dockerignore file to the ASP.NET Core project. Si el proyecto de ASP.NET Core ya contiene un Dockerfile, se le cambiará el nombre a Dockerfile.original.If a Dockerfile already exists in the ASP.NET Core project, it's renamed to Dockerfile.original. A continuación, se creará un nuevo Dockerfile similar al siguiente:A new Dockerfile, similar to the following, is created:

    # See https://aka.ms/containerimagehelp for information on how to use Windows Server 1709 containers with Service Fabric.
    # FROM microsoft/aspnetcore:2.0-nanoserver-1709
    FROM microsoft/aspnetcore:2.0-nanoserver-sac2016
    ARG source
    WORKDIR /app
    COPY ${source:-obj/Docker/publish} .
    ENTRYPOINT ["dotnet", "HelloDockerTools.dll"]
    
  • Agregar un elemento <IsServiceFabricServiceProject> al archivo .csproj al proyecto de ASP.NET Core:Adds an <IsServiceFabricServiceProject> element to the ASP.NET Core project's .csproj file:

    <IsServiceFabricServiceProject>True</IsServiceFabricServiceProject>
    
  • Agregar una carpeta PackageRoot al proyecto de ASP.NET Core.Adds a PackageRoot folder to the ASP.NET Core project. La carpeta incluirá un manifiesto de servicio y las opciones de configuración del nuevo servicio.The folder includes the service manifest and settings for the new service.

Para obtener más información, consulte Implementación de una aplicación .NET de un contenedor de Windows en Azure Service Fabric.For more information, see Deploy a .NET app in a Windows container to Azure Service Fabric.

DepuraciónDebug

Seleccione Docker en la lista desplegable de depuración de la barra de herramientas y empiece a depurar la aplicación.Select Docker from the debug drop-down in the toolbar, and start debugging the app. La vista Docker de la ventana Salida muestra las acciones siguientes en curso:The Docker view of the Output window shows the following actions taking place:

  • Si todavía no está en la caché, se adquirirá la etiqueta 2.1-aspnetcore-runtime de la imagen del entorno de ejecución microsoft/dotnet.The 2.1-aspnetcore-runtime tag of the microsoft/dotnet runtime image is acquired (if not already in the cache). La imagen instala los entornos de ejecución de ASP.NET Core y .NET Core, así como las bibliotecas asociadas.The image installs the ASP.NET Core and .NET Core runtimes and associated libraries. Además, está optimizada para ejecutar aplicaciones ASP.NET Core en producción.It's optimized for running ASP.NET Core apps in production.
  • Dentro del contenedor, la variable de entorno ASPNETCORE_ENVIRONMENT se establece en Development.The ASPNETCORE_ENVIRONMENT environment variable is set to Development within the container.
  • Se exponen dos puertos asignados de forma dinámica: uno para HTTP y otro para HTTPS.Two dynamically assigned ports are exposed: one for HTTP and one for HTTPS. El puerto asignado al localhost se puede asignar mediante el comando docker ps.The port assigned to localhost can be queried with the docker ps command.
  • La aplicación se copia en el contenedor.The app is copied to the container.
  • Se inicia el explorador predeterminado con el depurador asociado al contenedor, con el puerto asignado dinámicamente.The default browser is launched with the debugger attached to the container using the dynamically assigned port.

Seguidamente, se aplica la etiqueta dev a la imagen de Docker resultante de la aplicación.The resulting Docker image of the app is tagged as dev. La imagen se basa en la etiqueta 2.1-aspnetcore-runtime de la imagen base microsoft/dotnet.The image is based on the 2.1-aspnetcore-runtime tag of the microsoft/dotnet base image. Ejecute el comando docker images en la ventana Consola del Administrador de paquetes (PMC).Run the docker images command in the Package Manager Console (PMC) window. Se muestran las imágenes en la máquina:The images on the machine are displayed:

REPOSITORY        TAG                     IMAGE ID      CREATED         SIZE
hellodockertools  dev                     d72ce0f1dfe7  30 seconds ago  255MB
microsoft/dotnet  2.1-aspnetcore-runtime  fcc3887985bb  6 days ago      255MB
  • Se adquiere la imagen microsoft/aspnetcore en tiempo de ejecución (si todavía no está en la caché).The microsoft/aspnetcore runtime image is acquired (if not already in the cache).
  • Dentro del contenedor, la variable de entorno ASPNETCORE_ENVIRONMENT se establece en Development.The ASPNETCORE_ENVIRONMENT environment variable is set to Development within the container.
  • Se expone el puerto 80 y se asigna a un puerto asignado dinámicamente para el host local.Port 80 is exposed and mapped to a dynamically assigned port for localhost. El puerto viene determinado por el host de Docker y se puede consultar con el comando docker ps.The port is determined by the Docker host and can be queried with the docker ps command.
  • La aplicación se copia en el contenedor.The app is copied to the container.
  • Se inicia el explorador predeterminado con el depurador asociado al contenedor, con el puerto asignado dinámicamente.The default browser is launched with the debugger attached to the container using the dynamically assigned port.

Seguidamente, se aplica la etiqueta dev a la imagen de Docker resultante de la aplicación.The resulting Docker image of the app is tagged as dev. La imagen se basa en la imagen base microsoft/aspnetcore.The image is based on the microsoft/aspnetcore base image. Ejecute el comando docker images en la ventana Consola del Administrador de paquetes (PMC).Run the docker images command in the Package Manager Console (PMC) window. Se muestran las imágenes en la máquina:The images on the machine are displayed:

REPOSITORY            TAG  IMAGE ID      CREATED        SIZE
hellodockertools      dev  5fafe5d1ad5b  4 minutes ago  347MB
microsoft/aspnetcore  2.0  c69d39472da9  13 days ago    347MB

Nota

La imagen dev carece del contenido de la aplicación, ya que las opciones de configuración de depuración utilizan el montaje de volúmenes para proporcionar la experiencia iterativa.The dev image lacks the app contents, as Debug configurations use volume mounting to provide the iterative experience. Para insertar una imagen, use la configuración de versión.To push an image, use the Release configuration.

Ejecute el comando docker ps en la PMC.Run the docker ps command in PMC. Tenga en cuenta que la aplicación se ejecuta mediante el contenedor:Notice the app is running using the container:

CONTAINER ID        IMAGE                  COMMAND                   CREATED             STATUS              PORTS                   NAMES
baf9a678c88d        hellodockertools:dev   "C:\\remote_debugge..."   21 seconds ago      Up 19 seconds       0.0.0.0:37630->80/tcp   dockercompose4642749010770307127_hellodockertools_1

Editar y continuarEdit and continue

Los cambios en archivos estáticos y vistas de Razor se actualizan automáticamente sin necesidad de ningún paso de compilación.Changes to static files and Razor views are automatically updated without the need for a compilation step. Realice el cambio, guarde y actualice el explorador para ver la actualización.Make the change, save, and refresh the browser to view the update.

Las modificaciones en los archivos de código requieren compilación y un reinicio del Kestrel dentro del contenedor.Code file modifications require compilation and a restart of Kestrel within the container. Después de realizar la modificación, use CTRL+F5 para realizar el proceso e iniciar la aplicación dentro del contenedor.After making the change, use CTRL+F5 to perform the process and start the app within the container. El contenedor de Docker no se vuelve a compilar ni se detiene.The Docker container isn't rebuilt or stopped. Ejecute el comando docker ps en la PMC.Run the docker ps command in PMC. Observe que el contenedor original se está ejecutando desde hace 10 minutos:Notice the original container is still running as of 10 minutes ago:

CONTAINER ID        IMAGE                  COMMAND                   CREATED             STATUS              PORTS                   NAMES
baf9a678c88d        hellodockertools:dev   "C:\\remote_debugge..."   10 minutes ago      Up 10 minutes       0.0.0.0:37630->80/tcp   dockercompose4642749010770307127_hellodockertools_1

Publicar imágenes de DockerPublish Docker images

Una vez que se completa el ciclo de desarrollo y depuración de la aplicación, Visual Studio Tools para Docker ayuda a crear la imagen de producción de la aplicación.Once the develop and debug cycle of the app is completed, the Visual Studio Tools for Docker assist in creating the production image of the app. Cambie la lista desplegable de configuración a Versión y compile la aplicación.Change the configuration drop-down to Release and build the app. Si todavía no está en la caché, las herramientas obtendrán la imagen de compilación o publicación a partir de Docker Hub.The tooling acquires the compile/publish image from Docker Hub (if not already in the cache). Se generará una imagen con la etiqueta más reciente que se puede colocar en el Registro privado o Docker Hub.An image is produced with the latest tag, which can be pushed to the private registry or Docker Hub.

Para consultar la lista de imágenes, ejecute el comando docker images en PMC.Run the docker images command in PMC to see the list of images. Esto genera una salida similar a la siguiente:Output similar to the following is displayed:

REPOSITORY        TAG                     IMAGE ID      CREATED             SIZE
hellodockertools  latest                  e3984a64230c  About a minute ago  258MB
hellodockertools  dev                     d72ce0f1dfe7  4 minutes ago       255MB
microsoft/dotnet  2.1-sdk                 9e243db15f91  6 days ago          1.7GB
microsoft/dotnet  2.1-aspnetcore-runtime  fcc3887985bb  6 days ago          255MB
REPOSITORY                  TAG     IMAGE ID      CREATED         SIZE
hellodockertools            latest  cd28f0d4abbd  12 seconds ago  349MB
hellodockertools            dev     5fafe5d1ad5b  23 minutes ago  347MB
microsoft/aspnetcore-build  2.0     7fed40fbb647  13 days ago     2.02GB
microsoft/aspnetcore        2.0     c69d39472da9  13 days ago     347MB

A partir de .NET Core 2.1, las imágenes microsoft/aspnetcore-build y microsoft/aspnetcore que figuran en la salida anterior se reemplazan por imágenes microsoft/dotnet.The microsoft/aspnetcore-build and microsoft/aspnetcore images listed in the preceding output are replaced with microsoft/dotnet images as of .NET Core 2.1. Para obtener más información, consulte el anuncio sobre la migración de los repositorios de Docker.For more information, see the Docker repositories migration announcement.

Nota

El comando docker images devuelve imágenes de intermediario con los nombres de repositorio y las etiquetas identificados como <ninguno > (no mencionado anteriormente).The docker images command returns intermediary images with repository names and tags identified as <none> (not listed above). Estas imágenes sin nombre son creadas por el Dockerfile de compilación de varias fases.These unnamed images are produced by the multi-stage build Dockerfile. Mejoran la eficacia de la compilación de la imagen final y solo se vuelven a compilar las capas necesarias cuando se producen cambios.They improve the efficiency of building the final image—only the necessary layers are rebuilt when changes occur. Cuando las imágenes de intermediario ya no sean necesarias, elimínelas mediante el comando docker rmi.When the intermediary images are no longer needed, delete them using the docker rmi command.

Podría esperarse que la imagen de producción o versión fuera más pequeña que la imagen dev.There may be an expectation for the production or release image to be smaller in size by comparison to the dev image. Debido a la asignación de volumen, el depurador y la aplicación se han ejecutado desde la máquina local y no dentro del contenedor.Because of the volume mapping, the debugger and app were running from the local machine and not within the container. La imagen más reciente ha empaquetado el código de aplicación necesario para ejecutar la aplicación en un equipo host.The latest image has packaged the necessary app code to run the app on a host machine. Por tanto, la diferencia es el tamaño del código de aplicación.Therefore, the delta is the size of the app code.

Recursos adicionalesAdditional resources