Azure.Maps.Rendering 1.0.0-beta.3

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
This is a prerelease version of Azure.Maps.Rendering.
dotnet add package Azure.Maps.Rendering --version 1.0.0-beta.3
NuGet\Install-Package Azure.Maps.Rendering -Version 1.0.0-beta.3
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.Maps.Rendering" Version="1.0.0-beta.3" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Maps.Rendering --version 1.0.0-beta.3
#r "nuget: Azure.Maps.Rendering, 1.0.0-beta.3"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.Maps.Rendering as a Cake Addin
#addin nuget:?package=Azure.Maps.Rendering&version=1.0.0-beta.3&prerelease

// Install Azure.Maps.Rendering as a Cake Tool
#tool nuget:?package=Azure.Maps.Rendering&version=1.0.0-beta.3&prerelease

Azure Maps Render client library for .NET

Azure Maps Render is a library that can fetch image tiles and copyright information.

Source code | API reference documentation | REST API reference documentation | Product documentation

Getting started

Install the package

Install the client library for .NET with NuGet:

dotnet add package Azure.Maps.Rendering --prerelease

Prerequisites

You must have an Azure subscription and Azure Maps account.

To create a new Azure Maps account, you can use the Azure Portal, Azure PowerShell, or the Azure CLI. Here's an example using the Azure CLI:

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Authenticate the client

There are 2 ways to authenticate the client: Shared key authentication and Azure AD.

Shared Key authentication
  • Go to Azure Maps account > Authentication tab
  • Copy Primary Key or Secondary Key under Shared Key authentication section
// Create a MapsRenderingClient that will authenticate through Subscription Key (Shared key)
AzureKeyCredential credential = new AzureKeyCredential("<My Subscription Key>");
MapsRenderingClient client = new MapsRenderingClient(credential);
Azure AD authentication

In order to interact with the Azure Maps service, you'll need to create an instance of the MapsRenderingClient class. The Azure Identity library makes it easy to add Azure Active Directory support for authenticating Azure SDK clients with their corresponding Azure services.

To use AAD authentication, the environment variables as described in the Azure Identity README and create a DefaultAzureCredential instance to use with the MapsRenderingClient.

We also need an Azure Maps Client ID which can be found on the Azure Maps page > Authentication tab > "Client ID" in Azure Active Directory Authentication section.

AzureMapsPortal

// Create a MapsRenderingClient that will authenticate through Active Directory
TokenCredential credential = new DefaultAzureCredential();
string clientId = "<Your Map ClientId>";
MapsRenderingClient client = new MapsRenderingClient(credential, clientId);
Shared Access Signature (SAS) Authentication

Shared access signature (SAS) tokens are authentication tokens created using the JSON Web token (JWT) format and are cryptographically signed to prove authentication for an application to the Azure Maps REST API.

Before integrating SAS token authentication, we need to install Azure.ResourceManager and Azure.ResourceManager.Maps (version 1.1.0-beta.2 or higher):

dotnet add package Azure.ResourceManager
dotnet add package Azure.ResourceManager.Maps --prerelease

In the code, we need to import the following lines for both Azure Maps SDK and ResourceManager:

using Azure.Maps.Rendering;
using Azure.Core;
using Azure.ResourceManager;
using Azure.ResourceManager.Maps;
using Azure.ResourceManager.Maps.Models;

And then we can get SAS token via List Sas API and assign it to MapsRenderingClient. In the follow code sample, we fetch a specific maps account resource, and create a SAS token for 1 day expiry time when the code is executed.

// Get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// Authenticate your client
ArmClient armClient = new ArmClient(cred);

string subscriptionId = "MyMapsSubscriptionId";
string resourceGroupName = "MyMapsResourceGroupName";
string accountName = "MyMapsAccountName";

// Get maps account resource
ResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, accountName);
MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);

// Assign SAS token information
// Every time you want to SAS token, update the principal ID, max rate, start and expiry time
string principalId = "MyManagedIdentityObjectId";
int maxRatePerSecond = 500;

// Set start and expiry time for the SAS token in round-trip date/time format
DateTime now = DateTime.Now;
string start = now.ToString("O");
string expiry = now.AddDays(1).ToString("O");

MapsAccountSasContent sasContent = new MapsAccountSasContent(MapsSigningKey.PrimaryKey, principalId, maxRatePerSecond, start, expiry);
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);

// Create a SearchClient that will authenticate via SAS token
AzureSasCredential sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);
MapsRenderingClient client = new MapsRenderingClient(sasCredential);

Key concepts

MapsRenderingClient is designed for:

  • Communicate with Azure Maps endpoint to get images and tiles
  • Communicate with Azure Maps endpoint to get copyrights for images and tiles

Learn more about examples in samples

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

You can familiarize yourself with different APIs using our samples. Rendering map tiles requires knowledge about zoom levels and tile grid system. Please refer to the documentation for more information.

Get Imagery Tiles

Here is a simple example of rendering imagery tiles:

int zoom = 10, tileSize = 256;

// Get tile X, Y index by coordinate, zoom and tile size information
MapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(new GeoPosition(13.3854, 52.517), zoom, tileSize);

// Fetch imagery map tiles
GetMapTileOptions GetMapTileOptions = new GetMapTileOptions(
    MapTileSetId.MicrosoftImagery,
    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom)
);
Response<Stream> mapTile = client.GetMapTile(GetMapTileOptions);

// Prepare a file stream to save the imagery
using (FileStream fileStream = File.Create(".\\BerlinImagery.png"))
{
    mapTile.Value.CopyTo(fileStream);
}

Troubleshooting

General

When you interact with the Azure Maps services, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.

For example, if you try to get an imagery tile with wrong tile index, an error is returned, indicating "Bad Request" (HTTP 400).

try
{
    var options = new GetMapTileOptions(
        MapTileSetId.MicrosoftBaseHybrid,
        new MapTileIndex(12, 12, 2)
    );

    Response<Stream> imageryTile = client.GetMapTile(options);
    using var imageryStream = new MemoryStream();
    imageryTile.Value.CopyTo(imageryStream);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

Next steps

Contributing

See the CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <cla.microsoft.com>.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Azure.Maps.Rendering:

Package Downloads
AzureMapVisualizer

AzureLocationMapVisualizer is a .NET class library that enables developers to generate location-based images using Azure Maps. With this library, you can create beautiful and informative maps that are customized to fit your application's needs.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0-beta.3 69 5/10/2024
1.0.0-beta.2 22,462 7/13/2023
1.0.0-beta.1 10,886 10/13/2022