00:01This is a session about server object extensions.

00:04My name is Sterling Quinn.

00:05I'm a product engineer on the ArcGIS Server development team.

00:10I work in the Olympia, Washington, office.

00:15A couple years ago, I tried to build a server object extension, and I complained about the lack of documentation on SOEs...

00:21...and they said, You want to own it?

00:24So I got the job of kind of revamping the documentation, and now I've learned a little bit about it and can give these workshops.

00:31I do have some technical help coming at the end to help with the questions.

00:36One thing that they did, which is kind of bizarre, is they scheduled me for another session right after this one...

00:41...that I have to give, clear on the other side.

00:43So I am going to go for about one hour, and then I'll stop a little early and start taking questions.

00:49But I also have some help coming to...from the product engineers who will help me to answer questions at the end.

00:55I ask you that if you have a question during the time of this presentation that you write it down and ask it at the end...

01:01...just so we can make sure we end on time, and we'll take as many questions as we're able to...

01:07...and then my friends from the product engineer team will stick around and help to answer whatever's left.

01:12Now, we love to talk to you about server object extensions.

01:14We've noticed a lot of traffic at the server showcase this week, asking about server object extensions.

01:19It's becoming very clear that as people migrate to 10.1 or prepare to migrate...

01:24...they're thinking very much about server object extensions, and I think the amount of attendance here at this session...

01:30...speaks to that.

01:31It's a greater crowd than we've had in previous years.

01:36Today, I'll start from the beginning.

01:38So if you're new to server object extensions, I will give a brief introduction.

01:41I also want to present a few alternatives to server object extensions, or SOEs, as I'll refer to them from here on out.

01:50There are some new things that have become available in the out-of-the-box product...

01:54...that may make it unnecessary for you to develop an SOE.

01:58And if you could avoid developing an SOE, you might save yourself a little bit of time.

02:02So I will cover that before I dive into the details of how to actually write an SOE and deploy one.

02:10I also want to show you some resources you can go to after this conference for getting help on working with SOEs.

02:22So an SOE is actually a class library that you can write in .NET or Java that extends the base functionality of ArcGIS Server.

02:31And so it's a way for you to draw on the power of ArcObjects and extend ArcGIS Server in whatever way that you choose.

02:41You write SOEs as web services, so you give them a set of things that they're able to do and methods that they can call...

02:49...and then those go down into your business logic, and you are able to call ArcObjects.

02:55You need to deploy an SOE to your server.

02:57I'll show you how to do that.

02:58That's become a lot easier in 10.1, so I'm excited to show that part of it.

03:04This is 10.0 Manager.

03:06It probably will look familiar to you.

03:09When you make a new service, you can choose from this check box list of capabilities...

03:14...and you're probably familiar with the top ones, but you'll see at the bottom I've created my own that I can check.

03:20This one's called Spatial Query.

03:22That is an SOE that I've deployed to my server.

03:25So that's where people can enable that functionality.

03:32There's a number of advantages of making an SOE, despite the work that it takes to make one; you get these advantages.

03:38One is that you can draw on that functionality of ArcObjects.

03:41Many of you may have written code in ArcObjects that you've used over the years.

03:45Maybe you used it in the ADF or even before, and this is a way you could reuse that code.

03:52Also, if something's not available through the out-of-the-box geoprocessing tools...

03:58...you could program that functionality using an SOE.

04:03Another nice thing about SOEs is that they tend to run pretty quickly, because they're calling ArcObjects directly on the server.

04:09There's no additional overhead of the geoprocessing framework or tools, and we've seen that they tend to run very fast.

04:16They're also pluggable, meaning you could develop an SOE, and if you develop it wisely...

04:21...you could reuse it on various different service types or, sorry, on various different services that you deploy on your server.

04:31And, finally, you can expose an SOE as a web service.

04:33You can expose it through REST so that it can be consumed by the web APIs.

04:38If you've been using the web APIs, meaning JavaScript, Flex, Silverlight...

04:43...and you want to know how to do some kind of advanced functionality with those APIs, then an SOE may be the answer.

04:53Just to demonstrate what kind of things could be done with an SOE, I'll show a couple of examples.

05:01The first one I'll show was developed by the applications prototype team at Esri.

05:06Oh. Okay. Let's get out of here.

05:41Now you all have the URL. Can go there yourself.

05:53Well, let's try the other one, and we'll see if this is just an Internet problem or a problem with this service.

06:12Okay. I don't know what the issue was with that one, but I will show this one.

06:15This one does some dynamic segmentation, so it allows me to go to the map...

06:22...and I just developed this little app with JavaScript that I can draw a free-hand polyline...

06:28...and it will do some dynamic segmentation to place mile markers along my route.

06:34Now, this is a thing that you might not be able to easily accomplish on just one feature...

06:39...by using the out-of-the-box geoprocessing tools, so it's a good case for a server object extension.

06:47One fun thing about this SOE, let me change to kilometers, and I'll draw another polyline.

06:54I'm going to draw a very long one.

