Merge pull request #3465 from pareenaverma/content_review

Tech review of nopcommerce dotnet LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/2-environment-setup.md

@@ -16,47 +16,57 @@ This path was validated with Ubuntu 24.04 LTS on Azure Cobalt in `westus2` (exam
 
 ## Install tools on Cobalt VM
 
-Install the toolchain on the Cobalt VM before building and testing.
+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.
 
 ```bash
 sudo apt-get update -y
-sudo apt-get install -y git curl jq ca-certificates gnupg docker.io
+sudo apt-get install -y git curl jq python3 ripgrep unzip ca-certificates gnupg software-properties-common docker.io
 sudo usermod -aG docker "$USER"
 
 sudo add-apt-repository ppa:dotnet/backports -y
 sudo apt-get update -y
 sudo apt-get install -y dotnet-sdk-9.0
 ```
 
-Verify:
+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.
 
-Confirm architecture and tool versions before proceeding.
+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.
 
 ```bash
 uname -m
 dotnet --version
 docker --version
 ```
 
-Expected output: `Arm` (kernel strings may still show architecture-specific values). Ensure the .NET SDK version is 9.0.x.
+The output is similar to:
+
+```output
+aarch64
+9.0.x
+Docker version ...
+```
 
 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.
 
 ## PostgreSQL prerequisite for nopCommerce install
 
 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).
 
-Create PostgreSQL and enable `citext` before running the installer:
+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.
 
 ```bash
+export NOP_POSTGRES_PASSWORD='replace-with-a-strong-password'
+
 # Start PostgreSQL for local validation.
 docker run -d --name nop-postgres \
   -e POSTGRES_USER=nop \
-  -e POSTGRES_PASSWORD=<password> \
+  -e POSTGRES_PASSWORD="$NOP_POSTGRES_PASSWORD" \
   -e POSTGRES_DB=nopcommerce \
   -p 5432:5432 postgres:16
 
 # Enable the extension required by nopCommerce migrations.
 docker exec nop-postgres psql -U nop -d nopcommerce \
   -c "CREATE EXTENSION IF NOT EXISTS citext;"
 ```
+
+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.

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/3-checkout-build-baseline.md

@@ -12,7 +12,7 @@ Create a reproducible Arm baseline before optimization work. This page pins sour
 
 ## Clone and pin the source
 
-Pinning the exact tag and commit avoids silent drift in dependencies and behavior.
+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.
 
 ```bash
 git clone https://github.com/nopSolutions/nopCommerce.git
@@ -22,9 +22,15 @@ git checkout release-4.90.3
 git rev-parse --short=10 HEAD   # expect 9beda11c42
 ```
 
+If you open a new terminal later, return to the same repository root before running commands:
+
+```bash
+cd ~/nopCommerce  # replace with your clone path if different
+```
+
 ## Restore and build on Arm
 
-Run on the Arm VM to establish a native Arm baseline.
+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.
 
 ```bash
 # Restore dependencies first so build failures are easier to triage.
@@ -36,16 +42,28 @@ dotnet build src/Presentation/Nop.Web/Nop.Web.csproj -c Release --no-restore
 
 ## Start and install nopCommerce
 
-Start the app locally and complete installer setup with PostgreSQL.
+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.
 
 ```bash
 cd src/Presentation/Nop.Web
 dotnet run -c Release --no-build --urls http://0.0.0.0:5000
 ```
 
-Complete installation with PostgreSQL (`citext` enabled), then verify:
+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:
+
+- Server: `127.0.0.1`
+- Port: `5432`
+- Database: `nopcommerce`
+- User: `nop`
+- Password: the value of `NOP_POSTGRES_PASSWORD`
+
+Use sample data if you want a stable set of storefront pages for repeatable endpoint tests.
+
+Open a second terminal, return to the repository root, and verify that the app is installed and serving storefront traffic:
 
 ```bash
+cd ~/nopCommerce  # replace with your clone path if different
+
 # Root should return storefront content.
 curl -s -o /dev/null -w 'root=%{http_code}\n' http://127.0.0.1:5000/
 
@@ -57,21 +75,130 @@ Expected after successful install: `root=200`, `install=302`.
 
 ## Baseline methodology
 
-Do not benchmark `/install`. Baseline real storefront paths:
+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.
 
 - `/`
 - `/search/`
 - `/catalog/searchtermautocomplete`
 - `/product/search`
