Skip to main content
Version: 1.47

Getting Started with Okteto and ASP.NET

Okteto runs your ASP.NET Core application in Kubernetes while you edit it on your machine: every time you save a file, the change runs in your cluster a few seconds later, and you can debug it with breakpoints from your IDE. The ASP.NET Core Sample App, a hello world web API, is configured so that Okteto builds, deploys, and tests it directly in your Kubernetes cluster. To do the same in your own repository, we recommend using an AI agent with the Okteto agent skills.

Prerequisites​

  • The Okteto CLI, installed and configured to access your Okteto instance. See the installation guide.
  • To debug the application: VS Code with the C# extension, and an ssh client on your machine.

Clone the ASP.NET Core Sample App:

git clone https://github.com/okteto/aspnetcore-getting-started
cd aspnetcore-getting-started

The Dockerfile​

The Dockerfile of the ASP.NET Core Sample App defines two images, one per stage:

Dockerfile
FROM mcr.microsoft.com/dotnet/sdk:10.0.404-noble AS dev

RUN curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v 18.7.10521.2 -l /usr/local/bin/vsdbg

WORKDIR /usr/src/app
COPY helloworld.csproj .
RUN dotnet restore
COPY . .
RUN dotnet build && \
dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0.15-noble-chiseled AS prod

WORKDIR /app
COPY --from=dev /app .
ENTRYPOINT ["dotnet", "helloworld.dll"]
  • dev is the development image. It contains the .NET SDK, which includes dotnet watch for hot reload, vsdbg for debugging, and the source code. dotnet build fills the bin and obj folders of the image, so the first build of dotnet watch in the Development Container is incremental. dotnet publish writes the application to /app.
  • prod is the application image. It contains only the ASP.NET Core runtime and the application published in the dev stage. Chiseled images have no shell or package manager, and run as a non-root user.

The dev stage follows the recommendations for development images: every version is pinned, and the stage that builds the application doubles as the development image.

The Okteto Manifest​

The okteto.yml file is the Okteto Manifest of the ASP.NET Core Sample App.

Build​

The build section builds both images:

okteto.yml
build:
dev:
context: .
target: dev
hello-world:
context: .
target: prod
depends_on:
- dev

target selects a stage of the Dockerfile. depends_on makes Okteto build the dev image first, so hello-world reuses its cached layers. Okteto pushes both images to the Okteto Registry and stores their references in the OKTETO_BUILD_DEV_IMAGE and OKTETO_BUILD_HELLO_WORLD_IMAGE variables.

Deploy​

The deploy section installs the Helm chart in the chart folder, with the application image that Okteto built:

okteto.yml
deploy:
image: alpine/helm:4.3.2
commands:
- helm upgrade --install hello-world chart --set image=${OKTETO_BUILD_HELLO_WORLD_IMAGE}

The command runs with Remote Execution, in a container inside your cluster that uses the image set in deploy.image, so you don't need Helm on your machine.

Deploying the ASP.NET Core Sample App​

Run okteto deploy from the root folder of the ASP.NET Core Sample App:

okteto deploy

Okteto builds the dev and hello-world images, runs the deploy command, and prints the endpoint of the application:

i Using cindy @ okteto.example.com as context
✓ Image 'registry.okteto.example.com/cindy/aspnetcore-getting-started-dev:okteto' successfully pushed
✓ Image 'registry.okteto.example.com/cindy/aspnetcore-getting-started-hello-world:okteto' successfully pushed
i Running stage 'helm upgrade --install hello-world chart --set image=${OKTETO_BUILD_HELLO_WORLD_IMAGE}'
Executing command 'helm upgrade --install hello-world chart --set image=${OKTETO_BUILD_HELLO_WORLD_IMAGE}'...
Release "hello-world" does not exist. Installing it now.
NAME: hello-world
NAMESPACE: cindy
STATUS: deployed
REVISION: 1
i Endpoints available:
- https://hello-world-cindy.okteto.example.com
✓ Development environment 'aspnetcore-getting-started' successfully deployed

Open the endpoint in your browser to see the Hello world! response. The Okteto UI shows the same endpoint:

Okteto UI showing the cindy Namespace with the aspnetcore-getting-started Dev Environment deployed, its hello-world Deployment running, and its endpoint

Okteto creates an HTTPS endpoint for the Ingress in the Helm chart.

Testing the ASP.NET Core Sample App​