06:57Is that it was able to place those markers very quickly.

07:00So this is a...this is part of that speed of the SOE where it was going directly into ArcObjects.

07:05This one actually creates an in-memory feature class, and then it assigns m-values to it.

07:10It calculates those markers, and then it draws them on the screen.

07:13And it was able to do all of that very, very quickly through an SOE.

07:19So I like to show this one.

07:20The other one that I was going to show, I'm not sure why it's not working...

07:24...is able to make an elevation profile as you drag a line across the country or across a state.

07:31It reads the elevations in the underlying raster, and it computes the profile.

07:37Again, that's something that you might not be able to do with out-of-the-box tools or APIs.

07:42So it's a good case for an SOE.

07:47Before we dive into how to develop an SOE, I'd like to cover some alternatives, because you may not need one.

07:54And so I'll just list a couple of reasons. We saw people writing a lot of ArcObjects code in the past...

08:00...and I'll try to talk about the most recent out-of-the-box functionality at 10.1.

08:06A lot of times, we saw people writing ArcObjects to develop layouts for web-based printing.

08:12There are a couple of things in 10.1 that make printing easier.

08:16One of them is an out-of-the-box service that we set up...

08:20...we set it up for you actually when you create a new site in 10.1 for ArcGIS Server.

08:25It's called Printing Tools, and it's a geoprocessing service that can take a web map and make a printable image of that map.

08:32And you're able to call in to this printing tool service using the web APIs.

08:37So that's very useful.

08:38If you have advanced printing scenarios where you want to print in different projections...

08:43...or export very large images for printing on a plotter...

08:48...ArcPy mapping has a new function that can convert a web map into a map document...

08:54...and then you can have this MXD on the server, and you can do things like switch in your own local data...

09:00...to replace the cache tiles and get a high-resolution image for printing.

09:04So through use of ArcPy mapping and the printing tool service...

09:10...you might be able to replace some of that old custom code that you had in the past for generating layouts for printing.

09:16Another thing we saw people writing ArcObjects for was changing symbols on the fly within a map service...

09:23...trying to change colors or layer order or add layers.

09:27A lot of that is remedied at 10.1 by this new concept of dynamic layers that is available in map services.

09:37So what that means is that when you request a map service through...you can also specify some of the drawing information...

09:45...such as the layer order and the symbol set to use.

09:48And that allows you to use a dynamic map service in various ways, with different types of symbology and layer orders.

09:55And it no longer requires that you write custom ArcObjects that go into the server object and change those layers around.

10:04Also, you may be able to do some dynamic work with client-side graphics using a web API's feature layer...

10:10...to pull down graphics onto your browser and draw them using different shapes and colors and highlight them...

10:16...and so you may not need ArcObjects rendering if you use the client-side graphics or the dynamic layers.

10:26Especially with the ADF, we saw people writing a lot of ArcObjects code for web editing.

10:32The current way for web editing with Esri APIs is to use the feature service...

10:37...and then the different APIs for JavaScript, Flex, and Silverlight have editing widgets and classes, helper classes...

10:44...that help you with editing, and you do it through REST.

10:52In some cases, you may be able to make your workflow work in a model inside of ModelBuilder...

10:58...and if you can get it to work in ModelBuilder, then the next step would be to publish it as a geoprocessing service.

11:04A geoprocessing service is a web service that has some set inputs and outputs, and then it does...

11:10...runs geoprocessing tools on the server to get you your output that you want.

11:15And so if you're able to make a model that does what you need...

11:18...you may not need to write all that logic in ArcObjects in your SOE.

11:22This might save you some time trying to figure out ArcObjects coding.

11:27Also, if you want to write a script tool in Python and expose some script tool parameters on it...

11:34...you could publish that script tool as a geoprocessing service.

11:37So if you feel more comfortable doing things in Python and you're able to accomplish what you need with Python...

11:42...I would encourage you to look at this route and write the Python and then just publish it as a GP service.

11:50Finally, the geometry service...it seems like each release this gets a little bit better and has more and more methods on it...

11:56...for things like measurement, basic editing, things like trimming, extending, calculating areas, lengths.

12:04If you haven't looked at the geometry service recently and what it could do...

12:07...you should examine its list of methods and capabilities...

12:10...to see if that might replace some of the code that you have written or were going to write.

12:17Now, if none of those previous things fit your need and you still need to do something beyond the out-of-the-box services...

12:24...then an SOE would be appropriate.

12:28And, again, if you're concerned about performance, you might also look at an SOE...

12:32...if you want to just call into the ArcObjects directly and avoid the overhead that might come with the geoprocessing service.

12:43Well, let's talk about how you would approach developing an SOE.

12:47We're going to focus on REST web service SOE, although there is a SOAP SOE available as well.

12:56I'm going to show this in .NET.

12:58This year, we just have one session on SOEs, so I apologize; there won't be a separate Java session.

13:04A lot of the concepts that I will show with .NET SOEs also apply to Java.

13:10You can develop both REST and SOAP SOEs in Java, and you can do that in Eclipse.

