Learning ArcGIS Runtime SDK for .NET

Get ready to build awesome native apps! In this chapter, you will be introduced to ArcGIS Runtime in general. You will be presented with an overview of where it fits within the Esri platform, whom it is for, what problems it helps you solve, and how to get started; you will be presented with an overview of where it fits within Esri's platform, whom it is for, what problems it helps you solve, how to get started, not only with Runtime, but also the other tools you'll need to be successful at building native mapping apps.

What is ArcGIS Runtime? Well, to put it simply, it is a powerful mapping SDK for building native apps. However, it goes beyond just simple mapping because it is a core developer technology from Esri, the world's largest software company for Geographic Information Systems (GIS). Basically, you can easily make a map, add layers, and do analysis, such as buffer a point or line, visibility analysis, online and offline editing, and find the quickest route between two locations, which is really what separates Esri's technology from other mapping technologies. ArcGIS Runtime can be used to create the native mapping apps on iOS, OS X, Android, Linux, and Windows. It was developed in C++ and it has been designed to be as fast and efficient as possible on each OS it runs on. It's cross-platform, 64-bit, multithreaded, has a much simpler API than previous technologies from Esri, and it works with the local and cloud data sources. More importantly, for you, the developer is such that you don't have to make a language choice, and then go out and learn it before you can start developing. Esri has made this part easy for you as the developer so that you can use whatever language you're comfortable with and start developing immediately. However, if you're wondering whether you will make a sacrifice if you choose one OS over another, don't worry. The Application Programming Interface (API) is nearly identical across all supported operating systems. In short, you get the functionality you need no matter the language or platform you choose. What more could the developer ask for?

ArcGIS Runtime can be used in a variety of ways. These are the following three broad categories where ArcGIS Runtime can be used:

ArcGIS Runtime can be used for developing apps that you sell on Google Play, Apple App Store, or Windows Store. For example, it could provide the citizens of a city, town, or even nation with a phonebook that shows not only the map but also the directions from your current location to your favorite restaurant even if you don't have Internet access. See this screenshot:

ArcGIS Runtime can also be used to embed into another app. A perfect example of this is to embed it into a military vehicle real-time tracking system. This has been done with older technologies from Esri called ArcGIS Engine (Refer to A little history later in this chapter). See this screenshot:

Another use of ArcGIS Runtime could be a mobile solution for a business' enterprise effort to go mobile (enterprise mobility). For example, a utility may need to go out and perform damage assessment after a storm. As it's very possible that cell towers may be down, there is a real need to be able to find a location, add some data to the map (where the fallen debris is located) so that field crews can estimate how much work needs to be done.

What can ArcGIS Runtime do? Here's a quick summary:

Well, it can certainly make a map using both online and offline content. With these maps, you will be able to find things such as streets, points of interest, people, and equipment, using a variety of methods to find objects on the map either by just clicking on the map, entering coordinates, or an address. You'll be able to then route yourself to the desired location(s). However, it goes beyond simple queries that you'd find in any database system. With ArcGIS Runtime, you can also do spatial searches such as finding all of the manholes within 1 mile of this location using a simple one-mile circle (buffer). What if you're developing an app for a business' fleet of vehicles where the drivers not only want to visit multiple sites during the day, but also want to find other potential customers along the route so that they can maximize their time and minimize the fuel consumed? Well, that's just one of the many spatial analytical operations that can be built into the app. An even more critical app example is a soldier that needs to go into hostile territory where GPS is denied, but they need to make observations by adding enemy locations to a map while completely disconnected, and then find the quickest route back to base across rough terrain. Another military example is a battlefield commander who not only needs to have situation awareness by tracking friendly forces in real time while they're at the Forward Operating Base (FOB), but they also need to see it while they step outside or drive to another location.

For those who are more experienced Esri users, here's a more detailed summary of its features:

What are the language options? With ArcGIS Runtime, you can choose either .NET, Java SE, Android, Objective-C, C++ using Qt, or a combination of C++ and JavaScript by using Qt and QML. The beauty of this feature is that it's completely up to you and your team of developers. If you work alone, you probably already have a language in mind, and based on the title of this book, you're probably a .NET developer. If you're not a .NET developer, the good news is that the things you learn here will apply to the other flavors of ArcGIS Runtime. There will be some minor differences in how Runtime is implemented in your language of choice, however. With that said, which language choices do you have based on the OS? Refer to the following diagram. On the desktop, you can use Objective-C, .NET, C++ via Qt and QML, and Java SE. On mobile devices, you can use Objective-C, Java with the Android SDK, or .NET for Windows Phone. For embedded apps, you can use Java SE, C++ via Qt and QML, or .NET:

