by
Marc Moore
| Jul 10, 2012
Adding a new project to a Visual Studio solution is easy; however, there is a little more to getting a new ESI Services project up and running than simply creating it. First, open Visual Studio and open the ESI Services solution.
To add a new project, right-click the Solution node in Solution Explorer and choose Add, New Project. Then select WCF Rest Service Application from the dialog and name your project:
Visual Studio will create the default WCF Rest project in the solution:
Customizing Your Service
Since you probably want your service to be called something other than Service1, rename this file as needed and, if prompted, answer Yes to the following dialog:
Alternately, you may have to rename your service’s class manually.
NOTE: The ESI standard is to store the service classes in a folder named “Service”.
Next, edit the Global.asax.cs file and "true-up” your service route registration with your new service name:
The first parameter highlighted above is the routePrefix, which will be part of the URL your service’s callers will reference; therefore, make sure it’s both human and HTTP-friendly. As you can see, it does not have to be the same as your service’s class name. We’ll go with a routePrefix of “Benefits” for the rest of this example.
Next, using the default code as a guide, edit your service class so that it is only exposing the methods you want exposed.
Consider the following:
The UriTemplate parameter to the WebGet attribute maps URL fragments and querystring parameter names to formal method names/parameters.
Given that the Global class has a routePrefix of “Benefits”, we could reference the sample method using the URL “server/Benefits/CurrentCoverage?uin=111001111”.
Now, as you might guess, the SampleItem DTO referenced above is created by default and you’ll obviously want to change your output to be domain-specific as well.
NOTE: One thing to be aware of in this process is that the EsiServices.Framework library offers a some helpful base classes and interfaces to ensure that your XML/JSON output is compatible with other ESI Services projects. A complete discussion of this library is outside the scope of this article; see the TrainTraqRest project for a reference implementation.
A more complete example of a service’s method might be:
Once you've got an approximation of your services’ output in place, it’s time to run your service and it it with a request in order to make sure everything is working as expected. Do this as soon as possible in the process of starting a new project to ensure that you don’t get too far down the wrong road in the event you make a mistake.
Testing Your Service
It is easy enough to run your new web service on your development machine and test it out. One little trick that helps is to ensure that your service is always running (and listening) on the same port. To do this, right-click your project in VS’ Solution Explorer and choose Properties. Then click the Web tab on the properties sheet.
You may have to scroll down a bit to see the Servers section on the Web tab:
In the ESI Services project, we’ve been using ports 1234n, so browse around the solution until you find a port in that range that’s available and set your project to start the Visual Studio Development Server listening on it.
Once this is done you can press F5 to start VS’ debugger or Control-F5 to start your project without debugging. Either way, it will be listening on the port you specified, waiting for an HTTP request to come in that matches the route/URL format specified in your project’s service. To test, you can point a web browser to the URL your service supports or use Fiddler.
In this example, if Firefox is pointed to http://localhost:12348/Benefits/CurrentCoverage?uin=123001234, this is the result, which is what is expected given the code above:
Configuring Your Service
It’s great to be able to compile, run, and test your service on your development machine, but eventually it needs to be deployed to the test server for integration testing, etc. To do this, you’ll first have to create the appropriate solution and project configurations for your service project. When this is done you can create a build definition that references your new solution configuration.
The Debug Configuration
First, ensure that your new project is being built in the Debug configuration. It probably is; otherwise your testing would not have worked!
If you see your project, make sure it’s set to do a Debug build and that the Build checkbox is on.
Fixing Past Mistakes
The second thing to know about the ESI Services configurations is that by adding a new project to the solution, you have already created a problem for all of the existing projects. That’s because VS will have added your new project to the “to build” list for all existing solution configurations, including those targeting a single ESI Services project.
For example, consider the AuthenticationServices_DEV build below:
The iBenefits service should not be built during the AuthenticationServices build!!!
If we looked at each configuration in the solution, we would see that iBenefitsRest was added to each and every one of them. Ergo, you must remove your service from every solution configuration to which it does not apply; i.e., all of them except Debug.
Adding New Configurations
Adding new configurations consists of two parts: adding solution configurations and adding project configurations. To begin with, use the Configuration Manager to add a new solution configuration:
Then name your solution configuration appropriately.
NOTE: Don’t check the “Create new…” checkbox as it will create unnecessary project configurations throughout the solution.
Your new solution configuration will come up looking something like this:
Unfortunately, this is not close to what it should be. Make the necessary changes to the Configuration and Build columns until it looks like this:
1) Traditionally we’ve set the unbuilt projects to a Debug configuration.
2) We’re building the Framework project so it’s always up-to-date.
3) We next need to add a Project configuration for our web services project.
To add a Project configuration to our solution, choose “New…” from the project Configuration dropdown:
Then name your project configuration the same as your solution configuration (unless there is a compelling reason to vary these names).
Repeat this process for the TRUNK, TRAINING, and PROD configurations. When creating these solution configurations, you can you use the “Copy settings from…” option to copy the configuration from the DEV configuration to save a little time.
When you’ve completed all of the configurations for your project, go to your web.config, right-click on it, and choose Add Config Transforms to create a new web.yourconfiguration.config for each project configuration you added during the steps above:
Once these files have been created, edit them to include the necessary configuration values, including connection strings, application settings, etc.
Deploying Your Service
Once your solution and projects configurations have been created, it’s (finally) time to create your build definition. At this point in the solution’s life cycle, it is probably simplest to clone an existing build that’s similar to the one you want.
NOTE: To clone a build, you must have the TFS Power Tools installed.
To clone a build, go to Team Explorer in Visual Studio, navigate into your TFS project, open the Builds node, right-click on the build you want to copy from, and choose Clone Build Definition.
If your source build was named “My Build”, you will see a new build definition named “Copy of My Build.” There is no rename function for a build definition; to rename the new build you must edit it, which you would do anyway to set the project-specific properties of your new build.
To edit a build definition, right-click on it and choose Edit Build Definition.
Rename your build on the General tab:
Check your build schedule on the Trigger tab:
Check your source code folder on the Workspace tab:
The Process tab is where you’ll actually do the work of customizing your build. Under 1. Required, expand the “Items to Build” element and set your Configurations to Build and Projects to Build settings per your solution/configuration:
Note that the Configuration to Build is a solution configuration, not a project configuration, but if you named them the same, it doesn’t matter.
Under 4. Esi Arguments, set the Prior build dependency field only if you are creating a build definition for a projection release.
Under 5. Esi Database Arguments, ensure that the Execute the Deploy target on the DB Project setting is False.
Under 6. Esi Deployment and Configuration, set the Path to startup application value to the name of your web services project:
Under 8. Esi Web Arguments, set the Target App Location to the UNC path where your new project will be deployed by this particular build definition and set the Web Deployment Configuration to the name of the project configuration to build (again, if the solution and project configurations are named the same, that is a good thing):
Save the build definition and repeat for each deployment type (Development, Trunk, Training, Production Candidate, and Production Release).
Conclusion
Adding a new project to the ESI Services solution is not like rolling out of bed in the morning, but hopefully the idea is less intimidating now that the process has been explained.