13:17In some cases, it's even easier to develop an SOE in Java...

13:21...because the Java has some wizards that go into Eclipse that help you to build the schema of the SOE.

13:29So you will notice those if you attempt to build an SOE in Java.

13:34Both SDKs, the .NET ArcObjects SDK and the Java SDK have detailed documentation on how to approach an SOE.

13:42So the things that I'm going to show you today are not secrets.

13:44They're very well covered in the documentation.

13:51In order to develop an SOE, it's important that you know either .NET or Java.

13:57And then it helps to know a little bit about how web services communicate.

14:01You don't have to understand all about REST or SOAP...

14:05...but it is important to know how a web service takes in a request...

14:10...or how a web service takes in a request and then prepares a response and sends it back.

14:16You also want to know some ArcObjects so that you can perform your business logic within the SOE.

14:23And then optionally, if you want to develop advanced options for server administrators on your SOE...

14:30...you can develop pages that plug into Manager or ArcCatalog so that users can...so that administrators can set those properties.

14:40Now, that's somewhat out of scope for this presentation, but I can show where you can find samples in the SDK that do that.

14:49Let me show an SOE that I will walk through with you today.

14:52This is an SOE that's included in the SDK.

14:55So if you install the SDK, you will have this, and you can look at the code, just like we're looking at it today.

15:07Oops. This SOE allows me to click a point on the map, and so my input to the SOE is this point as well as a buffer distance.

15:18Right now, that's 3,000 meters, and it performs a buffer of 3,000 meters around my point...

15:24...and then it clips out those features of vegetation, and it sums up the different types of vegetation within that buffer...

15:35...and reports it inside of a table.

15:37I just used a Dojo grid here so I could sort the table if I want.

15:41This is a little JavaScript app that I wrote to consume the SOE.

15:45And I can repeat it elsewhere.

15:47I can change the buffer distance if I want.

15:53So this is complex enough that it has some ArcObjects I can show you as we walk through...

15:57...but it's also simple enough that hopefully it's not overwhelming to understand...

16:01...the inputs and the outputs of this SOE.

16:09So I'm going to take you through the journey of writing this SOE and working on it from the very beginning.

16:14When you develop and deploy and SOE, your first step is to write the code and then optionally...

16:19...write that property page that administrators can use to set advanced properties on the SOE.

16:25And then you'll deploy the SOE to ArcGIS Server.

16:28After that, you can publish a service that enables the use of the SOE and then, finally...

16:34...you can develop a client application to consume the SOE.

16:38However, as you go through these steps, you'll want to always have your client in mind...

16:43...and think about the ways that you're returning the web service response from your SOE and how the client will work with it.

16:52So let's start with writing the code.

16:54All SOEs implement these three interfaces that you see up here in yellow.

17:01IServerObjectExtension just has the basics that you need to start and stop the SOE.

17:08There's IObjectConstruct, which has...where you can put your initialization logic.

17:13Every time that you start a service, this IObjectConstruct code runs.

17:18So if you have some code that just needs to run one time at service startup...

17:23...you can put it here to avoid it running every time that you call the web service.

17:26And I'll show an example of that later on.

17:29Then IRESTRequestHandler is an interface that will help you to bring in and return web service requests and responses.

17:37Now, you don't have to know all the code to implement these interfaces...

17:41...because you have a template that's available for you in Visual Studio or in Eclipse that can help you get started.

17:48The .NET template is installed when you install the .NET ArcObjects SDK.

17:53And so let me show you how you would access that.

17:56I'm just going to open Visual Studio to a blank page.

18:01I have installed ArcGIS Server on here, and I've installed the ArcObjects SDK.

18:06If I choose New Project, I'll be able to see this item, ArcGIS, over here on the left...

18:14...and then a menu option for server object extensions.

18:18And that's where I get the templates for REST and SOAP.

18:20One thing to watch out for is by default, this will go to .NET Framework 4, and you won't see the templates.

18:26So you need to change this to 3.5.

18:31Let's just create a new one, and I'll show you what code is created with this template.

18:38What you'll see is that you'll have some references already set up for you for the libraries that you need...

18:44...the very minimum set of libraries to develop an SOE.

18:54So you can see some of those references in the Solution Explorer.

18:58And then if you open the code file, you'll see that it has some using directives here and the class for your SOE.

19:07Now, up here, before the class is declared, you'll see some .NET attributes.

19:13So these have like a display name that you'll see in Manager for your SOE and whether it supports REST or SOAP.

19:21You can modify these as needed.

19:24In the past, if you worked with SOEs at 10.0 or in previous releases...

19:28...some of this code was used when you actually wrote your SOE registration code.

19:33It's now...these properties have now been brought into the actual SOE code file...

19:39...and I'll explain a little bit more about how that works later on.

19:43One thing you'll notice is that when this class is declared, you'll see those three interfaces that are required that I mentioned...

19:51...IServerObjectExtension, IObjectConstruct, and IRESTRequestHandler.