The test section of the Okteto Manifest defines a Test Container that runs the xUnit tests of the tests folder:

okteto.yml
test:
unit:
image: ${OKTETO_BUILD_DEV_IMAGE}
caches:
- /root/.nuget/packages
commands:
- dotnet test --project tests --report-xunit-trx --report-xunit-trx-filename test-results.trx --results-directory .
artifacts:
- test-results.trx
  • image: the development image, so the tests run with the same .NET SDK as the Development Container.
  • caches: the NuGet packages folder, kept between runs of the Test Container.
  • commands: the commands that run the tests. dotnet test builds the tests project, runs its tests, and writes the results to test-results.trx. The Test Container fails if any of them exits with a non-zero code.
  • artifacts: the files that Okteto copies to your machine when the tests finish, in this case the test results.

xUnit v3 runs on Microsoft.Testing.Platform, and the global.json file tells dotnet test to use it:

global.json
{
"test": {
"runner": "Microsoft.Testing.Platform"
}
}

Test Containers run with Remote Execution, in a container inside your cluster.

Run the unit tests from the root folder of the ASP.NET Core Sample App:

okteto test
i Using cindy @ okteto.example.com as context
i Images were already built. To rebuild your images run 'okteto build'
i Executing test container 'unit'
i Running 'dotnet test --project tests --report-xunit-trx --report-xunit-trx-filename test-results.trx --results-directory .'
Running tests from /okteto/src/tests/bin/Debug/net10.0/helloworld.Tests.dll (net10.0|x64)
/okteto/src/tests/bin/Debug/net10.0/helloworld.Tests.dll (net10.0|x64) passed (731ms)
In process file artifacts produced:
- /okteto/src/test-results.trx
Test run summary: Passed!
total: 1
failed: 0
succeeded: 1
skipped: 0
duration: 973ms
✓ Command 'dotnet test --project tests --report-xunit-trx --report-xunit-trx-filename test-results.trx --results-directory .' successfully executed
✓ Test container 'unit' passed

The test results are now in test-results.trx, in the root folder of the ASP.NET Core Sample App on your machine. TRX is the test results format of Visual Studio and Azure Pipelines.

Running okteto deploy and okteto test after each change is usually fast enough, especially when an AI agent writes and tests the code autonomously. With the Okteto agent skills, the agent runs this loop in its own Namespace and reports back the tests it ran, the endpoints of the application, and a link to that Namespace.

Developing in a Development Container​

If you use AI agents, the Development Container is optional: agents work well with the okteto deploy and okteto test cycle, and don't need one. A Development Container gives you the experience of developing on your machine, with hot reload and a debugger on every change. When you run okteto up, Okteto replaces the hello-world Deployment with the Development Container, keeps your local files synchronized with it, and runs the hot-reload and debugging tools of the development image in your cluster.

While okteto up is running, an AI agent with the Okteto agent skills skips the build and deploy cycle: your changes already reach the Development Container through File Sync, so the agent waits for you to tell it what to run next.

Configuration​

The dev section of the okteto.yml file defines the Development Container of the ASP.NET Core Sample App:

okteto.yml
dev:
hello-world:
image: ${OKTETO_BUILD_DEV_IMAGE}
command: dotnet watch
sync:
- .:/usr/src/app
persistentVolume:
enabled: false
securityContext:
capabilities:
add:
- SYS_PTRACE

The hello-world key matches the name of the Deployment in the Helm chart. These are the fields of the Development Container:

  • image: the development image built in the build section.
  • command: starts dotnet watch, which builds and runs the application. When a .cs file changes, dotnet watch applies the change to the running application with hot reload, or rebuilds and restarts the application if hot reload can't apply it.
  • sync: synchronizes the root folder of the ASP.NET Core Sample App with /usr/src/app, the working directory of the development image.
  • persistentVolume: disables the persistent volume of the Development Container. Okteto synchronizes the files again on every okteto up, and the NuGet packages and the build output come from the development image, so there's no volume to create and attach. In projects with many dependencies, enable it and add /root/.nuget/packages to volumes to keep the NuGet cache between okteto up sessions.
  • securityContext: adds the SYS_PTRACE capability that vsdbg needs to attach to the application.

Hot reload​

Run okteto up to replace the hello-world Deployment with the Development Container:

okteto up

Okteto synchronizes your files and starts dotnet watch, which builds and runs the application:

