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 thedymaptic.GeoBlazor.Core
ordymaptic.GeoBlazor.Pro
(pro is a paid version with more features) package via your IDE’s Nuget Package Manager or from the command line withdotnet add package dymaptic.GeoBlazor.Core
(ordotnet 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), orenvironment 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 thewwwroot
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, andindex.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, replaceassets/esri/themes/light/main.css
withassets/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 yourbuilder.Services
to inject logic components likeGeometryEngine
.// 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 yourProgram.cs
. (This is not relevant if you are using the olderBlazor 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 theprovider
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 beInteractiveServer
for Blazor Server,InteractiveWebAssembly
for Blazor WebAssembly, orInteractiveAuto
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 theWebMap
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 theWebMap
.
@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!