19:56A lot of this code you won't touch.

19:58You need to leave it how it is, and it's the same with all SOEs.

20:02However, you can modify the code within IObjectConstruct if you have initialization logic.

20:11You'll also modify the code down here to create the schema for your web service.

20:15And the schema determines what actions your web service will be able to do...

20:20...and I will get into this in a little more detail later on.

20:24And then you'll have handler functions for each item in your schema.

20:29And so this just stubs out a very small SOE for you, and you can substitute your own code in here in the handler functions.

20:43So what happens in the template?

20:44I showed this.

20:46Basically three things: setting up the SOE, all the construct logic, creating the schema...

20:52...and then handling the different resources and operations on your SOE.

20:58You might have seen that there was a reference to this library, Esri.arcgis.soesupport.

21:03This contains some very important helper classes that you'll use as you develop your SOE.

21:09It gives you special objects that you can use for serializing and deserializing messages to the SOE...

21:18...as well as logging messages in the server logs and error handling.

21:24When you go to create an SOE web service, you need to decide what resources and operations it will expose.

21:31You can think of resources as something that gives you back information, almost like properties...

21:37...whereas operations do something or execute an action.

21:40Operations are more like methods on your SOE.

21:44So you'll need to determine those things that you want your SOE to do, and then you snap them together to build a schema.

21:50And you may need to diagram this on a whiteboard.

21:53It may be helpful to write out all the functions that you have.

21:56Maybe and you have these functions from previous years of code that you've written...

22:00...but what things or what methods are you going to want people to be able to call on your SOE?

22:05That's the part of creating the schema.

22:09You also have the ability to restrict users of the SOE from calling certain groups of methods.

22:17In the SOE developer documentation, we call these capabilities.

22:22That's kind of confusing, because up here you see a tab called Capabilities, which means the SOE itself.

22:27So please don't get confused by that.

22:31In Manager, you'll see that these are referred to as Operations Allowed.

22:35In any case, no matter you call them, these refer to certain groups of methods or operations on your SOE...

22:41...and if the administrator unchecks one of these items, it will restrict the end user of the SOE from calling those methods.

22:49And so as you set up your schema, you'll need to determine if you want to divide up your operations...

22:54...into these different allowed operations sets.

23:00Here's an example down here of where somebody defines a resource in their code...

23:06...and one of the parameters is the actual name of this group of operations that can be called, so Get Info.

23:16If somebody wants to call Custom Layer Resource, then Get Info will need to be checked on in Manager.

23:21That's essentially what this means.

23:25Let's take a look at some schemas from some of the sample SOEs in an SDK.

23:30We're going to look at two of them just so you can get an idea of how these are set up.

23:34I guess first, I will show you what this spatial query SOE looks like inside of the Services directory.

23:40So if I go to...I need this later, so I'm going to copy it.

23:46If I go and look at my services, here's Yellowstone, and this was the vegetation service that I was showing earlier.

23:53We scroll down on this, and you'll see your SOE here next to the supported extensions item.

24:04And so this SOE has a very simple schema.

24:06It has one resource which returns nothing, basically.

24:09It's the root resource.

24:11And then it has one operation, which is the actual spatial query.

24:17And then the user can type in, or can enter a location, an x,y point and then a buffer distance and execute the SOE.

24:25So how do you build this type of schema using code?

24:29I'm going to open the code for that particular SOE, and let's go down to the Create REST Schema.

24:37So in this case, one root resource is set up, which does basically nothing.

24:43It has a handler function, but there's not really anything in that handler.

24:47You can see how short it is.

24:51The operation...sorry about this...the operation is defined here...

24:57...and you can see that's where we define the input parameters for that operation.

25:01So somebody has to give a location and a distance, and then it will send back JSON as the response.

25:07And this operation has a handler function, which is defined down here later in the code.

25:13This handler function is where you're going to start diving into decoding the incoming message, running your ArcObjects...

25:20...all of this, and then preparing a response.

25:25Let's look at one that has a little more detailed schema.

25:32So there's another SOE in your SDK that you can look at called Find Nearby Features.

25:38At this one, you'll see actually has two resources defined.

25:42So it's got a root resource, but it also has another one called Custom Layer Resource...

25:46...and then it has one operation, Find Near Features.

25:50And down here at the bottom, these resources and operations are added together into a schema by calling this Add method.

25:58So it may be that in your SOE, you have to define numerous resources and operations as is going on here...

26:06...and then add them together to make a schema.

26:13[Unintelligible] I already talked about these handler functions.

26:15We'll take a closer look at one of those later on.

26:18Your handler functions have to work with JSON, your incoming web server request.

26:24You have to deserialize it into something you can use with ArcObjects.

26:28And you've got to do something with it, run your business logic...

26:31...and then you have to prepare a response that will be serialized back into JSON to return to the client.

26:40A very important class that will help you with this is in that helper library SOE support.

26:45It's call JSON object.

26:48There are also...on this object, there are some methods that will help you to deserialize...

26:55...and serialize the web service requests and response, respectively.

