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: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: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: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: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: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: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: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.
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: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: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.
Extending ArcGIS 10.1 for Server Services
Sterling Quinn explains how to extend ArcGIS for Server with new services.
- Recorded: Mar 28th, 2012
- Runtime: 52:51
- Views: 1342
- Published: Apr 23rd, 2012
- Night Mode (Off)Automatically dim the web site while the video is playing. A few seconds after you start watching the video and stop moving your mouse, your screen will dim. You can auto save this option if you login.
- HTML5 Video (Off) Play videos using HTML5 Video instead of flash. A modern web browser is required to view videos using HTML5.