Azure Maps Search Dotnet

作者 microsoft354361d83247MIT收录于 2026年10月8日更新于 2026年10月8日

Azure Maps SDK for .NET. Location-based services including geocoding, routing, rendering, geolocation, and weather. Use for address search, directions, map tiles, IP geolocation, and weather data. Triggers: "Azure Maps", "MapsSearchClient", "MapsRoutingClient", "MapsRenderingClient", "geocoding .NET", "route directions", "map tiles", "geolocation".

精选仅含说明Software Development
AI 生成的概览

介绍如何使用 Azure Maps .NET SDK 进行地理编码、路线规划、地图瓦片、地理定位和天气查询。

功能
该技能说明 Azure Maps .NET SDK,涵盖 Search、Routing、Rendering、Geolocation、Weather 和 Resource Management 包的安装方式。它介绍订阅密钥、Microsoft Entra 令牌凭据和 SAS 令牌等身份验证方式,并列出各包的客户端层次结构。它提供地理编码、批量与反向地理编码、边界多边形、路线导航、路线矩阵、等时圈、地图瓦片、IP 地理定位和天气查询的 C# 代码示例,以及错误处理和最佳实践。
适用场景
适用于编写调用 Azure Maps 位置服务的 .NET 代码,例如地址搜索、路线导航、地图瓦片、IP 地理定位或天气数据。适合需要这些 API 的具体客户端、选项和结果类型示例的开发者。
运行要求
需要 .NET SDK 以及 Azure Maps NuGet 包(Azure.Maps.Search、Azure.Maps.Routing、Azure.Maps.Rendering、Azure.Maps.Geolocation、Azure.Maps.Weather、Azure.ResourceManager.Maps、Azure.Identity)。需要具有凭据的 Azure Maps 账户:订阅密钥、Microsoft Entra 身份或 SAS 令牌,并需要访问 Azure Maps 服务的网络连接。不包含脚本,仅为说明和代码示例。

Azure Maps (.NET)

Azure Maps SDK for .NET providing location-based services: geocoding, routing, rendering, geolocation, and weather.

Installation

bash
# Search (geocoding, reverse geocoding)dotnet add package Azure.Maps.Search --prerelease
# Routing (directions, route matrix)dotnet add package Azure.Maps.Routing --prerelease
# Rendering (map tiles, static images)dotnet add package Azure.Maps.Rendering --prerelease
# Geolocation (IP to location)dotnet add package Azure.Maps.Geolocation --prerelease
# Weatherdotnet add package Azure.Maps.Weather --prerelease
# Resource Management (account management, SAS tokens)dotnet add package Azure.ResourceManager.Maps --prerelease
# Required for authenticationdotnet add package Azure.Identity

Current Versions:

  • Azure.Maps.Search: v2.0.0-beta.5
  • Azure.Maps.Routing: v1.0.0-beta.4
  • Azure.Maps.Rendering: v2.0.0-beta.1
  • Azure.Maps.Geolocation: v1.0.0-beta.3
  • Azure.ResourceManager.Maps: v1.1.0-beta.2

Environment Variables

bash
AZURE_MAPS_SUBSCRIPTION_KEY=<your-subscription-key>  # Only required for AzureKeyCredential authAZURE_MAPS_CLIENT_ID=<your-client-id>  # Required: Azure Maps client IDAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Authentication

Subscription Key (Shared Key)

csharp
using Azure;using Azure.Maps.Search;
var subscriptionKey = Environment.GetEnvironmentVariable("AZURE_MAPS_SUBSCRIPTION_KEY");var credential = new AzureKeyCredential(subscriptionKey);
var client = new MapsSearchClient(credential);

Microsoft Entra Token Credential

csharp
using Azure.Identity;using Azure.Maps.Search;
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>var credential = new DefaultAzureCredential(    DefaultAzureCredential.DefaultEnvironmentVariableName);// Or use a specific credential directly in production:// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes// var credential = new ManagedIdentityCredential();var clientId = Environment.GetEnvironmentVariable("AZURE_MAPS_CLIENT_ID");
var client = new MapsSearchClient(credential, clientId);

Shared Access Signature (SAS)