One of the awesome benefits of many of these languages is that you can build apps that are truly cross-platform. From the software development perspective, this means you can write your code once and run it on many platforms. For example, it's possible to use the .NET SDK to write an app that shares code and can be run on Windows, Windows Store, and Windows Phone. With the Qt version of ArcGIS Runtime, you can go even further and write your code so that it runs on nearly all platforms. That's amazing! But don't feel left out. Later this year, Esri will be releasing the Xamarin® version of ArcGIS Runtime, which will allow you to run your .NET apps on iOS and Android too. As a result, you get more bang for your buck.

Esri has a long history of providing powerful capabilities to its users for server, desktop, and mobile platforms. It really started back in the 1980s with ArcInfo and with a language called Arc Macro Language (AML). This language allowed users to create scripts that automated tasks and provided developers with the ability to create interfaces on both Windows and UNIX. Then, PCs became more powerful and Esri continued providing great developer opportunities with AML and new programs that ran on Windows called ArcView and MapObjects. Avenue was the first attempt of Esri at an object-oriented programming language. It was very popular because it provided its user base with their first exposure to this new paradigm of writing code. Of course, by the late 1990s, everything started to change with languages such as Visual Basic and Visual Basic for Applications (VBA). Not only that, languages such as Java became very popular, which led to .NET. As Esri saw these major developments, with more high-level languages that were easier for its user base, it became more and more obvious that developing a custom language for their user base no longer made sense. By the late 1990s, Esri started building ArcGIS, which was going to allow users to use their language of choice (C++, .NET, Java, VB, and VBA). Users could then develop a tool or extension for the flagship product of Esri (ArcGIS). Esri also decided to provide users with even more customization options with a very powerful product called ArcGIS Engine, which gave developers the full capability to customize every aspect of their flagship product. Since around the year 2000 and up until about 2014, ArcGIS Desktop and ArcGIS Engine were the main systems that most developers used to customize Esri's technology. The API was called ArcObjects and it was written in C++ and Microsoft's Component Object Model (COM). All these technologies evolved as the computer industry evolved and Esri, to its credit, kept pace despite the complexity and size of their GIS.

When it comes to web apps, Esri saw its first opportunity to leverage MapObjects, which was for Visual Basic, to allow users to take their work and push it to the web. As a result, they created MapObjects Internet Map Server (MOIMS). I actually had a great opportunity to create the first local government MOIMS app for Cabarrus County, NC back in the late 1990s. Back then, web mapping was pretty bare bones, but it worked! From there, ArcIMS came along, and then ArcGIS for Server was introduced. To aid web developers, Esri built their JavaScript API, which really brought about an incredible explosion of web apps over the past several years. All of this eventually led users to need a common platform to present their web content and apps in a portal. Eventually, ArcGIS Online (AGOL) and the on-premise version of AGOL, called Portal for ArcGIS, came about, which allowed users to create maps and apps very quickly. More importantly, this brought GIS to the masses.

Another important development over the past few years with Esri was the development of mobile solutions such as ArcPad and ArcGIS for Windows Mobile. Despite the success of these products, it is clear that ArcGIS Runtime is the future of mobile apps for the technology stack of Esri because of the rise of so many platforms, such as Android, Apple, and Microsoft-supported devices. As such, Esri is developing several client-side apps with ArcGIS Runtime for end users, such as Operations Dashboard for ArcGIS, Collector for ArcGIS, Navigator for ArcGIS, and ArcGIS Earth.

Despite the explosion of web apps, there still remains a need for native apps because if the Internet isn't available, many application scenarios simply aren't satisfied unless the user has the ability to work offline. As such, native apps are in abundance and growing. According to the site https://www.statista.com/chart/3530/app-store-growth/, native iOS apps are growing at a rate of 1,000 apps per day, as shown here:

That's phenomenal! Even more interesting is that people use native apps more than web apps, according to businessinsider.com, as shown here:

