.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 github. When merging, pay close attention to 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 now supports targeting .Net 8.0. There are new 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 a 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.

Determine database/container strategy

Local development is now done via Docker. All necessary base code and services are containerized via a single command included in your project. Before you run this, there are a few things you should consider.

Docker’s default naming convention differs when running your application with the CLI versus running it with Visual Studio. To avoid challenges associated with overlapping container names, you should choose a name for your collection of containers before building them. When running docker with the CLI, you can specify the name for the project with the -p option. A similar result can be achieved by adding the DockerComposeProjectName property in the .dcproj file in the project root.

The database for your application is created within the Docker project by default. If you have an existing database that you would like to use instead, you can modify the database connection string with the .env file in the project root.

The database and ElasticSearch containers mount their data to your OS’s file system in your project root. This allows the databases and ElasticSearch indexes to be persisted between Docker project builds. You can change the location of this mount by modifying the docker-compose.yml file in the project root.

Running containers

You can run your project in one of a few ways.

Docker Compose

Run docker compose up -d from the root of your project. It starts up all necessary containers including mssql and elasticsearch.

Visual Studio

Visual Studio 2022 can run and debug a Docker project. Select the InsiteCommerce Docker project from the Startup Projects drop-down list and begin a debug session. This builds your Extensions project and creates all necessary Docker containers.

Rider

There is a run configuration included with the release titled InsiteCommerce. It can be used to start up the containers in the docker compose file and attach a debugger.

Use LocalStack to run with a storage provider locally

Running .NET with a storage provider locally requires using LocalStack, a drop-in replacement for AWS services.
LocalStack is now in the Docker-compose file, and by default it initializes with all the files from ./src/InsiteCommerce.Web/UserFiles.

Initial setup

1. Ensure you have an updated Docker-compose with the entry for localstack.
2. Ensure these settings are in your .env file:
   AmazonS3StorageProviderBucketName=userfiles
AmazonS3StorageProviderCustomDomain=http://host.docker.internal:4566
3. Restart everything in docker.
4. Log into the Admin Console and modify the SystemSetting for StorageProvider to AmazonS3.
5. Validate that Content - Media displays the images from your local ./src/InsiteCommerce.Web/UserFiles folder.

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.

Access Configured Commerce

Spire

If you are running a Spire site, you must build Spire separately. If you are using the default Docker compose, Spire uses http\://localhost:30000 as its API URL. The Docker project uses NGINX to route all API requests from this endpoint to the appropriate services. Once your Spire build is complete, you can access your local site by using whichever port you have configured for your node server, such as http\://localhost:3000.

Classic

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

Known Issues

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

• DatabaseUpdater does not run the sql scripts from Extensions – The DatabaseUpdater container does not include the Extensions.dll so it is not able to run any sql scripts from it. As a work around, you can point a net48 site at the same database and run any sql scripts.

• FileSystem StorageProvider has issues – By default Configured Commerce uses the FileSystem. With three running containers that do not share a file system, it does not work as expected. Optimizely plans on evaluating if the same directory can be mapped into the three running containers or if LocalStack must be included in the docker compose.

• Error Page/Modal is blank – When an exception occurs loading a page, or making a request to an API, an elmah error details page is displayed. When running in the container setup with ASPNETCORE_ENVIRONMENT=Development it takes ~10 seconds to load the error details to populate the page.

• Exceptions not logged to ApplicationLog – When an exception occurs while running in the container setup 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.