-- `/category/products/`
-- `/addproducttocart/catalog/...`
-- `/addproducttocart/details/...`
-- `/shoppingcart/productdetails_attributechange/...`
-- `/product/combinations`
-- `/cart/estimateshipping`
-- `/cart/selectshippingoption`
+- Product and category pages from your sample data
+- Cart or checkout endpoints from a recorded production-like workflow
+
+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.
+
+```python {file_name="test_nopcommerce_endpoints.py"}
+#!/usr/bin/env python3
+import argparse
+import concurrent.futures
+import json
+import statistics
+import time
+import urllib.error
+import urllib.request
+
+DEFAULT_ROUTES = [
+    "/",
+    "/search/",
+    "/product/search",
+    "/catalog/searchtermautocomplete?term=a",
+]
+
+
+def percentile(values, percent):
+    if not values:
+        return None
+    data = sorted(values)
+    index = round((percent / 100) * (len(data) - 1))
+    return data[index]
+
+
+def fetch(base_url, route, timeout):
+    url = base_url.rstrip("/") + route
+    start = time.perf_counter()
+    status = None
+    error = None
+
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as response:
+            response.read()
+            status = response.getcode()
+    except urllib.error.HTTPError as exc:
+        exc.read()
+        status = exc.code
+        error = f"HTTPError:{exc.code}"
+    except Exception as exc:
+        error = type(exc).__name__
+
+    elapsed_ms = (time.perf_counter() - start) * 1000
+    ok = status is not None and 200 <= status < 400
+    return {
+        "route": route,
+        "status": status,
+        "ok": ok,
+        "elapsed_ms": round(elapsed_ms, 2),
+        "error": error,
+    }
+
+
+def summarize(samples):
+    summary = {}
+    for route in sorted({sample["route"] for sample in samples}):
+        route_samples = [sample for sample in samples if sample["route"] == route]
+        successful = [sample["elapsed_ms"] for sample in route_samples if sample["ok"]]
+        status_counts = {}
+        for sample in route_samples:
+            key = str(sample["status"]) if sample["status"] is not None else "no-status"
+            status_counts[key] = status_counts.get(key, 0) + 1
+
+        summary[route] = {
+            "requests": len(route_samples),
+            "errors": sum(1 for sample in route_samples if not sample["ok"]),
+            "status_counts": status_counts,
+            "p50_ms": round(statistics.median(successful), 2) if successful else None,
+            "p95_ms": round(percentile(successful, 95), 2) if successful else None,
+            "max_ms": round(max(successful), 2) if successful else None,
+        }
+    return summary
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--base-url", required=True)
+    parser.add_argument("--concurrency", type=int, default=8)
+    parser.add_argument("--iterations", type=int, default=20)
+    parser.add_argument("--json-out", required=True)
+    parser.add_argument("--route", action="append", default=[])
+    parser.add_argument("--timeout", type=float, default=10)
+    args = parser.parse_args()
+
+    routes = args.route or DEFAULT_ROUTES
+    work = [route for route in routes for _ in range(args.iterations)]
+
+    with concurrent.futures.ThreadPoolExecutor(max_workers=args.concurrency) as pool:
+        samples = list(pool.map(lambda route: fetch(args.base_url, route, args.timeout), work))
+
+    result = {
+        "base_url": args.base_url,
+        "concurrency": args.concurrency,
+        "iterations_per_route": args.iterations,
+        "routes": routes,
+        "summary": summarize(samples),
+        "samples": samples,
+    }
+
+    with open(args.json_out, "w", encoding="utf-8") as output:
+        json.dump(result, output, indent=2)
+        output.write("\n")
+
+    print(json.dumps(result["summary"], indent=2))
+    raise SystemExit(1 if any(not sample["ok"] for sample in samples) else 0)
+
+
+if __name__ == "__main__":
+    main()
+```
 
-Use the endpoint tester:
+Run the endpoint tester from the repository root while the app is still running in the first terminal:
 
 ```bash
 # Use fixed concurrency and iterations for a repeatable starting point.
@@ -82,6 +209,8 @@ python3 test_nopcommerce_endpoints.py \
   --json-out arm_before.json
 ```
 
+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.
+
 ## Baseline quality rules
 
 Use these rules before you compare any optimization result:

content/learning-paths/servers-and-cloud-computing/dotnet-migration-nopcommerce/4-dependency-mapping-manifests.md

@@ -12,15 +12,15 @@ Run dependency discovery before migration changes so you understand direct refer
 
 ### 1. Map direct references
 
-Start with project-level references to see what your app explicitly depends on.
+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.
 
 ```bash
 rg -n "<PackageReference|<ProjectReference" src
 ```
 
 ### 2. List transitive dependencies
 
-Enumerate the full dependency graph; transitive packages often carry architecture-sensitive constraints.
+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.
 
 ```bash
 dotnet list src/Presentation/Nop.Web/Nop.Web.csproj package --include-transitive
@@ -30,25 +30,32 @@ dotnet list src/Presentation/Nop.Web/Nop.Web.csproj package --include-transitive
 
 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.
 
+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.
+
 ```bash
 dotnet tool install --global CycloneDX
-dotnet CycloneDX src/Presentation/Nop.Web/Nop.Web.csproj -o sbom/
+export PATH="$PATH:$HOME/.dotnet/tools"
+dotnet-CycloneDX src/Presentation/Nop.Web/Nop.Web.csproj -o sbom/ -rs -F Json
 ```
 
-If tool installation is blocked, treat `dotnet list --include-transitive` plus `*.deps.json` evidence as a temporary fallback, not the final state.
+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.
 
 ### 4. Inspect package internals for native payloads
 
-Inspect package contents directly to find architecture-specific native binaries.
+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.
 
 ```bash
+PACKAGE_ID="replace-with-package-id"
+PACKAGE_VERSION="replace-with-version"
+NUPKG="$HOME/.nuget/packages/$PACKAGE_ID/$PACKAGE_VERSION/$PACKAGE_ID.$PACKAGE_VERSION.nupkg"
+
 mkdir -p /tmp/nupkg-audit
-cp ~/.nuget/packages/<package>/<version>/<package>.<version>.nupkg /tmp/nupkg-audit/
+cp "$NUPKG" /tmp/nupkg-audit/
 cd /tmp/nupkg-audit
-unzip -l <package>.<version>.nupkg | rg "runtimes/|native/"
+unzip -l "$(basename "$NUPKG")" | rg "runtimes/|native/"
 ```
 
-This is how you catch hidden architecture-specific binaries.
+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`.
 
 ## Dependency cascade rule