csharp
using Azure;using Azure.Core;using Azure.Identity;using Azure.ResourceManager;using Azure.ResourceManager.Maps;using Azure.ResourceManager.Maps.Models;using Azure.Maps.Search;
// Authenticate with Azure Resource ManagerArmClient armClient = new ArmClient(new DefaultAzureCredential());
// Get Maps account resourceResourceIdentifier mapsAccountResourceId = MapsAccountResource.CreateResourceIdentifier(    subscriptionId, resourceGroupName, accountName);MapsAccountResource mapsAccount = armClient.GetMapsAccountResource(mapsAccountResourceId);
// Generate SAS tokenMapsAccountSasContent sasContent = new MapsAccountSasContent(    MapsSigningKey.PrimaryKey,     principalId,     maxRatePerSecond: 500,     start: DateTime.UtcNow.ToString("O"),     expiry: DateTime.UtcNow.AddDays(1).ToString("O"));
Response<MapsAccountSasToken> sas = mapsAccount.GetSas(sasContent);
// Create client with SAS tokenvar sasCredential = new AzureSasCredential(sas.Value.AccountSasToken);var client = new MapsSearchClient(sasCredential);

Client Hierarchy

Azure.Maps.Search└── MapsSearchClient    ├── GetGeocoding()                    → Geocode addresses    ├── GetGeocodingBatch()               → Batch geocoding    ├── GetReverseGeocoding()             → Coordinates to address    ├── GetReverseGeocodingBatch()        → Batch reverse geocoding    └── GetPolygon()                      → Get boundary polygons
Azure.Maps.Routing└── MapsRoutingClient    ├── GetDirections()                   → Route directions    ├── GetImmediateRouteMatrix()         → Route matrix (sync, ≤100)    ├── GetRouteMatrix()                  → Route matrix (async, ≤700)    └── GetRouteRange()                   → Isochrone/reachable range
Azure.Maps.Rendering└── MapsRenderingClient    ├── GetMapTile()                      → Map tiles    ├── GetMapStaticImage()               → Static map images    └── GetCopyrightCaption()             → Copyright info
Azure.Maps.Geolocation└── MapsGeolocationClient    └── GetCountryCode()                  → IP to country/region
Azure.Maps.Weather└── MapsWeatherClient    ├── GetCurrentWeatherConditions()     → Current weather    ├── GetDailyForecast()                → Daily forecast    ├── GetHourlyForecast()               → Hourly forecast    └── GetSevereWeatherAlerts()          → Weather alerts

Core Workflows

1. Geocoding (Address to Coordinates)

csharp
using Azure;using Azure.Maps.Search;
var credential = new AzureKeyCredential(subscriptionKey);var client = new MapsSearchClient(credential);
Response<GeocodingResponse> result = client.GetGeocoding("1 Microsoft Way, Redmond, WA 98052");
foreach (var feature in result.Value.Features){    Console.WriteLine($"Coordinates: {string.Join(",", feature.Geometry.Coordinates)}");    Console.WriteLine($"Address: {feature.Properties.Address.FormattedAddress}");    Console.WriteLine($"Confidence: {feature.Properties.Confidence}");}

2. Batch Geocoding

csharp
using Azure.Maps.Search.Models.Queries;
List<GeocodingQuery> queries = new List<GeocodingQuery>{    new GeocodingQuery() { Query = "400 Broad St, Seattle, WA" },    new GeocodingQuery() { Query = "1 Microsoft Way, Redmond, WA" },    new GeocodingQuery() { AddressLine = "Space Needle", Top = 1 },};
Response<GeocodingBatchResponse> results = client.GetGeocodingBatch(queries);
foreach (var batchItem in results.Value.BatchItems){    foreach (var feature in batchItem.Features)    {        Console.WriteLine($"Coordinates: {string.Join(",", feature.Geometry.Coordinates)}");    }}

3. Reverse Geocoding (Coordinates to Address)

csharp
using Azure.Core.GeoJson;
GeoPosition coordinates = new GeoPosition(-122.138685, 47.6305637);Response<GeocodingResponse> result = client.GetReverseGeocoding(coordinates);
foreach (var feature in result.Value.Features){    Console.WriteLine($"Address: {feature.Properties.Address.FormattedAddress}");    Console.WriteLine($"Locality: {feature.Properties.Address.Locality}");}

4. Get Boundary Polygon