i Using cindy @ okteto.example.com as context
i 'aspnetcore-getting-started' was already deployed. To redeploy run 'okteto deploy' or 'okteto up --deploy'
✓ Images successfully pulled
✓ Files synchronized
Context: okteto.example.com
Namespace: cindy
Name: hello-world

dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload.
helloworld -> /usr/src/app/bin/Debug/net10.0/helloworld.dll
Build succeeded.
dotnet watch ⌚ Waiting for changes
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://[::]:8080
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.

Open Controllers/HelloWorldController.cs in your IDE, change the response message on line 12 to Hello world from Okteto!, and save the file:

Controllers/HelloWorldController.cs
[HttpGet]
public string Get()
{
var message = "Hello world from Okteto!";
return message;
}

Okteto synchronizes HelloWorldController.cs to the Development Container, and dotnet watch applies the change to the running application without restarting it:

dotnet watch ⌚ File updated: ./Controllers/HelloWorldController.cs
dotnet watch 🔥 C# and Razor changes applied in 731ms.

Reload the endpoint in your browser to see the new message. The change runs in your cluster without building an image or redeploying the application.

Press Ctrl+C to stop dotnet watch and exit okteto up.

Debugging with VS Code​

vsdbg attaches to the application that dotnet watch runs, so keep okteto up running. VS Code starts vsdbg in the Development Container over SSH: okteto up adds the hello-world.okteto host to your SSH configuration, and the .vscode/launch.json file of the ASP.NET Core Sample App runs vsdbg through it:

.vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Connect to okteto",
"type": "coreclr",
"request": "attach",
"processId": "${command:pickRemoteProcess}",
"pipeTransport": {
"pipeProgram": "ssh",
"pipeArgs": ["-q", "-T", "hello-world.okteto"],
"debuggerPath": "/usr/local/bin/vsdbg/vsdbg",
"pipeCwd": "${workspaceFolder}",
"quoteArgs": true
},
"sourceFileMap": {
"/usr/src/app": "${workspaceFolder}"
}
}
]
}

sourceFileMap maps /usr/src/app, the path in the sync field of the Okteto Manifest, to the folder that you open in VS Code. If you synchronize your code to another path, change sourceFileMap to match it. vsdbg only works with the Microsoft builds of VS Code and Visual Studio.

Open the ASP.NET Core Sample App in VS Code, open the Run and Debug view, and run the Connect to okteto configuration. VS Code lists the processes of the Development Container: select helloworld, the process of /usr/src/app/bin/Debug/net10.0/helloworld. Add a breakpoint on line 12 of Controllers/HelloWorldController.cs and reload the endpoint in your browser. Execution stops at the breakpoint, and you can inspect the request and the variables.

To end the debugging session, click Disconnect in the debug toolbar. vsdbg detaches, and the application keeps running with dotnet watch.

Cleaning up​

okteto down stops the Development Container and brings back the hello-world Deployment with the application image:

okteto down

When you're done, okteto destroy uninstalls the Helm release of the ASP.NET Core Sample App from your Namespace:

okteto destroy

FAQ​

How do I make builds, deploys, and okteto up faster?​

Upload only the files that each command needs: the context upload is key to performance. Every okteto build, okteto deploy, okteto test, and okteto up uploads files from your machine, and three ignore files decide what gets uploaded: .dockerignore for the image builds, .oktetoignore for okteto deploy, okteto test, and okteto destroy, and .stignore for File Sync. An AI agent with the Okteto agent skills configures them for your application and measures how much faster your builds, deploys, and okteto up get. Optimize your Development Environments covers these and other optimizations.

How do I deploy an application with several services and a database?​

Follow Deploy Your Application to Okteto if you deploy with a Helm chart, or Develop a Docker Compose application with Okteto if you use Docker Compose. If your services live in several repositories, see Deploy a multi-repo application with dependencies.

Do I need to deploy the whole application in every Namespace?​

No. Divert lets you deploy only the services you change and reuse the services of a shared environment.

How do I start each environment with realistic data?​

Create its database from a Volume Snapshot instead of running a seed script on every deploy. Data from Volume Snapshots shows how.

How do I create resources outside Kubernetes, such as a cloud database?​

Create them in the deploy and destroy commands with your infrastructure as code tool, so every environment gets its own cloud resources. Create cloud infrastructure with Terraform shows how, with an Amazon S3 bucket for each environment.

Where can I find every field of the Okteto Manifest?​

The Okteto Manifest reference lists every field of build, deploy, destroy, test, and dev.