Repository: dymaptic/GeoBlazor
Pull request #407: Update readme
Author: login: codergrl
Created: 2025-05-19T19:08:01Z | Merged: 2025-05-23T19:05:49Z

Updating the readme for the develop branch to let users know this applies to version 4. Also update code example to include Interactive rendering info


Diff:
diff --git a/Directory.Build.props b/Directory.Build.props
index 2698a17b0..110bae15f 100644
--- a/Directory.Build.props
+++ b/Directory.Build.props
@@ -2,6 +2,6 @@
   <PropertyGroup>
     <Nullable>enable</Nullable>
     <ImplicitUsings>enable</ImplicitUsings>
-    <CoreVersion>4.0.0.0-beta-10</CoreVersion>
+    <CoreVersion>4.0.0.0-beta-9.3</CoreVersion>
   </PropertyGroup>
 </Project>
\ No newline at end of file
diff --git a/ReadMe.md b/ReadMe.md
index f2c20ff08..fb993bc2d 100644
--- a/ReadMe.md
+++ b/ReadMe.md
@@ -1,20 +1,5 @@
-﻿<style>
-   #geoblazor-logo { 
-      background-color: #5D2E8E; 
-      padding: 1rem; 
-      border-radius: 1rem; 
-   }
-
-   #pro-link {
-      background-color: #d6d6d6;
-      padding: 1rem;
-      border-radius: 1rem;
-      width: 300px;
-   }
-</style>
-
-<p style="text-align: center;">
-  <img id="geoblazor-logo" src="./src/dymaptic.GeoBlazor.Core/gb_white_text_300px.png" alt="GeoBlazor" width="300">
+﻿<p style="text-align: center;">
+  <img id="geoblazor-logo" src="./src/dymaptic.GeoBlazor.Core/gb_white_text_300px.png" alt="GeoBlazor" width="300" style="background-color: #5D2E8E; padding: 1rem; border-radius: 1rem;" />
 </p>
 
 <p style="text-align: center;">
@@ -26,7 +11,7 @@ GeoBlazor brings the power of the ArcGIS Maps SDK for JavaScript into your Blazo
 <p style="text-align: center;">
    <em>
       <a href="https://www.nuget.org/packages/dymaptic.GeoBlazor.Pro">
-         <img id="pro-link" alt="GeoBlazor Pro" src="./src/dymaptic.GeoBlazor.Core/Go-GeoBlazor-Pro.png" />
+         <img id="pro-link" alt="GeoBlazor Pro" src="./src/dymaptic.GeoBlazor.Core/Go-GeoBlazor-Pro.png" style="background-color: #d6d6d6; padding: 1rem; border-radius: 1rem; width: 300px;" />
       </a>
    </em>
 </p>
