Getting Started with ASP.NET
A live example is available at https://aspnet.nullstone.dev.
This quickstart launches an ASP.NET web application to AWS via Nullstone. It also configures a local development environment using Docker that works identical to production, but with debugging enabled.
This quickstart contains a walkthrough for generating an ASP.NET app. A working example is available to fork at nullstone-io/aspnet-quickstart.
This quickstart is based off the official ASP.NET Core get started tutorial.
Create ASP.NET app
In this example, we are going to create an ASP.NET app named
aspnet-quickstart in the current directory. In your repository root, run these commands.
dotnet new webapp --no-https -o . dotnet new gitignore
This will create the following files and directories:
. ├── .vscode ├── Pages ├── Properties ├── wwwroot ├── .gitignore ├── appsettings.Development.json ├── appsettings.json ├── aspnet-quickstart.csproj └── Program.cs
Prepare for Local
Configure docker locally
Nullstone provides a docker image
nullstone/dotnet:local that is configured for local development. The source for the docker image is on GitHub at nullstone-io/docker-dotnet.
docker-compose.yml to run locally using Docker.
version: '3.8' services: db: image: mcr.microsoft.com/mssql/server environment: SA_PASSWORD: "Password1234%^&*" ACCEPT_EULA: "Y" app: image: nullstone/dotnet:local depends_on: - db environment: SQLSERVER_DSN: "Data Source=db;Initial Catalog=master;User ID=sa;Password=Password1234%^&*" ports: - "5001:5001" volumes: - .:/app - ~/.vsdbg:/remote_debugger:rw
Let's start our app locally.
docker compose up
Add your dependencies with
dotnet add .... Then, restart your docker container with
docker compose up or
docker compose restart. The local docker image will install dependencies on boot using
Prepare for Production
Before deploying an ASP.NET app to production, we need to dockerize your app.
Dockerfile with the following contents. This will build your app inside a build image and transfer the app into a production-optimized image.
If you named your project differently, make sure to change
CMD in the
Dockerfile to reflect your project name.
FROM mcr.microsoft.com/dotnet/sdk:6.0-focal AS build WORKDIR /src # Install packages COPY *.csproj . RUN dotnet restore # Copy the rest of app and publish COPY . . RUN dotnet publish -c Release -o /app/publish --no-restore FROM nullstone/dotnet COPY --from=build /app/publish . CMD ["dotnet", "aspnet-quickstart.dll"]
Launch to Nullstone
When launching to Nullstone, we're going to create an app in the Nullstone UI and attach capabilities that automatically configure our app. Follow these steps in the Nullstone UI.
- Create an application.
- Name: In this example, we're naming our app
- App Type:
- Name: In this example, we're naming our app
- From the Domains tab for the application, add a subdomain. (This will automatically attach a load balancer capability)
Create sqlserver datastore
- Create a datastore -
RDS SqlServer Cluster
- Visit your application created in the previous step.
- From the Datastores tab, add the datastore you just created.
Our application is ready to launch. Click "Launch" through the UI or issue
up through the CLI.
nullstone up --wait --app=aspnet-quickstart --env=dev
The current SQL Server Access capability does not automatically set up and inject credentials.
In this quickstart, we are injecting the master db credentials manually.
In production, you should establish a user with specific permissions and inject that user's credentials.
To connect to the database in our app we need to add an environment variable with the database connection string.
- Login to your AWS console to find the master username and password. The name of the secret in the Secrets Manager will be named with the datastore reference followed by
- Add the following environment variable to your application in Nullstone.
SQLSERVER_DSN Data Source=`db_endpoint`;Initial Catalog=master;User ID=`username`;Password=`password`
db_endpoint value can be found on the configuration tab for the datastore under
Once your application is provisioned, you may build and deploy your app.
You can name your image whatever you want, just remember this image name for the deploy step. In this example, we are using an image name of
docker build -t aspnet-app .
launch to push your docker image and deploy the service with a new version.
nullstone launch --source=aspnet-app --app=aspnet-quickstart --env=dev
When pushing your image, Nullstone performs auto-versioning if you are in a git-tracked directory. Nullstone selects the short commit SHA (a unique 8-character token) from the git repository to tag the docker image.
To use a manual version, issue launch with
--version (this example uses
nullstone launch --source=aspnet-app --app=aspnet-quickstart --env=dev --version=1.0.0
Nullstone enforces version/image tag immutability for security reasons.
If you repeatedly push a new docker image without committing anything to git, you will receive an error message like this:
error pushing artifact: error pushing image: tag invalid: The image tag 'c3c7cd83' already exists in the 'periwinkle-louse-fkslv' repository and cannot be overwritten because the repository is immutable.
The easiest way to resolve this is to launch with an indexed version. The following uses the same commit sha, but with a
-2 suffix to distinguish the image tag.
nullstone launch --source=aspnet-app --app=aspnet-quickstart --env=dev --version=c3c7cd83-2