Getting Started

Links to Sections:

Creating a New Project

If you are starting a new project from scratch, we recommend using the GeoBlazor Templates to create a new Blazor application with GeoBlazor already installed. This will save you time and ensure that your project is set up correctly with all the necessary dependencies and configurations.

GeoBlazor Registration

  1. Visit licensing.dymaptic.com. Click on the Sign Up button. Register

  2. Fill out the registration form and click Register. You will receive an email with a confirmation link. Click the link in the email to confirm your registration. Sign Up

  3. Return to licensing.dymaptic.com and log in with your new account. Login

  4. Click on the Get Licenses button. Get Licenses

  5. Click on the Get a Free Key button to get a free GeoBlazor Core Registration key, or click on the Get GeoBlazor Pro button to purchase a GeoBlazor Pro license key with additional features and support. License Options

  6. Click on the Generate New API Key button to generate a new license key. Generate Key

  7. Give your key a name, and select GeoBlazor Core (the free version) or GeoBlazor Pro in the Software dropdown. Click Submit. Generate Key

  8. You should see your new key shown on the page. Click the Copy Key button to copy the key to your clipboard. Copy Key

  9. This key must be stored where your application can access it as part of the .NET IConfiguration environment variables. You can add the key to the appsettings.json file, the user secret secrets.json file, or an environment-specific file like appsettings.Development.json or appsettings.Production.json. Learn more about configuration files in .NET

    Note: Older versions of the documentation referenced "RegistrationKey" instead of "LicenseKey" for GeoBlazor Core. We have made the two terms interchangeable, so you can use either in your configuration files.

    {
    "GeoBlazor" : {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

    {
    "GeoBlazor" : {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

  10. If your application is running in InteractiveServer mode, then the configuration file needs to be available to the server application. If it is running in InteractiveWebAssembly, it needs to be available to the client application. If you are using InteractiveAuto or a combination of render modes on different pages, or you're just not sure, then you should add configuration settings to both the server and client applications. Be aware that WebAssembly projects do not support user secrets, and do not by default see appsettings files in the root folder, so you need to place the files inside the wwwroot folder for them to be accessible by the client application. If you need to use an appsettings file, but don't want to commit your API keys to the repository, you can add the file to the .gitignore, delete it, make a commit, then re-add it. Git will ignore the file after that. A typical Blazor Web App project structure would look like this:

    MyBlazorApp/
├── MyBlazorApp/
│   ├── appsettings.json
│   ├── appsettings.Development.json // use for local server development, or use secrets.json
│   └── appsettings.Production.json // not really necessary, most production server env have their own configuration settings
├── MyBlazorApp.Client/
│   ├── wwwroot/
│   │   ├── appsettings.json
│   │   ├── appsettings.Development.json // use for local wasm development
│   │   ├── appsettings.Production.json // use for production wasm, you do have to deploy keys to production for WebAssembly

    MyBlazorApp/
├── MyBlazorApp/
│   ├── appsettings.json
│   ├── appsettings.Development.json // use for local server development, or use secrets.json
│   └── appsettings.Production.json // not really necessary, most production server env have their own configuration settings
├── MyBlazorApp.Client/
│   ├── wwwroot/
│   │   ├── appsettings.json
│   │   ├── appsettings.Development.json // use for local wasm development
│   │   ├── appsettings.Production.json // use for production wasm, you do have to deploy keys to production for WebAssembly

ArcGIS Authentication

  1. Visit location.arcgis.com. Click Sign up for free to create an account. For existing ArcGIS Online or ArcGIS Enterprise users, see the instructions here. Create An Account
  2. Once registered, choose Sign In. Sign In
  3. This is the Location Platform Dashboard, where you can manage your API keys, applications, and billing. Click on Create developer credentials on the right side to get started. Developer Dashboard
  4. You can create an API Key or an OAuth Application. For the simplest approach, choose API key credentials. Directions for OAuth 2.0 credentials are here. Create an API Key
  5. Set an expiration date for your API key, up to one year in the future. Add referrers if you want to ensure that your key can only be used from your website or application. Click Next when done. Create API Key
  6. Choose which ArcGIS services you want to enable for your API key. You should at minimum enable the Basemaps services. Click Next when done. API Key Services
  7. If you ever create private feature services or other data, you can grant access to those services with your API key here. Select items or choose Skip. API Key Data Access
  8. Give your API key a name, select a folder, category, and tags, and write a summary if you choose. Then click Next. API Key Summary
  9. Review your API key details and click Next. API Key Review
  10. Be prepared to copy your API key and store it somewhere secure, as you will not be able to see it again. When ready, click Next. API Key Created
  11. That's it! You now have an API key that you can use in your GeoBlazor application. You can also create additional API keys or OAuth applications from the dashboard as needed. API Key Created
  12. In your GeoBlazor application, find the JSON file where you stored your GeoBlazor license key, and add a line for the ArcGIS API key.
{
    "ArcGISApiKey": "your-ArcGIS-api-key",
    "GeoBlazor": {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

{
    "ArcGISApiKey": "your-ArcGIS-api-key",
    "GeoBlazor": {
        "LicenseKey": "your-GeoBlazor-license-key"
    }
}

If you used the GeoBlazor Templates, you should be ready to run your application at this point! If you are adding GeoBlazor to an existing Blazor application, continue with the steps below to set up your project.

Project Setup

  1. Add a PackageReference to the latest version of the dymaptic.GeoBlazor.Core or dymaptic.GeoBlazor.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. You don't need to add it to every project, as long as each project has a dependency on the one with the GeoBlazor reference.

    Optional: If you need to use bundled assets instead of CDN resources (for offline environments or security requirements), see Asset Files.

  2. CSS Stylesheets: GeoBlazor automatically injects its required CSS stylesheets via Blazor's <HeadContent> component when a MapView or SceneView renders. For this to work, your application must include a <HeadOutlet /> component in its <head> element. This is included by default in all modern Blazor project templates.

    Blazor Web Apps — Verify that <HeadOutlet /> is present in your App.razor:

    <head>
    <!-- ... other head content ... -->
    <HeadOutlet />
</head>

    <head>
    <!-- ... other head content ... -->
    <HeadOutlet />
</head>

    Standalone Blazor WebAssembly — Verify that the HeadOutlet component is registered in Program.cs:

    builder.RootComponents.Add<HeadOutlet>("head::after");

    builder.RootComponents.Add<HeadOutlet>("head::after");

    Blazor Hybrid (MAUI) — <HeadContent> is not supported in hybrid apps. You must manually add the links to your wwwroot/index.html:

    <link href="_content/dymaptic.GeoBlazor.Core"/>
<!-- Add the next line only for GeoBlazor Pro: -->
<link href="_content/dymaptic.GeoBlazor.Pro"/>

    <link href="_content/dymaptic.GeoBlazor.Core"/>
<!-- Add the next line only for GeoBlazor Pro: -->
<link href="_content/dymaptic.GeoBlazor.Pro"/>

  3. Namespace Imports: GeoBlazor automatically provides global using directives for all of its namespaces via the NuGet package. You do not need to add @using statements to _Imports.razor — all GeoBlazor components, enums, events, and types are available in your Razor files and C# code immediately after adding the package reference.

    To disable the implicit usings (e.g., if they conflict with your own types), add the following to your .csproj:

    <PropertyGroup>
  <GeoBlazorImplicitUsings>false</GeoBlazorImplicitUsings>
</PropertyGroup>

    <PropertyGroup>
  <GeoBlazorImplicitUsings>false</GeoBlazorImplicitUsings>
</PropertyGroup>

    To remove a specific namespace while keeping the rest:

    <ItemGroup>
  <Using Remove="dymaptic.GeoBlazor.Core.Functions" />
</ItemGroup>

    <ItemGroup>
  <Using Remove="dymaptic.GeoBlazor.Core.Functions" />
</ItemGroup>

  4. 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 Core
builder.Services.AddGeoBlazor(builder.Configuration);
// GeoBlazor Pro
builder.Services.AddGeoBlazorPro(builder.Configuration);

  5. 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 or .NET MAUI projects).

    // Server
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

// or WebAssembly
builder.Services.AddRazorComponents
    .AddInteractiveWebAssemblyComponents();

// or both
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents();

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

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

  6. If you are using Blazor Server or InteractiveServer mode in Blazor Web Apps with the .NET 8 UseStaticFiles middleware, you should also add the following lines to Program.cs to support the .wsv file type. This does not appear to be necessary with the .NET 9 MapStaticAssets middleware.

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

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

    If you wish to exclude JavaScript .map files from UseStaticFiles (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
   });

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

  7. Create a Razor Component page with a map. 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>

    @page "/map"
@rendermode InteractiveServer

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

  8. 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. Note that previous versions of GeoBlazor used the property Id, but this has been changed to PortalItemId in GeoBlazor 4 to avoid naming collisions.

    @page "/map"
@rendermode InteractiveServer

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

    @page "/map"
@rendermode InteractiveServer

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

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

    @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>

  10. Run your application and make sure you can see your map! If you have any trouble, join our Discord community for help. Web Map Sample