26:59So suppose that you're...as an incoming parameter, you get something like a number, a double.

27:06You can use this method, TryGetAsDouble to pull out that double from the incoming web service request...

27:12...and then start working with it in your code.

27:16Similarly, if you're done running your business logic...

27:19...and you need to return a response that has something like a double in the response, you can use this method AddDouble...

27:26...to prepare your JSON object to send back to the client.

27:31Now what if you have something like geometry that's coming in...

27:34...like somebody drew a polygon and they're submitting it to the SOE?

27:38How do you deserialize that?

27:41Well, there are also some conversion methods...there's a conversion class here that has these methods...

27:47...where you can bring in geometries, so you can take JSON and convert to ArcObjects and you can also go backwards.

27:55You can go from ArcObjects geometry to JSON geometry.

27:59This is very helpful.

28:02Here's a diagram of what's happening when somebody runs that spatial query SOE and they click a point...

28:08...and they provide a buffer distance.

28:10So I'm getting two things in, and they're coming in as this JSON object class.

28:15This is my input.

28:17Now, inside of that, I have another JSON object.

28:19So it's possible to nest these things.

28:22So I need to get that out by calling TryGetJsonObject.

28:26So now I've got this JSON object that just has the point x and y information.

28:32And then I can run the conversion method, sorry, the two-geometry method to convert that into an IPoint.

28:39And once I have an IPoint, I can start working with that in ArcObjects.

28:44By the same way, to get the double out of here, I just call this TryGetAsDouble method...

28:49...and then I've got the double that I can work with, and I can also work with this in conjunction with my ArcObjects code.

28:57Then when I'm ready to prepare a response, I've got all those clipped vegetation polygons...

29:01...that I've got to somehow send back in my response.

29:05I've got a whole bunch of IPolygon and, again, you can run these conversion methods so I could convert this to JSON object...

29:14...and now I've got a bunch of this JSON object, and each one holds a polygon.

29:18In my case, I take advantage of a .NET list to hold onto those, and then I call to array to pack this into the response.

29:27I've also got that table that I showed on the left of the application that has the vegetation type and the...

29:33...oh, I think it was the square meters of, yeah, that type of vegetation.

29:37So I've got a bunch of key value pairs that I also need to pack into the response.

29:41So in this case, I can call AddString on those keys and values and put them into an array and then add that to my final response.

29:51You're just doing this process of taking in the request, pulling things out, doing your stuff, and then packing it into a response.

29:58Let's see how that looks inside the code.

30:01So going back to that example.

30:06Okay, as soon as I start the handler function for that spatial query, you can see that I'm working with this JSON object class...

30:14...and I'm running this TryGetJsonObject method to get out that point.

30:20That's my location.

30:21And I ran the conversion method to convert that into an IPoint, and then I can use that point later on in my code.

30:30Down here is where I'm calling that TryGetAsDouble, and then I can use the double as a distance later on in my code.

30:39Down here I have all the ArcObjects that do the spatial filter and clip that geometry...

30:44...and then get it ready to send back to the client.

30:47So I have a bunch of polygons.

30:53Down here you see me creating more JSON objects, and this is preparing to send back a response.

30:58And I'm just adding those different...the things that I created, the polygon geometries...

31:05...and the key value pairs back into the JSON object to get it ready to return right here.

31:13So probably if you have a lot of existing ArcObjects code...

31:16...most of your work is going to be done writing this deserialization and serialization.

31:22It's important to think about what things your SOE will take in and out and how you will deserialize and serialize those.

31:28And as you look at the examples in the SDK, you'll begin to see patterns of how that's done.

31:39There are some certain rules for accessing map services within SOEs.

31:43You may have heard that at ArcGIS Server 10.1, all map services behind the scenes, they use the MSD...

31:52...or map service definition file that you might have been introduced to in 10.0 or 9.3.1.

31:58So inside of your SOEs, you should avoid working with a map document or an MXD directly.

32:04Instead, you want to work with the ArcObjects that are associated with map server.

32:09So let me...hopefully this link will work.

32:18I'm going to try to open the carto object model PDF.

32:20There's many pages in this PDF, and most of the objects in that object model have to do with the map document.

32:29So there's ones like IMap, ILayer.

32:32There's objects that have to do with the page layout and marginalia that's in a map document.

32:38All that stuff you should avoid, because it's...you will not be able to get to that information through your SOE.

32:45A map service is only based on the information inside that MSD, or map service definition file.

32:51So you will not be able to get to that.

32:55Maybe we won't have success opening this, but I will tell you, I think it's page 6 of that object model.

33:00You will see a bunch of objects related to map server, and those are the ones that you are able to use.

33:07There's a special interface called IMapServer data access that you may use frequently.

33:11This actually helps you to get at underlying data behind the MSD.

33:16There is a method on there, GetDataSource, and this will return you either IFeatureClass, IRaster, or ITable.

33:24And this is sufficient for getting at a lot of the underlying data.

33:29You might wonder about other data types.