However, here's a question: Should a developer build a native app or a web app? Which is most appropriate? On the one hand, everyone wants their app to be functional, useable, reliable, performant, and scalable, right? Besides, do you want to create a web app, native app, or hybrid app? It's pretty common that building a native app takes longer and costs more than building a web app. Yet, web apps aren't as responsive and still don't work, and will never work if you don't have a connection to the Web. So, which approach should you take? (Note that it's possible to cache web content on a device, but that has its limitations.)

Deciding on whether to develop a web or native app is the most important decision you'll make once the app has been approved to be developed by your users or customer. In some cases, this is something already decided by the user or customer because they already have something in mind. On the other hand, if you're building an app for public consumption, you and your team will have to make the decision. No matter what, it can sometimes be a difficult decision, so it's important you understand the factors. Here are some of the deciding factors:

That's just a taste of the kinds of question that you need to carefully evaluate. Another important wrinkle in this decision is that sometimes you find you have to combine both web and native. As a developer, I have had to write an app for a large utility that needed to integrate into their enterprise asset system, which used a web app frontend but also required native performance due the volume of the data and the speed at which users drove down the road.

There are no easy answers here. You will need to carefully evaluate your alternatives and make the best decision. Don't be surprised if you start down one path and realize that the other path was more appropriate. If the answer isn't obvious, hire a consultant, review other apps (both native and web), determine the cost, get everyone involved, conduct a proof of concept, and most importantly, be prepared to learn and keep an open mind.

Broadly speaking, there are the following four types of app that ArcGIS Runtime can be used for:

A map-centric app is an app that mostly shows a map with other windows and content focused around the map, such as the following screenshot. Note that the map takes up the entire window. All interface elements are on the map:

Display of a map with content focused around the map

A non map-centric app will contain a map, but it isn't the central focus of the app. The map simply supplements the primary purpose of the map. Refer to the University of Oregon app, where Maps is just one of many parts of a larger app. Finally, there are apps where you don't see a map at all, but it might use geocoding and/or routing in the background and just return a coordinate or directions in the form of a list:

Now, there are new types of map displays, such as the Pufferfish, which is a globe that renders a map on its spherical display, as shown here:

Map with a spherical display

As noted earlier, ArcGIS Runtime is written in C++ and compiled on each supported platform natively. Unlike ArcGIS Desktop and ArcGIS Engine, which relied heavily on COM, Runtime Core is pure C++. Therefore, it is as small and efficient as possible. The following architecture diagram shows the high-level architecture of ArcGIS Runtime. As you can see in the yellow box, there is C++ Runtime Core. This means that it makes full use of the hardware and graphics card of each OS. This aspect allows very fast performance for displaying the map content and analysis; it literally means that the API is pretty much the same across all platforms. In other words, Esri is maximizing code reuse, while at the same time, maximizing performance because it is natively compiled. Not only that, Runtime Core is actually pretty small. On Windows desktop, at the current release, it's only about 23 MB in size for the x86 build. For the x64 build, it's only about 30 MB. As such, it will fit easily on disk for any modern device. Esri has also developed this architecture so that it also minimizes battery use. Lastly, each API on top of Runtime Core has been designed to expose the full capabilities of Runtime Core.

When it comes to the rendering engine, Runtime Core uses OpenGL, OpenGL ARB shader, OpenGL ES 2.0, DirectX 9, and DirectX 11. Each rendering technology is selected to optimize the performance on each OS. Therefore, a desktop computer with a powerful graphics card can achieve maximum performance whereas a mobile device will obviously use a less powerful graphics card but it still maximizes the use of OpenGL ES, for example. Not shown in the architecture diagram is the Hardware Abstraction Layer (HAL) between the rendering engines and Runtime Core. With HAL, Esri can add even more rendering engine capabilities on top of these native rendering technologies, such as DirectX:

As a developer of ArcGIS Runtime, it's important to understand that the choices you make at the API level at the top of architecture really decide what happens at the HAL level and lower.

Where does ArcGIS Runtime fit with the Esri platform and what do you need to really develop a native app? What is the meaning of the word platform? When an organization invests in Esri's technology, they are actually investing in something similar to a hardware platform. Think of it in this way: if your organization decides to go with the technology of Microsoft, they have deliberately chosen to purchase hardware that is compatible with the Windows OS, software that is compatible with Windows, the business applications of Microsoft, and so on. Well, this is effectively the same thing with the Esri platform. When an organization chooses the Esri platform, they are deciding to use the database formats of Esri, language choices, the very way Esri views the geospatial technology, and everything else that goes along with this choice.

