You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/2-environment-setup.md
+24-12Lines changed: 24 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,22 +1,25 @@
1
1
---
2
-
title: Environment setup
2
+
title: Set up an Arm-based environment
3
+
description: Set up an Ubuntu Azure Cobalt-based virtual machine with Docker, .NET 9, and PostgreSQL so you can build and validate nopCommerce on Arm.
3
4
weight: 2
4
5
5
6
### FIXED, DO NOT MODIFY
6
7
layout: learningpathall
7
8
---
8
9
9
-
#Environment setup
10
+
## Set up a Microsoft Azure virtual machine powered by Cobalt 100
10
11
11
-
Set up an Arm Cobalt environment first, then keep your toolchain and runtime configuration stable across all test runs. This creates a reliable Arm baseline for migration and tuning work.
12
+
Set up an Arm Azure environment first, then keep your toolchain and runtime configuration stable across all test runs. This creates a reliable Arm baseline for migration and tuning work.
12
13
13
-
Start with the official [Azure Cobalt setup guide](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cobalt/) and complete VM provisioning there first.
14
+
Start with the [Azure Cobalt Learning Path](/learning-paths/servers-and-cloud-computing/cobalt/) and complete VM provisioning.
14
15
15
-
This path was validated with Ubuntu 24.04 LTS on Azure Cobalt in `westus2` (example VM size: `Standard_D2ps_v6`, 2 vCPUs).
16
+
The Learning Path was validated with Ubuntu 24.04 LTS on Azure Cobalt in `westus2` (example VM size: `Standard_D2ps_v6`, 2 vCPUs).
16
17
17
-
## Install tools on Cobalt VM
18
+
###Install tools on the Azure virtual machine
18
19
19
-
Install the toolchain on the Cobalt VM before building and testing. The commands install the Linux packages used throughout this Learning Path: source control, HTTP validation, JSON inspection, Python for the endpoint tester, package archive inspection, Docker, and the .NET 9 SDK from the Ubuntu backports feed.
20
+
Install the toolchain on the Azure VM before building and testing.
21
+
22
+
The following commands install the Linux packages used throughout this Learning Path: source control, HTTP validation, JSON inspection, Python for the endpoint tester, package archive inspection, Docker, and the .NET 9 SDK from the Ubuntu backports feed:
The Docker group change applies to new login sessions. Sign out and sign back in before running Docker without `sudo`, or run `newgrp docker` in the current terminal before continuing.
32
35
33
-
Confirm architecture and tool versions before proceeding. On Azure Cobalt, the Linux machine architecture should be `aarch64`, and the .NET SDK should be a 9.0.x release.
36
+
Confirm architecture and tool versions before proceeding:
34
37
35
38
```bash
36
39
uname -m
37
40
dotnet --version
38
41
docker --version
39
42
```
43
+
On Azure Cobalt, the Linux machine architecture should be `aarch64`, and the .NET SDK should be a `9.0.x` release.
40
44
41
45
The output is similar to:
42
46
@@ -46,13 +50,15 @@ aarch64
46
50
Docker version ...
47
51
```
48
52
49
-
If you are upgrading from an older .NET version before migrating to Cobalt, you can use [GitHub Copilot modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization/overview) to assess the project and guide the upgrade. In Visual Studio Code, open Copilot Chat and use `@modernize-dotnet`; in Visual Studio, use the Modernize action from Solution Explorer.
53
+
If you're upgrading from an older .NET version before migrating to Cobalt, use [GitHub Copilot modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization/overview) to assess the project and guide the upgrade. In Visual Studio Code, open Copilot Chat and use `@modernize-dotnet`. In Visual Studio, use the **Modernize** action from **Solution Explorer**.
54
+
55
+
### Enable citext to satisfy PostgreSQL prerequisite
50
56
51
-
## PostgreSQL prerequisite for nopCommerce install
57
+
nopCommerce defaults to SQL Server, but you'll use PostgreSQL for Arm validation. For PostgreSQL installs, you need `citext` before migration and installation. Without it, installer migrations fail with `type "citext" does not exist` (captured in local test artifacts).
52
58
53
-
nopCommerce defaults to SQL Server, but this learning path uses PostgreSQL for Arm validation. For PostgreSQL installs, `citext` is required before migration/installation. Without it, installer migrations fail with `type "citext" does not exist` (captured in local test artifacts).
59
+
Create PostgreSQL and enable `citext` before running the installer. The database runs in Docker on the VM so the nopCommerce app can connect to `127.0.0.1:5432` during the local validation phase.
54
60
55
-
Create PostgreSQL and enable `citext` before running the installer. The database runs in Docker on the Cobalt VM so the nopCommerce app can connect to `127.0.0.1:5432` during the local validation phase. Replace the password value before running the command.
61
+
Replace the password value before running the following commands:
The `docker exec` command should print `CREATE EXTENSION`. If it prints `NOTICE: extension "citext" already exists, skipping`, the database is already prepared and you can continue.
79
+
80
+
## What you've accomplished and what's next
81
+
82
+
You've set up an Arm-based environment by creating a Microsoft Azure VM powered by Cobalt 100 with Docker, .NET 9, and PostgreSQL ready for nopCommerce validation.
83
+
84
+
Next, you'll create a reproducible baseline to use for benchmarking.
Copy file name to clipboardExpand all lines: content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/3-checkout-build-baseline.md
+36-17Lines changed: 36 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,18 +1,23 @@
1
1
---
2
-
title: Build and baseline
2
+
title: Create a nopCommerce endpoint benchmark baseline on Arm
3
+
description: Build a pinned nopCommerce release on Arm and run a repeatable endpoint benchmark to create a baseline for later tuning.
3
4
weight: 3
4
5
5
6
### FIXED, DO NOT MODIFY
6
7
layout: learningpathall
7
8
---
8
9
9
-
# Build and baseline
10
+
##Build nopCommerce and create an endpoint baseline
10
11
11
-
Create a reproducible Arm baseline before optimization work. This page pins source, verifies a clean build, and captures a representative endpoint baseline so later changes can be measured against a known control.
12
+
Create a reproducible Arm baseline before optimization work.
12
13
13
-
## Clone and pin the source
14
+
You'll pin the source, verify a clean build, and capture a representative endpoint baseline so you can measure later changes against a known control.
14
15
15
-
Pinning the exact tag and commit avoids silent drift in dependencies and behavior. Run these commands on the Cobalt VM. The later commands assume you are in the `nopCommerce` repository root unless a section says otherwise.
16
+
### Clone and pin the source
17
+
18
+
Pinning the exact tag and commit avoids silent drift in dependencies and behavior.
19
+
20
+
Run the following commands on the Arm-based virtual machine (VM):
Later commands in the section assume you're in the `nopCommerce` repository root unless stated otherwise.
24
30
25
31
If you open a new terminal later, return to the same repository root before running commands:
26
32
27
33
```bash
28
34
cd~/nopCommerce # replace with your clone path if different
29
35
```
30
36
31
-
## Restore and build on Arm
37
+
###Restore and build on Arm
32
38
33
-
Run the restore and build on the Arm-based VM to establish a native Arm baseline. Restoring first separates package resolution problems from compilation problems, and `--no-restore` makes the build validate the already restored dependency graph.
39
+
Run restore and build on the Arm-based VM to establish a native Arm baseline:
34
40
35
41
```bash
36
42
# Restore dependencies first so build failures are easier to triage.
Restoring first separates package resolution problems from compilation problems, and `--no-restore` makes the build validate the already restored dependency graph.
42
49
43
-
## Start and install nopCommerce
50
+
###Start and install nopCommerce
44
51
45
-
Start the app locally and complete installer setup with PostgreSQL. Run this command in one terminal and leave it running; `dotnet run` hosts the web application and keeps the terminal attached to the server logs.
52
+
Start the app locally and complete installer setup with PostgreSQL.
53
+
54
+
Run the following command in one terminal and leave it running:
46
55
47
56
```bash
48
57
cd src/Presentation/Nop.Web
49
58
dotnet run -c Release --no-build --urls http://0.0.0.0:5000
50
59
```
60
+
`dotnet run` hosts the web application and keeps the terminal attached to the server logs.
51
61
52
62
In a browser, open `http://<cobalt-public-ip>:5000` or use an SSH tunnel to reach `http://127.0.0.1:5000`. On the nopCommerce install page, select PostgreSQL and use the database settings from the previous section:
Expected after successful install: `root=200`, `install=302`.
84
+
The outputs after a successful install should be: `root=200`, `install=302`.
75
85
76
-
##Baseline methodology
86
+
### Run the endpoint baseline benchmark
77
87
78
-
Do not benchmark `/install`. Baseline stable storefront paths first, then add cart and attribute-change routes only after you know the valid product IDs, attribute IDs, request method, and anti-forgery token behavior for your installed store.
88
+
Don't benchmark `/install`. Baseline stable storefront paths first, then add cart and attribute-change routes only after you know the valid product IDs, attribute IDs, request method, and anti-forgery token behavior for your installed store.
79
89
80
90
-`/`
81
91
-`/search/`
@@ -84,7 +94,7 @@ Do not benchmark `/install`. Baseline stable storefront paths first, then add ca
84
94
- Product and category pages from your sample data
85
95
- Cart or checkout endpoints from a recorded production-like workflow
86
96
87
-
Create the endpoint tester in the repository root. The script uses only the Python standard library, submits requests with fixed concurrency, treats non-2xx and non-3xx responses as errors, and writes raw samples plus per-route summaries to JSON.
97
+
Create the endpoint tester in the repository root:
The script uses only the Python standard library, submits requests with fixed concurrency, treats non-2xx and non-3xx responses as errors, and writes raw samples plus per-route summaries to JSON.
212
+
201
213
Run the endpoint tester from the repository root while the app is still running in the first terminal:
The command prints the per-route summary and writes the raw measurements to `arm_before.json`. Keep that JSON file unchanged; it is the baseline artifact used by the tuning step.
224
+
The command prints the per-route summary and writes the raw measurements to `arm_before.json`. Keep that JSON file unchanged because it's the baseline artifact used in the tuning step.
213
225
214
-
## Baseline quality rules
226
+
###Baseline quality rules
215
227
216
228
Use these rules before you compare any optimization result:
217
229
218
-
- Run at least 3 baseline trials with identical parameters.
219
-
- Keep endpoint order fixed per run (not randomized) when comparing before vs after.
230
+
- Run at least three baseline trials with identical parameters.
231
+
- Keep endpoint order fixed per run (not randomized) when comparing before and after.
220
232
- Keep database state and seeded data identical across runs.
221
233
- Capture raw JSON for every run and compare medians, not single outliers.
222
234
223
235
This baseline process becomes the control for every later tuning or code-change decision.
236
+
237
+
## What you've accomplished and what's next
238
+
239
+
You've now pinned the nopCommerce source, verified the build, installed the app, and captured `arm_before.json` as your endpoint baseline.
title: Generate an SBOM and run .NET dependency discovery before migration
3
+
description: Audit .NET dependencies, generate a CycloneDX SBOM, and inspect native package payloads before migrating nopCommerce to Arm.
3
4
weight: 4
4
5
5
6
### FIXED, DO NOT MODIFY
6
7
layout: learningpathall
7
8
---
8
9
9
-
# Audit dependencies
10
+
##Audit application dependencies
10
11
11
-
Run dependency discovery before migration changes so you understand direct references, transitive risk, and hidden native payloads. This avoids late surprises when deploying to Arm.
12
+
Run dependency discovery before migration changes so you understand direct references, transitive risk, and hidden native payloads. By doing so, you'll avoid late surprises when deploying to Arm.
12
13
13
-
### 1. Map direct references
14
+
### Map direct references
14
15
15
-
Start from the `nopCommerce` repository root. Project-level references show what the app explicitly depends on before NuGet expands the graph. The command searches project files under `src` and prints file names and line numbers so you can jump directly to the owning project.
16
+
Start from the `nopCommerce` repository root. Project-level references show what the app explicitly depends on before NuGet expands the graph.
17
+
18
+
Run the following command to search project files under `src` and print file names and line numbers, so you can jump directly to the owning project:
16
19
17
20
```bash
18
21
rg -n "<PackageReference|<ProjectReference" src
19
22
```
20
23
21
-
### 2. List transitive dependencies
24
+
### List transitive dependencies
22
25
23
-
Enumerate the full dependency graph for the web entry point. Transitive packages often carry architecture-sensitive constraints, so review the output for runtime-specific package names, native library packages, image processing libraries, database providers, and platform-specific assets.
26
+
Enumerate the full dependency graph for the web entry point:
24
27
25
28
```bash
26
29
dotnet list src/Presentation/Nop.Web/Nop.Web.csproj package --include-transitive
27
30
```
31
+
Transitive packages often carry architecture-sensitive constraints. Review the output for runtime-specific package names, native library packages, image processing libraries, database providers, and platform-specific assets.
28
32
29
-
### 3. Generate an SBOM
33
+
### Generate an SBOM
30
34
31
-
Generate an SBOM so you can track all components, versions, and exposure surface as a first-class migration artifact. While not strictly necessary for migration purposes, this is a best practice that will save your team time down the road. You can also give this SBOM to an LLM to extract insights about your codebase for you.
35
+
Generate an SBOM so you can track all components, versions, and exposure surface as a first-class migration artifact. While not strictly necessary for migration purposes, this is a best practice that'll save time. You can also give this SBOM to an LLM to extract insights about your codebase.
32
36
33
37
The CycloneDX tool is installed as a .NET global tool. Add `~/.dotnet/tools` to `PATH` in the current shell so the `dotnet-CycloneDX` command is available immediately after installation.
The `-rs` option includes project references, and `-F Json` writes JSON output that is easier to diff in CI. If tool installation is blocked, treat `dotnet list --include-transitive` plus `*.deps.json` evidence as a temporary fallback, not the final state.
47
+
The `-rs` option includes project references, and `-F Json` writes JSON output that's easier to diff in CI. If tool installation is blocked, treat `dotnet list --include-transitive` plus `*.deps.json` evidence as a temporary fallback, not the final state.
42
48
43
-
### 4. Inspect package internals for native payloads
49
+
### Inspect package internals for native payloads
44
50
45
-
Inspect package contents directly when a dependency looks architecture-sensitive. NuGet package folders are usually lower case on Linux, so set `PACKAGE_ID` to the folder name under `~/.nuget/packages` and `PACKAGE_VERSION` to the version you want to inspect.
51
+
Inspect package contents directly when a dependency looks architecture-sensitive. NuGet package folders are usually lower case on Linux, so set `PACKAGE_ID` to the folder name under `~/.nuget/packages` and `PACKAGE_VERSION` to the version you want to inspect:
If the command prints `runtimes/linux-arm64`, the package already carries an Arm Linux asset. If it prints only `linux-x64`, `win-x64`, or another non-Arm runtime, trace whether that asset is used by nopCommerce before you treat the dependency as portable. If there is no output, the package does not advertise runtime or native payload directories in the `.nupkg`.
64
+
If the command prints `runtimes/linux-arm64`, the package already carries an Arm Linux asset. If it prints only `linux-x64`, `win-x64`, or another non-Arm runtime, trace whether that asset is used by nopCommerce before you treat the dependency as portable. If there's no output, the package doesn't advertise runtime or native payload directories in the `.nupkg`.
65
+
66
+
### Dependency cascade rule
67
+
68
+
Treat dependencies as a chain, not isolated items.
59
69
60
-
## Dependency cascade rule
70
+
Assume the app depends on library A, library A depends on library B, library B is architecture-sensitive. In this scenario, you must resolve B first, then validate A, then validate the app.
61
71
62
-
Treat dependencies as a chain, not isolated items:
72
+
## What you've accomplished and what's next
63
73
64
-
- App depends on library A
65
-
- Library A depends on library B
66
-
- Library B is architecture-sensitive
74
+
You've now mapped direct and transitive dependencies, generated an SBOM, and checked packages for native payloads that could affect Arm deployment.
67
75
68
-
You must resolve B first, then validate A, then validate the app.
76
+
Next, you'll explore options to containerize and migrate the application.
0 commit comments