33:32Some data types, such as, well, I believe, TIN layers or embedding map services within another map service...

33:39...those layers are not supported by the MSD.

33:41So to even to get to this point, you would have to get your map through the analyzers...

33:45...that run when you publish your map document.

33:49So most of your data sources are going to be conventional supported data sources...

33:53...that you can get through IFeatureClass, IRaster, or ITable.

33:58Let me show you how I do this within some code in this spatial query SOE.

34:03So this spatial query runs on that vegetation layer.

34:07And I have some initialization logic in my SOE that just runs one time when I turn the service on or when I start the service.

34:15And that code goes and gets that vegetation layer.

34:20I'm always going to be working with that layer so I don't need to run that code every time I make a call.

34:25So I start out...I have this server object helper that's part of my template, and from there, I can get to the map service.

34:34That's what this IMapServer3 is, that represents the host map service for this SOE.

34:40And then I have other interfaces that work with IMapServer to help me iterate through the layers.

34:46If you haven't used these interfaces, you should become familiar with them, IMapLayerInfo, and then from there...

34:54...I can get to IMapServer data access, and you will see me calling GetDataSource on there...

35:02...and that's how I get to IFeatureClass, and once I have IFeatureClass...

35:05...I can start to go to town and work with that vegetation layer.

35:11As I look at this code, you might notice a few other things.

35:13You can see that I have some log messages that I'm writing.

35:17So SOEs have the ability to write logs, and you can set those at any log level you want.

35:24So I happen to set them at the error level, but if you want to set them at verbose or fine or warning, you can do that.

35:32And this is very helpful for debugging SOEs.

35:36SOEs can be tricky to debug, because you have to attach the debugger to the process that's running the map service.

35:43I found that sometimes adding these log messages can be very helpful...

35:47...if I'm having trouble running the actual Visual Studio debugger.

35:59Let's talk about SOE deployment.

36:02So this has really changed between 10.0 and 10.1.

36:06If you're new to this or you're going to do it at 10.0, I will take a detour in a few minutes and talk about that.

36:12Let me talk about 10.1 first.

36:14The 10.1 SOEs are encapsulated in a .SOE file.

36:19This file is created when you build your project in Visual Studio.

36:23With Java SOEs, the file is also created after you're done, and you run a step to package it up.

36:33You browse to the SOE file in Manager, and that's all it takes to deploy it...

36:37...and then you can go to any map service and enable the SOE on its properties.

36:42If your SOE has advanced properties that the administrator can configure, Manager will detect that...

36:48...and it will provide text boxes for the administrator to type those in.

36:51I'll show an example of that.

36:55So let's take a look at deploying an SOE in Manager.

37:01This is the 10.1 Manager.

37:04I really like this Manager.

37:05You might have noticed in the plenary, they said that it's been rewritten as just HTML and JavaScript application.

37:11It has a real lightweight feel.

37:13There's no separate manager for .NET and Java. It's just one manager.

37:19Oh, you know what, I've already deployed this one.

37:20Well, let me deploy another one.

37:24To deploy an SOE, you just click Add Extension, and then you go browse to that SOE file...

37:29...that was created when you build your project.

37:31It's going to be down inside your project folder down in the Bin directory.

37:36So let me do that for one of the ones in the SDK.

37:48So I'm going to go to this level.

37:50And this is just a good opportunity to show the samples that are shipped at 10.1.

37:54So I'm down in the...let me just go from scratch so you can see where I'm going, because you may want to do this.

38:04And so I'm down in program files X86, because the SDK is installed here.

38:09And if you go into ArcGIS, you'll see Desktop sitting there, but you'll also see the developer kit.

38:15And if you go down into samples, ArcObjects, that's where you have all these Visual Studio projects...

38:21...that have been set there for you to look at.

38:25And all the SOEs are down underneath Server, so they're easy to find. They're all grouped together.

38:31There are some samples that have...show how to do capabilities...

38:35...which is those different groups of methods that you can turn on and off.

38:39There's SOEs that have properties...advanced properties that can be configured by the administrator.

38:45There's the spatial query SOE that we worked with here.

38:48And then there's that Find Near Features SOE that I was showing the schema of earlier on.

38:53So I'll just go ahead and deploy this one.

38:57You'll see that the project is there and all the project files, and within the sample, if you go in the Bin directory...

39:03...we've created the .SOE file for you.

39:06If you just want to practice deployment, you can see what it looks like here.

39:11So I've just browsed to that.

39:12When I click Add, it literally takes just a second or two to deploy the SOE. Okay.

39:20And then I can go back in and look on any service.

39:25[Audience question] [unintelligible]. What is actually in the [unintelligible] part? The zip file?

39:31The zipped up file with all the information that's needed to...

39:34[Audience question] So if you have like dependencies, [unintelligible].

39:40Those can be packaged into that file as well.

39:42It's in the documentation how to do that.

39:46So underneath Capabilities, you can now see these two SOEs that I've deployed here.

39:52Now, this one, this is the one I just deployed, and here's one I had deployed earlier.