ArcGIS Runtime is part of this platform. This doesn't mean you can use other technologies such as Google Earth, but it does mean that the organization has made a conscious decision to rely on a host of tools from Esri to satisfy their geospatial needs.

With that in mind, ArcGIS Runtime is a developer toolkit that you can use in and of itself, or as part of the Esri platform. If used within the context of the Esri platform, ArcGIS Runtime is a client app, as shown in the following diagram, in the top tier. However, you can also use ArcGIS Runtime without anything else from Esri. This means you don't need ArcGIS Desktop or Pro, ArcGIS Server, Portal for ArcGIS, AGOL Online, or any other technology. You can easily use publicly available web services or download shapefiles from publicly available sites and build an app. On the other hand, if you need to create your own data or build your analytical tools, you'll need one of these other technologies from Esri:

The preceding diagram will be found at http://www.wiki.gis.com/wiki/index.php/File:SDS15Fig2.11_ArcGISSOA.jpg.

ArcGIS Desktop (Desktop) is a very powerful desktop authoring technology that allows high-end GIS users to create data that includes complex editing, such as maintaining a complex electric utility network or editing a local government parcel database. It includes a wide variety of analytical tools, such as the ability to do routing, visibility analysis, line-of-sight analysis, spatial statistics, geostatistics, overlays, location-allocation analysis, and data management. In short, it allows you to create layers either from direct editing or as a result of analytical operations, and lastly, it allows you to publish your results (including analytical tools) to ArcGIS Server so that you can share it with others in your organization. You can even build scripts with Python or powerful tools with ArcObjects. Although ArcGIS Desktop has been around for about 15 years now, it is still the workhorse of Esri for the GIS power users. Despite this, it will eventually be replaced by its successors called ArcGIS Pro, which is the next natural step from the 32-bit ArcGIS Desktop to ArcGIS Pro, which is 64-bit technology.

ArcGIS Desktop and ArcGIS Pro are very important to the ArcGIS Runtime developer because they allow you to create layers and map objects that you may consume in your Runtime app. As ArcGIS Pro more and more begins to supplant ArcGIS Desktop, you will find that Pro will be more important to you as your requirements and needs grow.

After you've created layers and maps, you will need to make these applications available to ArcGIS Runtime. This is done with ArcGIS Desktop or Pro as a web service. There are several kinds of service that you can expose and that ArcGIS Runtime can use. You can publish and consume basemaps, map packages, tile packages, map servers, feature services, and so on. Throughout this book, these topics will be expanded on and consumed in the code examples.

Once a service has been created, it can be consumed with AGOL or Portal for ArcGIS (Portal). Users can add these services to their online maps and do further analysis with them. It should also be noted that users can also publish content on AGOL or Portal for ArcGIS without ArcGIS Desktop. On AGOL, you have the ability to create and use data in some pretty awesome ways. For example, with AGOL you can do Hot Spot analysis without ever needing ArcGIS Desktop or Pro. You can even add data to an online map in AGOL and ArcGIS Runtime can consume the resulting service. So, do you really need ArcGIS Desktop or Pro? Well, like anything, it depends. If you need sophisticated analytical or editing capabilities, Desktop or Pro is the technology to use. Otherwise, you may find that AGOL may be more than sufficient. In the end, each technology should be carefully evaluated along with the cost. If you're building a somewhat basic consumer product, you may find that AGOL will be more than sufficient. On the other hand, if you're part of an enterprise GIS that has invested in GIS technology and staff, it's makes perfect sense to use Portal, and Desktop, and Pro. Many organizations use Desktop/Pro, AGOL, Portal, custom web and desktop apps, and other third-party enterprise systems and databases, all in an effort to satisfy their users.

For more information about the Esri platform, refer to http://www.esri.com/~/media/Files/Pdfs/products/arcgis-platform/architecting-the-arcgis-platform.

Now that we've covered some background information about Esri's technology, let's return to ArcGIS Runtime. ArcGIS Runtime is the first and foremost SDK and an API. It's an SDK that provides you with the tools (Visual Studio templates, samples, and so on) so that you can quickly build apps. It exposes a rich API in the form of objects so that you can satisfy nearly any requirement your app needs. You can simply pick and choose what you need and decide how to implement the required solution. However, before you do that, you really need to know what you expect and the steps required to get started. As you go through the remaining parts of this book, you will be exposed to the SDK and API, which will gradually make you aware of all of the capabilities and options you have to consider to build the high-quality apps.

