.NET 8.0 local development environment
Describes running your Optimizely Configured Commerce code locally in a Windows 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.
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 thenginx
config uses the same values found in.env
, they only need to be changed here:- 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.
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 anInsite.Commerce
database. Restore a database to mssql after it is running, then rerundocker 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.
Updated 14 days ago