Getting Started

Below instructions are for creating a Blazor application from scratch and adding GeoBlazor version 4.x. Adding GeoBlazor to an existing application would be the same, beginning with step 2. For previous versions of GeoBlazor, visit our repository at [github.com/dymaptic.GeoBlazor] and use the branches/tag dropdown to find the tag that matches your version.

Alternatively, you can use the new GeoBlazor Templates to create a new Blazor application with GeoBlazor already installed.

Create a new Blazor Web App, Blazor Server, Blazor Wasm, or Blazor Hybrid (MAUI) project.
Add a PackageReference to the latest version of the dymaptic.GeoBlazor.Core or dymaptic.GeoBlazor.Pro (pro is a paid version with more features) 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.

Note: .NET 9 can cause very slow build times due to its new static asset compression. If you need faster builds, we recommend staying on .NET 8 for now, and using a global.json file to pin your SDK build version to .NET 8. See our open request for a fix here.

If you decide to stay with .NET 9, we suggest adding the following line to your csproj file to disable the new compression feature:
   <PropertyGroup>
       <CompressionEnabled Condition="$(Configuration) != 'RELEASE'">false</CompressionEnabled>
   </PropertyGroup>

Get an API Key from the ArcGIS Location Platform. Place this in your appsettings.json, secrets.json (user secrets), or environment variables.:
```
{
    "ArcGISApiKey": "YourArcGISApiKey"
}
```
Note: If you are using Blazor WASM, there are several issues with this approach. First, appsettings.json is not added by default to all templates. If you want to add it yourself, you need to add it inside the wwwroot folder. For Blazor Web Apps with WebAssembly, you must define the API key in _both_ projects. Be Aware that the API key will be exposed in the browser (just like it would with Javascript). Even when using Blazor Server, the API key may be present in HTTP requests visible to the user in the browsers dev tools, so you should probably take other steps like setting up referrer rules in ArcGIS.

You can also set up an OAuth2 workflow, which is more secure as it does not expose a static API key, but this is more complex. You can read about all the authentication options in Authentication.
Register at licensing.dymaptic.com for a free GeoBlazor Core Registration key, or to purchase a GeoBlazor Pro license key with additional features and support. Add the key to appsettings.json:

    {
        "ArcGISApiKey": "YourArcGISApiKey",
        "GeoBlazor": {
            // GeoBlazor Core
            "RegistrationKey": "YourGeoBlazorRegistrationKey"
            // GeoBlazor Pro
            "LicenseKey": "YourGeoBlazorProLicenseKey"
        }
    }

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:

 <!-- GeoBlazor Core -->
 <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" />
   
 <!-- GeoBlazor Pro -->
 <link href="_content/dymaptic.GeoBlazor.Core" />
 <link href="_content/dymaptic.GeoBlazor.Pro" />
 <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.

Starting in .NET 9, there is also a new static asset compression feature that uses an Assets dictionary. If you see this pattern, follow the same pattern for GeoBlazor links:

 <link href="@Assets["_content/dymaptic.GeoBlazor.Core"]"/>
 <link href="@Assets["_content/dymaptic.GeoBlazor.Pro"]" />
 <link href="@Assets["_content/dymaptic.GeoBlazor.Core/assets/esri/themes/light/main.css"]" rel="stylesheet" />
 <link href="@Assets["YourProject.styles.css"]" rel="stylesheet" />