You may be wondering why this book is focused on the .NET version of ArcGIS Runtime. Well, for starters, many Esri users like .NET, especially C#. Another reason is that if you know Java and Android, you'll find it easy enough to read the C# code because Java and C# are similar. Another important reason is that Esri has released 3D first in the .NET SDK, so it was hard to pass up this opportunity to talk about one of my favorite subjects (3D). ArcGIS Pro will also be based on .NET, so hopefully some of the skills you learn about here, especially Model-View-ViewModel (MVVM), will also apply to Pro. Furthermore, there seems to be a general sense that Visual Studio is a great Integrated Development Environment (IDE), as opposed to Eclipse, NetBeans, Google's Android Studio, and the other IDEs, but that's just my opinion. This is not anything against those IDEs, I just prefer Visual Studio. Very soon Esri is going to release the Xamarin® support, which means that the developers will be able to write an app in Visual Studio, compile it natively, and run it on Windows, Windows Store, iOS, and Android. I suspect you'll agree with some of these and disagree with others. Regardless, I hope that by the end of this book, you will have a solid understanding of the API so that you can move to any other SDKs, and it will be just a matter of switching your brain from C# to Android or to C++ or to Java.

In order to successfully install and use ArcGIS Runtime, you will need to have a PC that meets the minimum system requirements. You can find the system requirements on the ArcGIS Runtime site, https://developers.arcgis.com/net/desktop/guide/system-requirements.htm.

In order to start building an ArcGIS Runtime app, you will need the following IDEs and toolkits:

Install-Package Esri.ArcGISRuntime –Version 10.2.7.1234

Now that your development environment is established, your next task is to create an initial app.

<Window x:Class="Chapter1.MainWindow"
  xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:esri="http://schemas.esri.com/arcgis/runtime/2013"
    Title="MainWindow" 
    Height="350" 
    Width="525">
  <Grid>
    <esri:MapView x:Name="MyMapView"
      LayerLoaded="MyMapView_LayerLoaded">
    <esri:Map>
      <esri:ArcGISTiledMapServiceLayer ID="Basemap"

      ServiceUri="http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer"/>
      </esri:Map>
    </esri:MapView>
  </Grid>
</Window>

using Esri.ArcGISRuntime.Controls;
using System;
using System.Diagnostics;
using System.Linq;
using System.Windows;

namespace ArcGISApp1
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }

        private void MyMapView_LayerLoaded(object sender, 
            LayerLoadedEventArgs e)
        {
            if (e.LoadError == null)
                return;

            Debug.WriteLine(string.Format("Error while loading layer 
                : {0} - {1}",
                e.Layer.ID, e.LoadError.Message));
        }
    }
}

Enhancing the app

Let's add a couple of features to this app. First of all, let's add the scale to the map. After all, this is a mapping app and scale is important in any map. Perform the following steps:

1. Add the following lines shown in the code sample after the closing </esri:MapView> tag:

   <TextBlock Background="#77000000" HorizontalAlignment="Center"
     VerticalAlignment="Bottom" Padding="5"  
     Foreground="White">
       <Run>Map Scale 1:</Run>
       <TextBlock Text="{Binding ElementName=MyMapView, 
         StringFormat={}{0:0}, Path=Scale}" 
         FontSize="12" FontWeight="Bold"  
     Foreground="White"/>  
   </TextBlock>

2. Run the app. You will see the scale shown at the bottom of the page, as shown in the following screenshot:

   

The way these steps work is actually just like any other Windows Presentation Framework (WPF) app. In this case, we're making a TextBlock tag bind to the MapView class. Check out the Text property of the inner TextBlock tag. It is being bound to the element called MyMapView. The MyMapView element is the identifier of the MapView class. It is also using the Scale property with Path from the MyMapView element.

In other words, the MapView class has a property called Scale, and the TextBlock tag is simply binding to it just like it's possible to bind to any other WPF FrameworkElement type. All other properties of the TextBlock tags are standard properties. There is also a Run element in the code just to hold the text, Map Scale 1. Another interesting thing you can glean from this is that if you want to place FrameworkElement types on top of the map, all you have to do is to place your XAML after the closing MapView element.