csharp
using Azure.Maps.Search.Models;
GetPolygonOptions options = new GetPolygonOptions(){    Coordinates = new GeoPosition(-122.204141, 47.61256),    ResultType = BoundaryResultTypeEnum.Locality,    Resolution = ResolutionEnum.Small,};
Response<Boundary> result = client.GetPolygon(options);
Console.WriteLine($"Boundary copyright: {result.Value.Properties?.Copyright}");Console.WriteLine($"Polygon count: {result.Value.Geometry.Count}");

5. Route Directions

csharp
using Azure;using Azure.Core.GeoJson;using Azure.Maps.Routing;using Azure.Maps.Routing.Models;
var client = new MapsRoutingClient(new AzureKeyCredential(subscriptionKey));
List<GeoPosition> routePoints = new List<GeoPosition>(){    new GeoPosition(-122.34, 47.61),  // Seattle    new GeoPosition(-122.13, 47.64)   // Redmond};
RouteDirectionQuery query = new RouteDirectionQuery(routePoints);Response<RouteDirections> result = client.GetDirections(query);
foreach (var route in result.Value.Routes){    Console.WriteLine($"Distance: {route.Summary.LengthInMeters} meters");    Console.WriteLine($"Duration: {route.Summary.TravelTimeDuration}");        foreach (RouteLeg leg in route.Legs)    {        Console.WriteLine($"Leg points: {leg.Points.Count}");    }}

6. Route Directions with Options

csharp
RouteDirectionOptions options = new RouteDirectionOptions(){    RouteType = RouteType.Fastest,    UseTrafficData = true,    TravelMode = TravelMode.Bicycle,    Language = RoutingLanguage.EnglishUsa,    InstructionsType = RouteInstructionsType.Text,};
RouteDirectionQuery query = new RouteDirectionQuery(routePoints){    RouteDirectionOptions = options};
Response<RouteDirections> result = client.GetDirections(query);

7. Route Matrix

csharp
RouteMatrixQuery routeMatrixQuery = new RouteMatrixQuery{    Origins = new List<GeoPosition>()    {        new GeoPosition(-122.34, 47.61),        new GeoPosition(-122.13, 47.64)    },    Destinations = new List<GeoPosition>()     {         new GeoPosition(-122.20, 47.62),        new GeoPosition(-122.40, 47.65)    },};
// Synchronous (up to 100 route combinations)Response<RouteMatrixResult> result = client.GetImmediateRouteMatrix(routeMatrixQuery);
foreach (var cell in result.Value.Matrix.SelectMany(row => row)){    Console.WriteLine($"Distance: {cell.Response?.RouteSummary?.LengthInMeters}");    Console.WriteLine($"Duration: {cell.Response?.RouteSummary?.TravelTimeDuration}");}
// Asynchronous (up to 700 route combinations)RouteMatrixOptions routeMatrixOptions = new RouteMatrixOptions(routeMatrixQuery){    TravelTimeType = TravelTimeType.All,};GetRouteMatrixOperation asyncResult = client.GetRouteMatrix(WaitUntil.Completed, routeMatrixOptions);

8. Route Range (Isochrone)

csharp
RouteRangeOptions options = new RouteRangeOptions(-122.34, 47.61){    TimeBudget = new TimeSpan(0, 20, 0)  // 20 minutes};
Response<RouteRangeResult> result = client.GetRouteRange(options);
// result.Value.ReachableRange contains the polygonConsole.WriteLine($"Boundary points: {result.Value.ReachableRange.Boundary.Count}");

9. Get Map Tiles

csharp
using Azure;using Azure.Maps.Rendering;
var client = new MapsRenderingClient(new AzureKeyCredential(subscriptionKey));
int zoom = 10;int tileSize = 256;
// Convert coordinates to tile indexMapTileIndex tileIndex = MapsRenderingClient.PositionToTileXY(    new GeoPosition(13.3854, 52.517), zoom, tileSize);
// Fetch map tileGetMapTileOptions options = new GetMapTileOptions(    MapTileSetId.MicrosoftImagery,    new MapTileIndex(tileIndex.X, tileIndex.Y, zoom));
Response<Stream> mapTile = client.GetMapTile(options);
// Save to fileusing (FileStream fileStream = File.Create("./MapTile.png")){    mapTile.Value.CopyTo(fileStream);}

10. IP Geolocation

csharp
using System.Net;using Azure;using Azure.Maps.Geolocation;
var client = new MapsGeolocationClient(new AzureKeyCredential(subscriptionKey));
IPAddress ipAddress = IPAddress.Parse("2001:4898:80e8:b::189");Response<CountryRegionResult> result = client.GetCountryCode(ipAddress);
Console.WriteLine($"Country ISO Code: {result.Value.IsoCode}");

11. Current Weather

csharp
using Azure;using Azure.Core.GeoJson;using Azure.Maps.Weather;
var client = new MapsWeatherClient(new AzureKeyCredential(subscriptionKey));
var position = new GeoPosition(-122.13071, 47.64011);var options = new GetCurrentWeatherConditionsOptions(position);
Response<CurrentConditionsResult> result = client.GetCurrentWeatherConditions(options);
foreach (var condition in result.Value.Results){    Console.WriteLine($"Temperature: {condition.Temperature.Value} {condition.Temperature.Unit}");    Console.WriteLine($"Weather: {condition.Phrase}");    Console.WriteLine($"Humidity: {condition.RelativeHumidity}%");}

Key Types Reference

Search Package

TypePurpose
MapsSearchClientMain client for search operations
GeocodingResponseGeocoding result
GeocodingBatchResponseBatch geocoding result
GeocodingQueryQuery for batch geocoding
ReverseGeocodingQueryQuery for batch reverse geocoding
GetPolygonOptionsOptions for polygon retrieval
BoundaryBoundary polygon result
BoundaryResultTypeEnumBoundary type (Locality, AdminDistrict, etc.)
ResolutionEnumPolygon resolution (Small, Medium, Large)

Routing Package

TypePurpose
MapsRoutingClientMain client for routing operations
RouteDirectionQueryQuery for route directions
RouteDirectionOptionsRoute calculation options
RouteDirectionsRoute directions result
RouteLegSegment of a route
RouteMatrixQueryQuery for route matrix
RouteMatrixResultRoute matrix result
RouteRangeOptionsOptions for isochrone
RouteRangeResultIsochrone result
RouteTypeRoute type (Fastest, Shortest, Eco, Thrilling)
TravelModeTravel mode (Car, Truck, Bicycle, Pedestrian)

Rendering Package

TypePurpose
MapsRenderingClientMain client for rendering
GetMapTileOptionsMap tile options
MapTileIndexTile coordinates (X, Y, Zoom)
MapTileSetIdTile set identifier

Common Types

TypePurpose
GeoPositionGeographic position (longitude, latitude)
GeoBoundingBoxBounding box for geographic area

Best Practices

  1. Use Entra ID for production — Prefer over subscription keys
  2. Batch operations — Use batch geocoding for multiple addresses
  3. Cache results — Geocoding results don't change frequently
  4. Use appropriate tile sizes — 256 or 512 pixels based on display
  5. Handle rate limits — Implement exponential backoff
  6. Use async route matrix — For large matrix calculations (>100)
  7. Consider traffic data — Set UseTrafficData = true for accurate ETAs

Error Handling

csharp
try{    Response<GeocodingResponse> result = client.GetGeocoding(address);}catch (RequestFailedException ex){    Console.WriteLine($"Status: {ex.Status}");    Console.WriteLine($"Error: {ex.Message}");        switch (ex.Status)    {        case 400:            // Invalid request parameters            break;        case 401:            // Authentication failed            break;        case 429:            // Rate limited - implement backoff            break;    }}

Related SDKs

SDKPurposeInstall
Azure.Maps.SearchGeocoding, searchdotnet add package Azure.Maps.Search --prerelease
Azure.Maps.RoutingDirections, matrixdotnet add package Azure.Maps.Routing --prerelease
Azure.Maps.RenderingMap tiles, imagesdotnet add package Azure.Maps.Rendering --prerelease
Azure.Maps.GeolocationIP geolocationdotnet add package Azure.Maps.Geolocation --prerelease
Azure.Maps.WeatherWeather datadotnet add package Azure.Maps.Weather --prerelease
Azure.ResourceManager.MapsAccount managementdotnet add package Azure.ResourceManager.Maps --prerelease

Reference Links

来源与署名

来源:microsoft/skills位于.github/plugins/azure-sdk-dotnet/skills/azure-maps-search-dotnet提交354361d

许可证: MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架