.NET 8.0 local development environment

👍

Beta

.NET8 is currently in beta for Optimizely Configured Commerce. Talk to your implementation partner about reviewing your custom extensions as they begin testing .NET8.

📘

Note

You must have .NET8, Docker Desktop, and Visual Studio 2022. Setting up these programs is outside the scope of this article.

Merge most recent code

Pull the most recent code from Git Hub. When merging, note the changes in base for both the .sln and .csproj files. The .sln has moved to the root and now has references to projects for the Storefront API, Admin API, Integration, the Docker compose, and files at the root of the project.

The Extensions project supports targeting .Net 8.0. There are properties in the .csproj that are conditionally included based on the target framework. These must be included in .csproj to get the project to build. Any third-party references should be included or excluded based on the .NET versions they support. By default, it targets net48. That can be changed to net8.0 or net48;net8.0

InsiteCommerce.Web causes a build failure if you set your Extensions project target to net8.0. This is a known issue that will be resolved in a future release. For now, you can remove the project reference to Extensions.csproj from InsiteCommerce.Web.csproj.

Build extensions

You most likely need to make changes to your Extensions code before you are able to build it successfully. The .NET8 framework article contains additional details on some of the common scenarios you might run see. You must build your Extensions project before you can run the code locally.

Getting Started

From the root of the repo, run the following. It starts all necessary services, including MySQL, Elasticsearch, and more.

docker compose up -d

In later releases, Docker Compose was changed to include profiles. To start all containers, run the following:

docker compose --profile apps up -d

Build and run the following projects. Depending on your needs, not all of these are required to be running. See the details about each project below.

• Admin.Api
• Storefront.Api
• Integration.Api

Notes

• Your extensions project must compile in .NET8 for this to work.
• You can run the projects with your IDE or the command line using dotnet run.
• Optimizely has not tested how well watch or hot-reload work.
• Currently, the above docker compose command fails because it does not initialize a database for Insite.Commerce. You must restore a database onto the SQL server then rerun the docker compose up -d command.

Access Configured Commerce

Classic

If you are running a Classic site, you can access it on http\://localhost:30100.

Spire

If you run a Spire site, you must build and start Spire separately.

cd src/FrontEnd
npm install
npm run start

You can access your Spire website on http\://localhost:30000.

Configuration

Configuration takes place in the .env. Some variables to note:

• DB_CONNECTION_STRING – The main connection string
• CLASSIC_PORT – The port that classic-proxy listens on. For running multiple projects locally, this must be changed.
• SPIRE_PORT – The port that spire-proxy listens on. For running multiple projects locally, this must be changed.
• Other Ports – The rest of the netcore services that nginx proxies to. Because the nginx config uses the same values found in .env, they only need to be changed here:
  • IDENTITY_WEB_PORT
  • SPIRE_WEB_PORT
  • STOREFRONT_API_PORT
  • ADMIN_API_PORT
  • INTEGRATION_API_PORT

Overview of Projects

Admin.Api

Handles traffic for the Admin Console and both Classic and Spire CMS and serves up theme bundles for Classic. As of 2405, this runs internal WIS jobs if the environment variable ADMIN_STARTS_INTERNAL_WIS=true.

Storefront.Api

Handles running the storefront API.

Integration.Api

Handles running the integration API and running internal WIS jobs. Can be left off if using Admin.Api to run internal WIS jobs and not testing integration.

Overview of Containers

The docker-compose in the root contains all services needed to run a Configured Commerce site.

When running docker with the CLI, you can specify the name for the project with the -p option. You can achieve a similar result by adding the DockerComposeProjectName property in the .dcproj file in the project root.

database-updater

Handles running change scripts. Must be rebuilt and rerun if you update Configured Commerce versions or add additional change scripts in extensions.

identity-web

Handles identity-related traffic. Needed to login to the storefront or Admin Console.

mssql

Maps folders at .sql into the running container to retain the database between restarts by default.

A single instance can be used across multiple projects.

elasticsearch (Elasticsearch 5)

A single instance can be used across multiple projects.

elasicsearchnext (Elasticsearch 7)

A single instance can be used across multiple projects.

ironpdfengine

Needed for any code that generates PDFs. A single instance can be used across multiple projects.

classic-proxy

Nginx ingress for the Classic site. This is not needed for Spire-only sites.

The configuration is at .config/nginx/default.conf.template.

spire-proxy

Nginx ingress for the Spire site. This is not needed for Classic-only sites.

The configuration is at .config/nginx/default.conf.template.

localstack

Running .NET with a storage provider locally requires using LocalStack, a drop-in replacement for AWS services.
The free version does not persist files after a restart but it is setup to map all files from /src/InsiteCommerce.Web/UserFiles into LocalStack when the LocalStack is started.

If you need to connect to LocalStack for debugging, you can use CyberDuck # Open Connection.

Select Amazon S3 as the connection type:

• Server – localhost
• Port – 4566
• Access Key Id – [AnyValue]
• Secret Access Key – [AnyValue]

Click Connect.

mailhog

Used as the SMTP server with the standard set up. You can view mail at http\://localhost:8025

By default, SMTP uses 2525.

A single instance can be used across multiple projects

Minimize running containers

Out of the box, the docker compose runs all services whether they are needed or not. To save resources, make modifications to only start what is needed, such as removing classic-proxy if working only with Spire.

Sharing services between projects is also possible. The default compose file uses depends_on to ensure things start in the correct order. You would need to modify this.

SQL Server could be run natively or from a shared docker container. If using a shared container, consider the volume mapping. Having the shared container mapping a volume specific to a single project is not recommended.

Running Apps as Containers

The three startup apps (admin, storefront, and integration) are also included in the docker-compose.yml file. If you want to run them with docker, you can use the command docker compose --profile apps up -d

Running them as containers can be useful because it is closer to how they run in production. It can help troubleshoot Linux versus Windows issues and let you start everything up quickly with a single command.

Known Issues

• DatabaseUpdater fails to start – When initially running docker compose up -d, the DatabaseUpdater container fails. This is because when mssql starts for the first time, it does not contain an Insite.Commerce database. Restore a database to mssql after it is running, then rerun docker compose up -d.

• Exceptions not logged to ApplicationLog – When an exception occurs while running in the container set up with ASPNETCORE_ENVIRONMENT=Development, those exceptions are not logged to the ApplicationLog table. The exception details are written out to the console of the container.