In _Imports.razor (for both Server and Client projects, if applicable), add the following lines up front, or you can add as needed to resolve code that you consume.

 @using dymaptic.GeoBlazor.Core
 @using dymaptic.GeoBlazor.Core.Attributes
 @using dymaptic.GeoBlazor.Core.Components
 @using dymaptic.GeoBlazor.Core.Components.Geometries
 @using dymaptic.GeoBlazor.Core.Components.Layers
 @using dymaptic.GeoBlazor.Core.Components.Popups
 @using dymaptic.GeoBlazor.Core.Components.Renderers
 @using dymaptic.GeoBlazor.Core.Components.Symbols
 @using dymaptic.GeoBlazor.Core.Components.Views
 @using dymaptic.GeoBlazor.Core.Components.Widgets
 @using dymaptic.GeoBlazor.Core.Enums
 @using dymaptic.GeoBlazor.Core.Events
 @using dymaptic.GeoBlazor.Core.Exceptions
 @using dymaptic.GeoBlazor.Core.Extensions
 @using dymaptic.GeoBlazor.Core.Functions
 @using dymaptic.GeoBlazor.Core.Interfaces
 @using dymaptic.GeoBlazor.Core.Model
 @using dymaptic.GeoBlazor.Core.Options
 @using dymaptic.GeoBlazor.Core.Results
 // for GeoBlazor Pro:
 @using dymaptic.GeoBlazor.Pro
 @using dymaptic.GeoBlazor.Pro.Components
 @using dymaptic.GeoBlazor.Pro.Components.Geometries
 @using dymaptic.GeoBlazor.Pro.Components.Layers
 @using dymaptic.GeoBlazor.Pro.Components.Popups
 @using dymaptic.GeoBlazor.Pro.Components.Renderers
 @using dymaptic.GeoBlazor.Pro.Components.Widgets
 @using dymaptic.GeoBlazor.Pro.Enums
 @using dymaptic.GeoBlazor.Pro.Events
 @using dymaptic.GeoBlazor.Pro.Functions
 @using dymaptic.GeoBlazor.Pro.Interfaces
 @using dymaptic.GeoBlazor.Pro.Model
 @using dymaptic.GeoBlazor.Pro.Options
 @using dymaptic.GeoBlazor.Pro.Results

In Program.cs (for both Server and Client projects, if applicable), add the following line to your builder.Services to inject logic components like GeometryEngine.
```
// GeoBlazor Core
builder.Services.AddGeoBlazor(builder.Configuration);
// GeoBlazor Pro
builder.Services.AddGeoBlazorPro(builder.Configuration);
```

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).

// 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:

// 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);

If you are using Blazor Server or InteractiveServer mode in Blazor Web Apps, you should also add the following lines to Program.cs to support the .wsv file type.

var provider = new FileExtensionContentTypeProvider();
provider.Mappings[".wsv"] = "application/octet-stream";
app.UseStaticFiles(new StaticFileOptions
{
    ContentTypeProvider = provider
});

If you wish to exclude JavaScript .map files (useful for debugging, but are a large download for end users), update the provider code above to exclude .map files.

var provider = new FileExtensionContentTypeProvider();
provider.Mappings[".wsv"] = "application/octet-stream";
#if RELEASE
provider.Mappings.Remove(".map");
#endif
app.UseStaticFiles(new StaticFileOptions
{
    ContentTypeProvider = provider
});

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.
```
@page "/map"
@rendermode InteractiveServer

<MapView Longitude="-118.805" Latitude="34.027" Zoom="11" Style="height: 400px; width: 100%;"> 
</MapView>
```
Within the MapView, define a map using the WebMap component. To load a pre-generated map from ArcGIS Online or Portal, get the Map Id (PortalItem Id) of the map.

   @page "/map"
   @rendermode InteractiveServer

   <MapView Longitude="-118.805" Latitude="34.027" Zoom="11" Style="height: 400px; width: 100%;"> 
       <WebMap>
           <PortalItem PortalItemId="4a6cb60ebbe3483a805999d481c2daa5" />
       </WebMap>
   </MapView>

Add a Widget to the MapView, after the WebMap.

   @page "/map"
   @rendermode InteractiveServer

   <MapView Longitude="-118.805" Latitude="34.027" Zoom="11" Style="height: 400px; width: 100%;"> 
       <WebMap>
           <PortalItem PortalItemId="4a6cb60ebbe3483a805999d481c2daa5" />
       </WebMap>
       <ScaleBarWidget Position="OverlayPosition.BottomLeft" />
   </MapView>

Run your application and make sure you can see your map!