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 從公開儲存庫中收錄這些內容。

檢舉或申請下架