Of course, just showing a basemap with a scale isn't very interesting, so let's add some more layers that will allow us to actually do something, such as search for a state or a city. In order to do that, you will need to take a look at some of the publicly available map services on AGOL. Perform the following steps:

1. Navigate to http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer.

2. The name of the service is USA. Click on ArcGIS JavaScript beside View In. You should be able to see a map of the United States.

3. Read the Service Description option. It's short in this case but tells you exactly what the service is all about.

4. Under Layers, you will note that there are four layers listed—Cities, Highways, States, and Counties.

5. Go back to Visual Studio and add the following lines of code to your XAML after the first layer. Make sure it is after the first layer and before the closing </esri:Map> tag:

   <esri:ArcGISDynamicMapServiceLayer ID="USA" ServiceUri="http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer"/>

6. As you can see, a dynamic map service has been added using ArcGISDynamicMapServiceLayer. It was given a name, USA. A dynamic map service contains any number of layers. They return the geometry and attributes in the layer across the Internet in the form of an image.

7. Run the app and you will see a map with all the layers over USA. Feel free to zoom in so that you can see more details.

8. Close the app. The next thing that would make the app more interesting is to add the ability to search for a city, county, or state name; so let's do that.

9. Enter the XAML code, as shown here, after the closing MapView element:

   <TextBlock Name="Search" Background="#77000000" 
     HorizontalAlignment="Center"
     VerticalAlignment="Top" Padding="5" 
     Foreground="White" >
     <Run>Search for  </Run>
     <TextBox Name="SearchTextBox" 
       Text="Lancaster">
     </TextBox>
     <Run>  in the Cities, Counties or States layer. </Run>
     <Button Content="Find" Width="30"></Button>
   </TextBlock>

10. As you can see, a new TextBlock tag has been added after the closing MapView element with some text using <Run>, and a Button tag has been added.

11. Run your app. You will see the new XAML at the top of your map, as shown in the following screenshot. You can also see what it looks like in the XAML Designer workspace:

    

12. If you run this app and click on Find, nothing will happen because we haven't wired up the button to an event handler.

13. If you haven't done this before, read carefully. In the button's XAML after Width="30", start typing the word Click, and then press the Tab key twice. You will note that as with other WPF apps, this action prompts the creation of an event handler, as shown here:

    

14. After you've done this step, an event handler will be created in MainWindow.xaml.cs. We will return to this event handler after the next step.

15. Let's make a few more changes to this code. First, in the Window element's properties, change the Height attribute to 600 and the Width attribute to 800. Then, add some Grid row definitions, as shown in following code sample. Lastly, below the TextBlock tag, add a DataGrid tag and name it MyDataGrid. Make sure you've entered exactly what is shown in the code sample. Also, note that the scale related to XAML has been removed:

    <Window x:Class="ArcGISApp1.MainWindow"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:esri="http://schemas.esri.com/arcgis/runtime/2013"
      Title="MainWindow" 
      Height="600" 
      Width="800"
    >
      <Grid>
        <Grid.RowDefinitions>
          <RowDefinition Height="400" />
          <RowDefinition Height="200" />
        </Grid.RowDefinitions>
    
        <esri:MapView x:Name="MyMapView" Grid.Row="0"
          LayerLoaded="MyMapView_LayerLoaded" >
          <esri:Map>
            <esri:ArcGISTiledMapServiceLayer ID="Basemap"
              ServiceUri="http://services.arcgisonline.com/ArcGIS/rest/services/World_Topo_Map/MapServer"/>
            <esri:ArcGISDynamicMapServiceLayer ID="USA" 
              ServiceUri="http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer"/>
          </esri:Map>
        </esri:MapView>
    
        <TextBlock Grid.Row="0" Name="Search" Background="#77000000" 
          HorizontalAlignment="Center"
          VerticalAlignment="Top" Padding="5" Foreground="White" >
          <Run>Search for  </Run>
          <TextBox Name="SearchTextBox" Text="Lancaster"></TextBox>
          <Run>  in the Cities, Counties or States layer: </Run>
          <Button Content="Find" Width="30" Click="Button_Click"></Button>
        </TextBlock>
    
        <DataGrid Name="MyDataGrid" Grid.Row="2" Height="200"></DataGrid>
    
      </Grid>
    </Window>

16. Right-click on MainWindow.xaml and click on View Code, or just double-click on it.