39:58Now, this one actually has some properties I could set up.

40:00If the administrator wants to change the name of the layer that it works with instead of that vegetation layer...

40:05...he or she could go type that in right here.

40:08And so Manager kind of gives you a default list of properties that you can change using a text box.

40:12If you want to expand on this and develop your own custom property page...

40:16...there's some examples in the SDK of how you could do that.

40:22I find that in most cases you don't need those additional properties, and if you do, the default page in Manager is very helpful.

40:30Developing those custom property pages can require a lot more development knowledge about Manager, pages, and digits...

40:38...and ArcCatalog property pages.

40:41So I think you want to avoid that route if you can, but if you need it, it's there.

40:47Let's talk about deployment in 10.0.

40:50If you need to do this now, you need to take the SOE.

40:53It won't be packaged into a .SOE file.

40:56That doesn't exist.

40:57You'll have the DLL, so you need to take that DLL and put it on each SOC machine in a place...

41:03...that the ArcGIS Server SOC account can read...

41:08...and then you'll need to register it on each machine with this regasm command.

41:14You also need to do a second registration step, which is to register the SOE with ArcGIS Server itself.

41:20Now, this is done using this method, IServerObject[unintelligible] AddExtensionType.

41:27So you need to run that...you need to write a little console application that runs this method to register your SOE.

41:34The nice thing is that in the SDK samples for 10.0, there is an example of this app.

41:40So let me just show you where you might get that code.

41:44So I am opening the help for 10.0.

41:49And if you open any sample, like let's look at this spatial query sample, you'll go down and you'll see the available code files.

42:00So it comes with...here's a basic SOE code file that you can also get the console application for registering the SOE.

42:09And, ah, that's really small.

42:13I know you guys really like that 8-point Courier font.

42:19So here you can see where I'm going to IServerObjectAdmin2, and then I set some properties on the SOE...

42:24...and then I...it's just registered here.

42:29Here's that AddExtensionType method that they're calling.

42:32The nice thing about this is you can basically copy this code and paste it into your own console app...

42:36...and change the name of the SOE, and you're ready to go.

42:39So you could reuse this registration code on just about any SOE.

42:45But you can see why we tried to make this easier at 10.0, because there's multiple steps for registration.

42:52There is a file you can go to, ServerTypesExt.dat, that's way down in the guts of the server.

42:58If you look at that in Notepad, you can verify if your extension is in the list.

43:02This is just a very simple XML file that shows the SOEs that have been registered with the server.

43:08I can't show it to you here because I have 10.1 on this machine, and things have changed.

43:13But you might want to note that path.

43:16That's a way that I use to troubleshoot registration and to see if it really got recorded with the server.

43:22[Inaudible audience question]

43:26If there is one, you don't want to open it.

43:28It's more...10.1 is more of a black box, and you need to go through Manager...

43:31...or the administration API to work with your available SOE types.

43:38Yeah, in the past, I mean, we kind of talked about opening these DAT files and CFGs and log files in 10.0.

43:45That's less kosher to do in 10.1. You need to stick with the admin API as well as Manager.

43:51And I can take further questions about that after the session if you have them.

43:56The final piece of this is using an SOE in a client application.

44:00So you've prepared this SOE to take in web service requests and also to send back responses...

44:05...and now it's time to be on the other end and receive the response and to do something with it in a client.

44:15So when you're calling one of these SOEs like the REST web service SOE that we just made, you're just making HTTP requests.

44:22You're making RESTful requests.

44:24And each API, whether it be JavaScript, Flex, or Silverlight, has its own ways and preferred methods...

44:30...for making those types of requests and working with the responses.

44:34And I'm, by no means, an expert in all three of them.

44:37I did write a client app for this one that uses JavaScript, and I'll show the JavaScript way.

44:43The different SDK teams for Flex and Silverlight are working on samples for their online help that show how to consume SOEs.

44:50So I encourage you to go to the samples page for your SDK of choice and go look for the SOE samples.

44:58With JavaScript, for example, you're going to use the helper method that's in the API called Esri.request.

45:06So this allows you to set up all your inputs to the SOE using JSON, and then you can execute the request...

45:14...and then get a response object and work with it in your code.

45:19So let me show you some JavaScript code that's here in Notepad.

45:26This is the JavaScript code for that Yellowstone app that I just showed.

45:29And to refresh your memory, I'm just going to demo that one more time just so you can remember what it looks like...

45:35...and the different components that it has.

45:37So it allows me to take a point on click, and then it summarizes the vegetation, and then it's got this table over on the left.

45:44So here's the code for that.

45:47I won't talk about all this code, but I do want to point out the URL of the SOE.

45:53You need to pass that in, and notice how your SOEs are all going to be under this EXTS path, right after your map server...

46:05...and then you're just following the schema of your SOE down into the operation that I defined.

46:09So I defined one operation on that SOE called spatial query, and that's how I get the URL.

46:15If you're in doubt about how to do this, you should go to the services directory...

46:19...and you can drill down and take a look at the URL in the address bar.