@@ -47,6 +32,11 @@ GeoBlazor brings the power of the ArcGIS Maps SDK for JavaScript into your Blazo
 
 [![Discord](https://img.shields.io/discord/1027907220949717033?color=%235865F2&label=chat&logo=discord&logoColor=white)](https://discord.gg/hcmbPzn4VW)
 
+## ‼️Important Version Information
+Below are the steps to get started with GeoBlazor version 4.x. To view the documentation for previous versions, 
+use the branches/tags dropdown in the top left corner of the GitHub page to select the version you want to view.
+The release versions each have a corresponding tag.
+
 ## ✨ Key Features
 
 - **Pure C# Development**: Access the complete ArcGIS Maps SDK without writing a single line of JavaScript
@@ -62,7 +52,6 @@ GeoBlazor brings the power of the ArcGIS Maps SDK for JavaScript into your Blazo
 - [Documentation](https://docs.geoblazor.com)
 - [GitHub Repository](https://github.com/dymaptic/GeoBlazor)
 - [Join our Discord Server](https://discord.gg/hcmbPzn4VW)
-- [Repository Contributions](docs/DeveloperGuide)
 
 <p align="center">
   <img src="https://docs.geoblazor.com/assets/images/webmap.png" alt="GeoBlazor Map Example" width="800">
@@ -94,13 +83,12 @@ Or for the Pro version with additional features:
 
 (from https://docs.geoblazor.com/pages/gettingStarted.html)
 
-1. Create a new Blazor Web App (.NET 8), Blazor Server, Blazor Wasm, or Blazor Hybrid (MAUI) project.
+1. Create a new Blazor Web App, Blazor Server, Blazor Wasm, or Blazor Hybrid (MAUI) project.
 
-2. Add a `PackageReference` to the latest version of the `dymaptic.GeoBlazor.Core` package via your IDE's Nuget Package
-   Manager or `dotnet add package dymaptic.GeoBlazor.Core`.
+2. Add a `PackageReference` to the latest version of the `dymaptic.GeoBlazor.Core` or `dymaptic.GeoBlazor.Pro` ([pro is a paid version with more features](pro)) package via your IDE's Nuget Package Manager or from the command line with `dotnet add package dymaptic.GeoBlazor.Core` (or `dotnet add package dymaptic.GeoBlazor.Pro`). For Blazor Web Apps supporting WebAssembly, add this reference to the `.Client` WebAssembly project, or a Razor Class Library where you intend to write your mapping Razor components.
 
-3. Get an API Key from the [ArcGIS Portal](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/). For Blazor Server, place it in your
-   appsettings.json:
+3. Get an API Key from the [ArcGIS Location Platform](https://location.arcgis.com/). Place this in your
+   `appsettings.json`, `secrets.json` (user secrets), or `environment variables`.:
 
    ```json
    {
@@ -111,24 +99,27 @@ Or for the Pro version with additional features:
 4. Register at [licensing.dymaptic.com](https://licensing.dymaptic.com) for a free GeoBlazor Core Registration key.
    Add the key to `appsettings.json`:
 
-```json
-    {
-        "ArcGISApiKey": "YourArcGISApiKey",
-        "GeoBlazor": {
-            "RegistrationKey": "YourGeoBlazorRegistrationKey"
-        }
-    }
-```
+   ```json
+       {
+           "ArcGISApiKey": "YourArcGISApiKey",
+           "GeoBlazor": {
+               "RegistrationKey": "YourGeoBlazorRegistrationKey"
+           }
+       }
+   ```
+
+5. In the root file that defines your html (`App.razor` for Blazor Web Apps, `_Layout.cshtml` for older Blazor Server apps, and `index.html` only for standalone Blazor WebAssembly apps), add the following to the `<head>` section:
 
-5. In the root file that defines your html (`_Layout.cshtml`, `index.html`, or `App.razor`), add the following to the `<head>` section:
+   ```html
+   <link href="_content/dymaptic.GeoBlazor.Core"/>
+   <link href="_content/dymaptic.GeoBlazor.Core/assets/esri/themes/light/main.css" rel="stylesheet" />
+   <link href="YourProject.styles.css" rel="stylesheet" />
+   ```
+   The `YourProject.styles.css` is the default stylesheet for your project, this line should already be present in your template, but is important for GeoBlazor to function correctly.
+   For dark mode, replace `assets/esri/themes/light/main.css` with `assets/esri/themes/dark/main.css`.
 
-    ```html
-    <link href="_content/dymaptic.GeoBlazor.Core"/>
-    <link href="_content/dymaptic.GeoBlazor.Core/assets/esri/themes/light/main.css" rel="stylesheet" />
-    <link href="YourProject.styles.css" rel="stylesheet" />
-    ```
 
-6. In `_Imports.razor`, add the GeoBlazor namespaces:
+6. In `_Imports.razor` (for both Server and Client projects, if applicable), add the GeoBlazor namespaces:
 
    ```csharp
    @using dymaptic.GeoBlazor.Core
@@ -152,26 +143,65 @@ Or for the Pro version with additional features:
    @using dymaptic.GeoBlazor.Core.Results
    ```
 
-7. In `Program.cs`, register the GeoBlazor services:
+7. In `Program.cs` (for both Server and Client projects, if applicable), register the GeoBlazor services:
 
    ```csharp
    builder.Services.AddGeoBlazor(builder.Configuration);
    ```
+8. GeoBlazor requires Interactive Server or WebAssembly rendering enabled when using the modern `Blazor Web App` templates. Verify that the following lines are present in your `Program.cs`.
+   (This is not relevant if you are using the older `Blazor Server` template, and does not apply to WebAssembly projects).
 
-8. Create a Razor Component page with a map:
+   ```csharp
+   // Server
+   builder.Services.AddRazorComponents()
+       .AddInteractiveServerComponents();
+
+   // or WebAssembly
+   builder.Services.AddRazorComponents
+       .AddInteractiveWebAssemblyComponents();
+   
+   // or both
+   builder.Services.AddRazorComponents()
+       .AddInteractiveServerComponents()
+       .AddInteractiveWebAssemblyComponents();
+   ```
+   
+   and in the lower portion of the file:
 
+   ```csharp
+   // Server
+   app.MapRazorComponents<App>()
+       .AddInteractiveServerRenderMode();
+
+   // or WebAssembly
+   app.MapRazorComponents<App>()
+       .AddInteractiveWebAssemblyRenderMode()
+       .AddAdditionalAssemblies(typeof(Counter).Assembly);
+   
+   // or both
+   app.MapRazorComponents<App>()
+       .AddInteractiveServerRenderMode()
+       .AddInteractiveWebAssemblyRenderMode()
+       .AddAdditionalAssemblies(typeof(Counter).Assembly);
+   ```
+9. Create a Razor Component page with a map. Again for Blazor Web Apps, be sure that the `@rendermode` is defined at the 
+   page or app level (line 2 of the example below). This should be `InteractiveServer` for Blazor Server, 
+   `InteractiveWebAssembly` for Blazor WebAssembly, or `InteractiveAuto` for the automatic switching between modes. 
+   [Learn more about Blazor render modes](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes).
+   
    ```html
-   @page "/"
+   @page "/map"
+   @rendermode InteractiveServer
 
    <MapView Longitude="-118.805" Latitude="34.027" Zoom="11" Style="height: 400px; width: 100%;"> 
        <WebMap>
-           <PortalItem Id="4a6cb60ebbe3483a805999d481c2daa5" />
+           <PortalItem PortalItemId="4a6cb60ebbe3483a805999d481c2daa5" />
        </WebMap>
        <ScaleBarWidget Position="OverlayPosition.BottomLeft" />
    </MapView>
    ```
 
-8. Run your application and see your map!
+10. Run your application and see your map!
 
 For complete documentation, please visit [https://docs.geoblazor.com](https://docs.geoblazor.com)
 
diff --git a/src/dymaptic.GeoBlazor.Core/ReadMe.md b/src/dymaptic.GeoBlazor.Core/ReadMe.md
index 621d55a4c..9e7aa80dc 100644
--- a/src/dymaptic.GeoBlazor.Core/ReadMe.md
+++ b/src/dymaptic.GeoBlazor.Core/ReadMe.md
@@ -68,13 +68,12 @@ Or for the Pro version with additional features:
 
 (from https://docs.geoblazor.com/pages/gettingStarted.html)
 
-1. Create a new Blazor Web App (.NET 8), Blazor Server, Blazor Wasm, or Blazor Hybrid (MAUI) project.
+1. Create a new Blazor Web App, Blazor Server, Blazor Wasm, or Blazor Hybrid (MAUI) project.
 
-2. Add a `PackageReference` to the latest version of the `dymaptic.GeoBlazor.Core` package via your IDE's Nuget Package
-   Manager or `dotnet add package dymaptic.GeoBlazor.Core`.
+2. Add a `PackageReference` to the latest version of the `dymaptic.GeoBlazor.Core` or `dymaptic.GeoBlazor.Pro` ([pro is a paid version with more features](pro)) package via your IDE's Nuget Package Manager or from the command line with `dotnet add package dymaptic.GeoBlazor.Core` (or `dotnet add package dymaptic.GeoBlazor.Pro`). For Blazor Web Apps supporting WebAssembly, add this reference to the `.Client` WebAssembly project, or a Razor Class Library where you intend to write your mapping Razor components.
 
-3. Get an API Key from the [ArcGIS Portal](https://developers.arcgis.com/documentation/security-and-authentication/api-key-authentication/). For Blazor Server, place it in your
-   appsettings.json:
+3. Get an API Key from the [ArcGIS Location Platform](https://location.arcgis.com/). Place this in your
+   `appsettings.json`, `secrets.json` (user secrets), or `environment variables`.:
 
    ```json
    {
@@ -94,15 +93,18 @@ Or for the Pro version with additional features:
     }
 ```
 
-5. In the root file that defines your html (`_Layout.cshtml`, `index.html`, or `App.razor`), add the following to the `<head>` section:
+5. In the root file that defines your html (`App.razor` for Blazor Web Apps, `_Layout.cshtml` for older Blazor Server apps, and `index.html` only for standalone Blazor WebAssembly apps), add the following to the `<head>` section:
 
-    ```html
-    <link href="_content/dymaptic.GeoBlazor.Core"/>
-    <link href="_content/dymaptic.GeoBlazor.Core/assets/esri/themes/light/main.css" rel="stylesheet" />
-    <link href="YourProject.styles.css" rel="stylesheet" />
-    ```
+   ```html
+   <link href="_content/dymaptic.GeoBlazor.Core"/>
+   <link href="_content/dymaptic.GeoBlazor.Core/assets/esri/themes/light/main.css" rel="stylesheet" />
+   <link href="YourProject.styles.css" rel="stylesheet" />
+   ```
+   The `YourProject.styles.css` is the default stylesheet for your project, this line should already be present in your template, but is important for GeoBlazor to function correctly.
+   For dark mode, replace `assets/esri/themes/light/main.css` with `assets/esri/themes/dark/main.css`.
 
-6. In `_Imports.razor`, add the GeoBlazor namespaces:
+
+6. In `_Imports.razor` (for both Server and Client projects, if applicable), add the GeoBlazor namespaces:
 
    ```csharp
    @using dymaptic.GeoBlazor.Core
@@ -126,26 +128,65 @@ Or for the Pro version with additional features:
    @using dymaptic.GeoBlazor.Core.Results
    ```
 
-7. In `Program.cs`, register the GeoBlazor services:
+7. In `Program.cs` (for both Server and Client projects, if applicable), register the GeoBlazor services:
 
    ```csharp
    builder.Services.AddGeoBlazor(builder.Configuration);
    ```
+8. GeoBlazor requires Interactive Server or WebAssembly rendering enabled when using the modern `Blazor Web App` templates. Verify that the following lines are present in your `Program.cs`.
+   (This is not relevant if you are using the older `Blazor Server` template, and does not apply to WebAssembly projects).
 
-8. Create a Razor Component page with a map:
+   ```csharp
+   // Server
+   builder.Services.AddRazorComponents()
+       .AddInteractiveServerComponents();
+
+   // or WebAssembly
+   builder.Services.AddRazorComponents
+       .AddInteractiveWebAssemblyComponents();
+   
+   // or both
+   builder.Services.AddRazorComponents()
+       .AddInteractiveServerComponents()
+       .AddInteractiveWebAssemblyComponents();
+   ```
+   
+   and in the lower portion of the file:
 
+   ```csharp
+   // Server
+   app.MapRazorComponents<App>()
+       .AddInteractiveServerRenderMode();
+
+   // or WebAssembly
+   app.MapRazorComponents<App>()
+       .AddInteractiveWebAssemblyRenderMode()
+       .AddAdditionalAssemblies(typeof(Counter).Assembly);
+   
+   // or both
+   app.MapRazorComponents<App>()
+       .AddInteractiveServerRenderMode()
+       .AddInteractiveWebAssemblyRenderMode()
+       .AddAdditionalAssemblies(typeof(Counter).Assembly);
+   ```
+9. Create a Razor Component page with a map. Again for Blazor Web Apps, be sure that the `@rendermode` is defined at the 
+   page or app level (line 2 of the example below). This should be `InteractiveServer` for Blazor Server, 
+   `InteractiveWebAssembly` for Blazor WebAssembly, or `InteractiveAuto` for the automatic switching between modes. 
+   [Learn more about Blazor render modes](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes).
+   
    ```html
-   @page "/"
+   @page "/map"
+   @rendermode InteractiveServer
 
    <MapView Longitude="-118.805" Latitude="34.027" Zoom="11" Style="height: 400px; width: 100%;"> 
        <WebMap>
-           <PortalItem Id="4a6cb60ebbe3483a805999d481c2daa5" />
+           <PortalItem PortalItemId="4a6cb60ebbe3483a805999d481c2daa5" />
        </WebMap>
        <ScaleBarWidget Position="OverlayPosition.BottomLeft" />
    </MapView>
    ```
 
-8. Run your application and see your map!
+10. Run your application and see your map!
 
 For complete documentation, please visit [https://docs.geoblazor.com](https://docs.geoblazor.com)
 


Reviews:
user: login: TimPurdum
body: Looks good, you can add those suggestions or re-assign back to me. The other copies of the getting started information are in the Pro repository, I can make sure those get updated.
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-05-19T20:10:00Z

Review comments:
diff_hunk: @@ -47,6 +47,9 @@ GeoBlazor brings the power of the ArcGIS Maps SDK for JavaScript into your Blazo
 
 [![Discord](https://img.shields.io/discord/1027907220949717033?color=%235865F2&label=chat&logo=discord&logoColor=white)](https://discord.gg/hcmbPzn4VW)
 
+## ‼️Important Version Information
+The below documentation is for GeoBlazor version 4.x. To view the documentation for previous versions, switch to the main branch, or go to the [Documentation](https://docs.geoblazor.com) page.
+
path: ReadMe.md
user: login: TimPurdum
body: This will be out of date as soon as we release v4, because we will merge into main. I suggest we point them to https://www.nuget.org/packages/dymaptic.GeoBlazor.Core/3.2.1#readme-body-tab, which will remain permanently locked to v3.
created_at: 2025-05-19T20:02:21Z
author_association: COLLABORATOR
diff_hunk: @@ -157,11 +160,18 @@ Or for the Pro version with additional features:
    ```csharp
    builder.Services.AddGeoBlazor(builder.Configuration);
    ```
+8. GeoBlazor requires Interactive server-side rendering enabled. Verify that the following lines are present in your `Program.cs`:
+
+   ```csharp
+      .AddInteractiveServerComponents(); // this should be in the Services section
 
+      .AddInteractiveServerRenderMode(); // this should be in the app section
+   ```
path: ReadMe.md
user: login: TimPurdum
body: I realize they are stacked that way in the template, but I find it more confusing to see alone like this, so might be better to show the full compiled line. We also need to show them the option of adding the WebAssembly interactive modes, which work as well.

```chsharp
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// or

builder.Services.AddRazorComponents
    .AddInteractiveWebAssemblyComponents();

// or both

builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();
```

and

```
app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

// or

app.MapRazorComponents<App>()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(Counter).Assembly);

// or

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode()
    .AddInteractiveWebAssemblyRenderMode()
    .AddAdditionalAssemblies(typeof(Counter).Assembly);
```
created_at: 2025-05-19T20:06:56Z
author_association: COLLABORATOR
diff_hunk: @@ -157,11 +160,18 @@ Or for the Pro version with additional features:
    ```csharp
    builder.Services.AddGeoBlazor(builder.Configuration);
    ```
+8. GeoBlazor requires Interactive server-side rendering enabled. Verify that the following lines are present in your `Program.cs`:
+
+   ```csharp
+      .AddInteractiveServerComponents(); // this should be in the Services section
 
+      .AddInteractiveServerRenderMode(); // this should be in the app section
+   ```
 8. Create a Razor Component page with a map:
 
    ```html
    @page "/"
+   @rendermode InteractiveServer
path: ReadMe.md
user: login: TimPurdum
body: No great way to show an inline comment here, so might put the other options into the text above or below, like:

8. Create a Razor Component page with a map. Be sure to set an [Interactive Render Mode](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes) like Server, WebAssembly, or Auto:
created_at: 2025-05-19T20:09:10Z
author_association: COLLABORATOR

PR comments:
user: login: TimPurdum
created_at: 2025-05-21T03:35:58Z
body: @codergrl I went ahead and implemented my suggestions along with some other changes we have discussed. I also:

- updated the internal `ReadMe.md` that gets packaged for NuGet.org
- fixed the broken style at the top of the github readme
- updated the link to ArcGIS Locations Service
- figured out a better solution for the "old version docs" (the branch/tag dropdown in github).
author_association: COLLABORATOR
user: login: codergrl
created_at: 2025-05-23T16:04:32Z
body: This looks great, good to merge.
author_association: MEMBER