17. Add the following using statements at the top of the source file:

    using Esri.ArcGISRuntime.Controls;
    using Esri.ArcGISRuntime.Data;
    using Esri.ArcGISRuntime.Geometry;
    using Esri.ArcGISRuntime.Layers;
    using Esri.ArcGISRuntime.Tasks;
    using Esri.ArcGISRuntime.Tasks.Query;

18. Also, note that in the source code file, there is a new private method called Button_Click. It currently has no code in it. We will now populate it with some code so that we can search for a city, county, or state. Enter the following code in the event handler (Button_Click). Also note that the async keyword has been added to the event's signature:

    private async void Button_Click(object sender, RoutedEventArgs e)
    {
    
        var url = "http://sampleserver6.arcgisonline.com/arcgis/rest/services/USA/MapServer";
        var findTask = new FindTask(new Uri(url));
    
        var findParameters = new FindParameters();
        findParameters.LayerIDs.Add(0); // Cities
        findParameters.LayerIDs.Add(3); // Counties
        findParameters.LayerIDs.Add(2); // States
    
        findParameters.SearchFields.Add("name");
        findParameters.SearchFields.Add("areaname");
        findParameters.SearchFields.Add("state_name");
    
        findParameters.ReturnGeometry = true;
        findParameters.SpatialReference = MyMapView.SpatialReference;
    
        findParameters.SearchText = SearchTextBox.Text;
        findParameters.Contains = true; 
    
        FindResult findResult = await 
            findTask.ExecuteAsync(findParameters);
    
        var foundCities = 0;
        var foundCounties = 0;
        var foundStates = 0;
    
        // Loop through results; count the matches found in each layer
        foreach (FindItem findItem in findResult.Results)
        {
            switch (findItem.LayerID)
            {
                case 0: // Cities
                    foundCities++;
                    break;
                case 3: // Counties
                    foundCounties++;
                    break;
                case 2: // States
                    foundStates++;
                    break;
            }
        }
    
        // Report the number of matches for each layer
        var msg = string.Format("Found {0} cities, {1} counties, and 
            {2} states containing '" + SearchTextBox.Text + "' in a 
            Name attribute", foundCities, foundCounties, 
        foundStates);
        MessageBox.Show(msg);
    
    
        // Bind the results to a DataGrid control on the page
        MyDataGrid.ItemsSource = findResult.Results;    
    }

19. Once you've completed entering the code, run the app. You should note that the window is larger and that there is a data grid at the bottom of the window. You will also see all the layers in the dynamic map service. You can now click on the Find button. A message box will appear, indicating the number of cities, counties, and states that have the name Lancaster in them. Refer to the included sample project code with this book, named Chapter1, if you need any help:

That was the name of my home town. Try yours. Note that not all cities in the USA are in the Cities layers.

There were several things in the code-behind file. First, the URL of the map service was set, a FindTask constructor was created, a FindParameters argument was added, search fields were set, a parameter was set to return the geometry, the spatial reference was set, the search text was set, a parameter was set as to whether to use the exact text entered, FindResult was executed asynchronously, the results were looped over to find the counts in each layer, a message was created with the counts, and finally, and most importantly, the results were passed into the DataGrid tag's ItemsSource so that it can be viewed. In the next chapters, we will go over these objects in more detail.

Now that you've created a simple app, similar to a traditional Windows Forms app, except with WPF, we're going to go into the next chapter and explain why this is not an ideal approach. We're going to redesign this app so that it's more reusable. What is the best way to write code that is reusable, maintainable, and configurable? How would we automate the testing of this app as it stands? How would you make it so that you could change the base layer without having to change the XAML and recompile the app? These are all important questions that need to be thought of before writing a professional level app. In the chapters to come, we will address these issues while explaining the main features of ArcGIS Runtime in much more detail.

In this chapter, you've been exposed to the full breadth of app development with Esri's premier native apps SDK. You were introduced to ArcGIS Runtime, provided with high-level examples of its use and application, the language choices you have, a little history of Esri's development tools, the use of native apps across the broader app market, the types of mapping apps, the architecture of ArcGIS Runtime, areas where ArcGIS Runtime fits within the Esri platform, installation steps, building your first app with ArcGIS Runtime, and finally, some things to think about when it comes to configuration, testing, and structuring your app.

In the next chapter, we're going to take the app we've built here and refactor it so that it fits the MVVM pattern. This will allow us to make our apps maintainable and provide us with a structure for the remaining chapters.