46:25You can even test out your SOE, and this is very helpful when you're developing.

46:31So I'm going to return this response as JSON, and you can see that I get a bunch of rings back...

46:36...that are to construct those vegetation polygons.

46:41And you want to understand how these are structured because you're going to have to take them in in JavaScript...

46:45...and start doing something with them.

46:47At the end of this, after all that geometry, I get back some named value pairs that have the different vegetation types...

46:55...and the amount of area covered by those.

46:57So I will also need to do something with this part of the response.

47:04So back in Notepad, I'm setting up...I set up this variable called content, and this has all of my input parameters.

47:11So I need to provide a location.

47:13I just get the x and y from the clicked point, so I handle that click event up here farther up.

47:22And then I also pull in a distance right out of the text box.

47:25And when I've got that, I've got all the inputs I need to call this method.

47:29So then I use Esri Request.

47:31It's going to want the URL of my SOE.

47:34It's going to want that content variable that has all of my input parameters, and then that's all I need.

47:42I can define some callback functions that work with the response.

47:47In my case, I've written two functions, one of them to draw the geometries, that's down here...

47:53...and I've written another function that takes those named value pairs of vegetation types and puts them in the grid.

48:00So in the handler function that draws the geometries, I set up some polygon fill symbols, and I read through those rings...

48:10...and I just add them to the polygons, and then I draw them on the map.

48:13I just put them right into the map's graphics layer.

48:17With the named value pairs, I just put those into a Dojo grid.

48:21Notice that this doesn't take very much code at all.

48:24I actually, when I serialized my response, I did it in such a way that the JSON structure fit right into that Dojo grid...

48:34...or right into the structure that the Dojo grid was expecting.

48:36So this is where it's helpful to maybe have a little bit of knowledge of what types of clients will consume your SOE...

48:42...and then you can prepare your responses in that format that it will expect.

48:57If you need to get more help on SOEs or you're going to go attempt this after this session...

49:03...I encourage you to go back and review the recording of this session.

49:06I believe all the Dev Summit sessions are recorded.

49:08That's what they've done in years past.

49:10So this...you could look for this showing up on the Esri resource center website.

49:16If you can't find this one right away, you can go to last year's, and some of the demos are very similar...

49:21...but they were...there it's completely 10.0-centric.

49:24So that may be helpful.

49:27Also, I showed you where you can find the SOE doc in the ArcObjects SDK.

49:32Let me just go back to that briefly, and point out some of the things that are in that doc.

49:40If you're wondering how to get there, you'll just go to the resource center, and you need to go into the developer SDKs.

49:52So your destination is the .NET ArcObjects SDK.

49:56And then from there, you can drill down into the concepts, and there's a section about developing with ArcGIS Server...

50:06...and you can learn about server object extensions there.

50:09I know I'm going pretty fast on that, but the help in here is actually pretty good if you search for server object extension help.

50:16When you get there, there's different sections for working with REST and SOAP...

50:21...and also some of the tips that I talked about with working with map services are well documented in the help...

50:27...and then you'll see all of those samples that I mentioned before.

50:38If you want to download some of today's demos, you can go to these links.

50:43These are just shortcuts to some of the SOEs that I showed.

50:46The SOE, that dynamic segmentation SOE that places the mile markers, all that code is available for you online to take a look at.

50:54It might be helpful if you want to view one that's a little more advanced than some of the ones in the SDK.

51:01And, yeah, that's it. We ended a little bit early for questions.

51:08Ajit, I'd like to invite you to just come on up here with me.

51:11I'd like to introduce Ajit Dharmik. He's a lead product engineer for SOEs, and he's here to help me out.

51:17If I have to run to that other session I have to give, Ajit will help you out with your questions as well.

51:22So go ahead and raise your hands, and, you know, you can ask whatever's been on your mind.

51:27Don, go ahead.

51:29[Audience question] Is the documentation for 10.1 available yet? I know that, I think, we were all invited to be in prerelease.

51:35Oh, yeah. Great question. So let me show that.

51:37I actually have that open.

51:41Well, let me just show you from scratch.

51:43So if you go to the beta site, this is no longer...this no longer requires a user name and password.

51:48For a long time it did, but it's open to the public now.

51:51So you can to go resources beta at ArcGIS.com, and you can go read the 10.1 documentation.

51:56Now, it's going to be the prerelease documentation, so some items in this may change between now and final...

52:02...but it's better than having nothing, and it's a good way to prepare for 10.1, especially migration...

52:08...which is going to be big with ArcGIS Server.

52:12So if you click Library, you'll see down here the help for all the different SDKs, and including the .NET SDK.

52:21The Java one is still in progress. We're working on it.

52:25If you go to Developing with ArcGIS, you can drill down in the same manner to Developing with ArcGIS Server...

52:31...and then there's the SOE help there.

52:34Again, this is prerelease help. There's some quirkiness with this in areas where we need to fill in.

52:39However, it will reflect some of the new things with SOE deployment and other 10.1 parts.