DTaylor's Blog

SharePoint 2010 Service Application Load Balancer

2011-02-23T23:34:40Z

I’ve recently been asked some questions about the internal load balancer for service applications in SharePoint 2010, which I’ll summarize here.

What is the Service Application Load Balancer?

In order to simplify installation of multi-machine server farms, SharePoint provides a basic load balancer that can round-robin requests to Web service applications.

This provides load balancing and fault-tolerance out-of-the-box for SharePoint service applications without requiring the administrator to be familiar with the intricacies of external load balancing solutions.

If a deployment requires more advanced load balancing or fault tolerance capabilities, an administrator can opt to use an external load balancer.

How does it work?

A Service Application Proxy typically requests an endpoint for a connected Service Application from the load balancer, which is a software component that executes in the same process and application domain as the proxy.

The load balancer maintains a complete list of available endpoints for each Service Application in a cache, and simply returns the next available endpoint to the proxy in a round-robin fashion.

How does it maintain the list of available service application endpoints?

For communication with service applications that are local to a SharePoint server farm, the load balancer looks into the configuration database to discover the available endpoints for a service application.

In this case, the endpoint cache is updated whenever the list of available service application endpoints in the local configuration database changes. The delay in updating the cache is typically less than 1 minute.

For communication with service applications in a remote server farm (i.e., federated services), the load balancer uses the Topology web service (aka, “Application Discovery and Load Balancer Service”) to discover the available endpoints for a service application.

In this case, the list of service application endpoints is periodically retrieved from the Topology web service on the remote farm and copied into the local configuration database as an intermediate cache.

This periodic retrieval is performed by the “Application Addresses Refresh” timer job. By default, this timer job executes every 15 minutes.

How does it handle failures?

The Service Application Proxy may report an endpoint failure to the load balancer, in which case the load balancer will remove the specified endpoint from the round-robin rotation for some period of time.

By default, this period is 10 minutes (configurable using the "BadListPeriod” parameter of the Set-SPTopologyServiceApplicationProxy Cmdlet).

If only one endpoint remains, it will not be removed from the rotation, even if a proxy reports a failure for that endpoint.

Is the Topology Web service a single point of failure for the load balancer?

No. The Topology web service application proxy is “self-balancing”. In other words, it uses the same round-robin load balancing algorithm to provide fault tolerance for itself.

When an administrator creates a connection to a remote (federated) service application, the connection information includes one of the Topology web service application endpoints (selected at random) from the remote server farm. I’ll call this the “bootstrap” node.

The bootstrap node is used to query the complete list of Topology web service application endpoints, which are then cached in the local SharePoint configuration database and used to round-robin all future requests to the Topology web service application.

This cached list of Topology web service application endpoints is then updated periodically just like any other federated service application.

So, the bootstrap node is only needed one time when an administrator creates a new connection (Service Application Proxy) to a remote service application.

What are the limitations of the load balancer?

There is an extreme case where connectivity to a federated service farm may be lost by replacing all of the servers in the remote farm within a single cache refresh interval (i.e., before the “Application Addresses Refresh” timer job can execute).

To hit this case, you would need to bring down all of the servers hosting the Topology web service application in the service farm at once, and after they are all down, replace them all with servers that have different addresses, essentially moving the entire farm to a new set of servers at once rather than gradually over time.

In this case, none of the Topology web services endpoints cached by the client farm would be valid, and the client could would not be able to acquire the all-new list of endpoints (because it needs at least one valid endpoint to query the list of new endpoints).

To avoid this situation, at least one of the Topology web servers in the service farm should be maintained long enough for client farms to update their cache with at least one of the new Topology web service endpoints (at which point the old server can safely be removed). Alternatively, give at least one of the new servers the same name as one of the servers being replaced.

Another limitation of the Service Application load balancer is that the list of available endpoints is maintained separately in the application domain of each caller, and there is no coordination between callers.

This means that each proxy must independently discover that an endpoint is unavailable for some reason, which may translate to one failure per caller application domain (e.g., client application pool process) when a given server goes down unexpectedly.

This also means that it is theoretically possible that some clients may achieve lock-step and send requests to the same servers in succession, thus achieving fault tolerance but not the most effective load balancing.

Calculator Service Source Code

2010-06-11T09:52:03Z

By request, see the attached file for an early look at the source code for the Calculator Service as a Visual Studio 2010 project.

This is a work in progress. Some features are not yet implemented, and I haven’t yet explained some of the implemented features. Use at your own risk, no warranties implied, etc.

Note that I’ve found that an iisreset is usually required after retracting and before re-deploying the solution.

Enjoy!

CalculatorService.zip

SharePoint Calculator Service Part 10 – Service Client

2010-06-08T01:37:30Z

So far, we’ve been covering the service side of our Calculator service. We have a working service application that can be deployed and managed in a SharePoint server farm.

In this article, we’ll switch focus to the client side. Remember that SharePoint service applications live in the middle-tier, so our “client” is actually another server—typically, a Web Front End server.

For example, our client may be a web page or a web part that renders a calculator user interface for presentation in a browser.

If you need a refresher on the various moving parts of a service application, you can refer to my previous post on Service Application Topologies.

Service Proxy and Service Application Proxy

The Service Proxy (SPServiceProxy) and Service Application Proxy (SPServiceApplicationProxy) objects represent the client components that communicate with a service.

They are logically the client-side equivalents of the SPService and SPServiceApplication.

In other words, in the same way that the SPService represents a service that has been registered in a SharePoint server farm, an SPServiceProxy represents a service client that has been registered in a SharePoint server farm. The SPServiceProxy represents the capability to connect to some SPService.

Similarly, an SPServiceApplication represents a logical endpoint of a service in a SharePoint server farm, and a SPServiceApplicationProxy represents a connection to that logical endpoint.

And, just as we have specialized SPIisWebService and SPIisWebServiceApplication classes for web services, we have specialized classes for web service clients: SPIisWebServiceProxy and SPIisWebServiceApplicationProxy.

We will derive classes from the abstract SPIisWebServiceProxy and SPIisWebServiceApplicationProxy classes and register them in the SharePoint configuration database in order to deeply integrate the client with the SharePoint administration experience and runtime.

So let’s do it!

CalculatorServiceProxy

First, we’ll create our service proxy class:

internal sealed class CalculatorServiceProxy : SPIisWebServiceProxy
{
internal CalculatorServiceProxy(
SPFarm farm)
: base(farm)
{
}
}

This is the class that we’ll register in the configuration database in order to tell SharePoint that our client classes are installed and ready to use.

CalculatorServiceApplicationProxy

Next, we’ll create our service application proxy class:

internal sealed class CalculatorServiceApplicationProxy : SPIisWebServiceApplicationProxy
{
[Persisted]
private SPServiceLoadBalancer loadBalancer;
internal CalculatorServiceApplicationProxy(
string name,
CalculatorServiceProxy serviceProxy,
Uri serviceApplicationAddress)
: base(name, serviceProxy, serviceApplicationAddress)
{
// Create a new round-robin load balancer
this.loadBalancer = new SPRoundRobinServiceLoadBalancer(serviceApplicationAddress);
}
public override void Provision()
{
// Provision the load balancer
this.loadBalancer.Provision();
base.Provision();
}
public override void Unprovision(
bool deleteData)
{
// Unprovision the load balancer
this.loadBalancer.Unprovision();
base.Unprovision(deleteData);
}
internal SPServiceLoadBalancer LoadBalancer
{
get
{
return this.loadBalancer;
}
}
internal Configuration Configuration
{
get
{
return OpenClientConfiguration(SPUtility.GetGenericSetupPath(
@"WebClients\Sample\Calculator"));
}
}
}

This is the class that will be created on demand when an administrator chooses to create a connection to a new service application.

The class is constructed like any other configuration object, with one additional parameter: serviceApplicationAddress (lines 9-10).

Service Application Address and Load Balancer

The serviceApplicationAddress property identifies the service application to which the service application proxy will connect. Specifically, it must match the value of the CalculatorServiceApplication.Uri property.

If you’re really observant, you may have noted that a service application actually has many addresses—one per service instance. Remember that a service application may be hosted on any number of servers, and the host on each server is called the service instance.

For example, if our service application is hosted on two machines, server1 and server2, it will have two addresses: http://server1:32843/…/calculator.svc and http://server2:32843/…/calculator.svc.

So how can a service application have a single address in the object model?

The answer is that the service application address is a logical service address that can be resolved into many physical addresses at runtime—one physical address per service instance.

The Service Application Framework takes care of this detail for us by providing the SPRoundRobinServiceLoadBalancer class and the supporting Topology service. (I’ll save the details of how this works for a future post.)

For now, suffice it to say that we can simply construct (line 13) and provision/unprovision (lines 16-31) the load balancer component with our service application proxy and get this functionality.

We’ll also expose the load balancer object as an internal property for later use by our client runtime (lines 33-39).

Client Configuration

We’ll be using WCF to connect to our service application, and as a best practice we’ll keep the client settings in a configuration file.

This is the client-side equivalent of having service settings in a web.config file. However, unlike the service side, our client assembly dll can be loaded by any arbitrary executable.

This is a little tricky for the .NET configuration system, which supports configuration only at the exe scope and doesn’t support per-dll configuration. There simply isn’t a place we can drop a config file where it will be loaded by the .NET configuration system and recognized by WCF regardless of what exe (w3wp.exe, powershell.exe, someapp.exe, etc) loads our client dll.

To solve this problem, we use the SharePoint OpenClientConfiguration helper method to reference a file named “client.config” in a well-known location.

By convention, our deployment solution will drop the client.config file under the “WebClients” folder of the SharePoint installation. We separate our client.config file from all other config files by creating a subfolder (“Sample\Calculator”).

Calculator Client (Runtime)

Next, we’ll implement our calculator client. This is the public-facing class that clients, such as web parts, will use to interact with our service.

public sealed class CalculatorClient
{
private SPServiceContext serviceContext;
// Used to cache the client channel factory
private static ChannelFactory<ICalculatorServiceContract> s_ChannelFactory;
private static object s_ChannelFactoryLock = new object();
public CalculatorClient(
SPServiceContext serviceContext)
{
if (null == serviceContext)
{
throw new ArgumentNullException("serviceContext");
}
this.serviceContext = serviceContext;
}
/// <summary>
/// Client method executed on WFE (front-end), for example, by a web part.
/// </summary>
public int Add(int a, int b)
{
int result = 0;
// Execute the service application method
this.ExecuteOnChannel(
channel => result = channel.Add(a, b));
return result;
}
private delegate void CodeToExecuteOnChannel(
ICalculatorServiceContract channel);
private void ExecuteOnChannel(
CodeToExecuteOnChannel codeBlock)
{
if (null == codeBlock)
{
throw new ArgumentNullException("codeBlock");
}
// Get the default service application proxy from the service context
CalculatorServiceApplicationProxy proxy = (CalculatorServiceApplicationProxy)this.serviceContext.GetDefaultProxy(
typeof(CalculatorServiceApplicationProxy));
if (null == proxy)
{
throw new InvalidOperationException("Calculator service application proxy not found.");
}
SPServiceLoadBalancer loadBalancer = proxy.LoadBalancer;
if (null == loadBalancer)
{
throw new InvalidOperationException("Calculator load balancer not found.");
}
SPServiceLoadBalancerContext loadBalancerContext = loadBalancer.BeginOperation();
try
{
using (new SPServiceContextScope(this.serviceContext))
{
// Get a channel to the service application endpoint
IChannel channel = (IChannel)GetChannel(proxy, loadBalancerContext.EndpointAddress);
try
{
// Execute the delegate
codeBlock((ICalculatorServiceContract)channel);
// Close the channel
channel.Close();
}
finally
{
if (channel.State != CommunicationState.Closed)
{
channel.Abort();
}
}
}
}
catch (EndpointNotFoundException)
{
loadBalancerContext.Status = SPServiceLoadBalancerStatus.Failed;
throw;
}
finally
{
loadBalancerContext.EndOperation();
}
}
private ICalculatorServiceContract GetChannel(
CalculatorServiceApplicationProxy proxy,
Uri address)
{
// Check for a cached channel factory
if (null == s_ChannelFactory)
{
lock (s_ChannelFactoryLock)
{
if (null == s_ChannelFactory)
{
// Get the endpoint configuration name
string endpointConfigurationName = "http";
// Create a channel factory without specifying an endpoint address
// so it can be cached and used for multiple endpoint addresses
s_ChannelFactory = new ConfigurationChannelFactory<ICalculatorServiceContract>(
endpointConfigurationName, proxy.Configuration, null);
// Configure the channel factory for claims-based authentication
s_ChannelFactory.ConfigureCredentials(SPServiceAuthenticationMode.Claims);
}
}
}
return s_ChannelFactory.CreateChannelActingAsLoggedOnUser(new EndpointAddress(address));
}
}

The first thing to note about this class is that it doesn’t subclass any framework classes. This is an intentional decision on my part, because I want this public class to have longevity. If I choose to use some alternate framework down the road or maybe move from a web service to some other type of service, I want to protect my client code from these changes.

So, I have intentionally made all of my framework subclasses internal to my implementation and have only exposed the CalculatorClient class to my consumers.

Note that if my goal was to have the shortest sample code possible I could have merged some of these classes, but in this case I am prioritizing what I consider to be a best practice over code brevity.

SPServiceContext

The one part of the framework that is necessarily exposed by the client is SPServiceContext. SharePoint does require some context in order to be able to invoke a service method, and the SPServiceContext object wraps up all of that context into a a single object.

Technically, this context could be acquired automatically in some cases. For example, the SPServiceContext.Current method is a static method that can acquire the necessary context in certain cases, for example, when executed by a web part.

However, SPServiceContext.Current will return null in other situations, for example, when it cannot automatically detect the necessary context from the PowerShell console or from a timer job.

So, it is not appropriate to use SPServiceContext.Current from general-purpose object model code such as CalculatorClient.

Instead, the caller must provide this context to the object model using whatever SPServiceContext method is appropriate for the execution context, i.e., SPServiceContext.Current for a SharePoint web part or page context, or the SPServiceContextPipeBind object for a PowerShell cmdlet.

I plan to cover more about SPServiceContext in depth in a future article. For now, you can just consider it a “black box” of context that gives SharePoint the runtime context for executing a service request, such as the context necessary for finding the appropriate service application proxy configured by the SharePoint farm administrator.

ExecuteOnChannel

ExecuteOnChannel is a private helper method that I wrote to wrap up all of the steps that are common to every service call. You can pass a delegate as a parameter and the delegate function will be executed on a WCF channel that has authenticated with the service application.

private void ExecuteOnChannel(
CodeToExecuteOnChannel codeBlock)

With some nice C# lambda expression syntax (lines 28-29), the code for calling a service method is fairly readable, and you don’t have the maintenance problems associated with copy-paste.

this.ExecuteOnChannel(channel =>
result = channel.Add(a, b));

The first thing we do in ExecuteOnChannel is lookup our service application proxy (lines 45-51). We use the GetDefaultProxy method on our SPServiceContext object, which knows how to find the proxy that the farm administrator has configured for the given context. More on how this works in a future article.

CalculatorServiceApplicationProxy proxy = (CalculatorServiceApplicationProxy)this.serviceContext.GetDefaultProxy(
typeof(CalculatorServiceApplicationProxy));

From our service application proxy, we get our load balancer object (lines 53-57).

SPServiceLoadBalancer loadBalancer = proxy.LoadBalancer;

Then, we tell the load balancer that we want to begin an operation using the BeginOperation method (line 59).

SPServiceLoadBalancerContext loadBalancerContext = loadBalancer.BeginOperation();

This returns an SPServiceLoadBalancerContext object that we can use to get a service endpoint address using the loadBalancerContext.EndpointAddress property (line 65). Note that this address is a physical endpoint address, in that it identifies a URI to which we can directly send a WCF message.

We also use the load balancer context to report failures to the load balancer (lines 83-87).

catch (EndpointNotFoundException)
{
loadBalancerContext.Status = SPServiceLoadBalancerStatus.Failed;
throw;
}

It is important to note that the consequence of reporting a failure to the load balancer is that the endpoint will temporarily be removed from rotation. In other words, the load balancer will not direct requests to that endpoint for some time.

So, if the service method throws some exception that is expected given the inputs it would not be appropriate to report that exception as a failure to the load balancer, because the endpoint is working fine.

It is only appropriate to report failures that indicate that the endpoint is unavailable or not functioning properly. In our example, if the endpoint cannot be found we report the failure and ensure that future requests will not be sent to this endpoint for some time.

I plan to cover the details of the SPRoundRobinServiceLoadBalancer implementation in a future article, but for now your service client will function correctly by simply following this example.

When the operation completes, we report this to the load balancer in a finally block using the EndOperation method so that, for example, it can track statistics about in-flight operations for its internal load balancing algorithm.

finally
{
loadBalancerContext.EndOperation();
}

I’m going to postpone discussion of the SPServiceContextScope (line 62) for now. It’s not strictly necessary for this example, but it will come into play if we implement a partitioning scheme for hosted deployments in the future. I’m including it for now in case the code gets copy-pasted, since it makes the ExecuteOnChannel method more widely applicable.

That leaves the code to actually acquire the WCF channel, execute the specified code on it, and clean up (lines 64-80). This is pretty standard WCF code, so I won’t go into detail.

GetChannel

The private GetChannel helper method is used by ExecuteOnChannel to acquire a WCF channel.

It is important to note that we cache the WCF channel factory, which is a requirement to achieve great performance. We use a standard double-check lock (lines 99-103) and cache the channel factory in a static variable (lines 6-7).

In order to enable the channel factory to be cached, we do not specify an endpoint address when creating the channel factory. If you recall the earlier discussion on load balancing, this is because each service request may be addressed to a different physical service instance (aka service host).

Instead, we specify the endpoint address at the time the channel is created. So a given WCF channel is effectively bound to a single physical service instance, but each channel may be bound to a different service instance.

As noted earlier in the Client Configuration section of this article, we want the channel factory to get its configuration from our client.config file. So we use the WCF ConfigurationChannelFactory class to create our channel factory using the Configuration object specified by the service application proxy (lines 110-111).

s_ChannelFactory = new ConfigurationChannelFactory<ICalculatorServiceContract>(
endpointConfigurationName, proxy.Configuration, null);

We also specify the endpoint configuration name from our client.config file, which I’ve currently hard-coded to “http” (line 106). More on supporting multiple endpoint addresses in a future article.

Since our service application is configured for claims-based authentication, we use the ConfigureCredentials extension method from the SAF SPChannelFactoryOperations class.

s_ChannelFactory.ConfigureCredentials(SPServiceAuthenticationMode.Claims);

And finally, we create the WCF channel using the CreateChannelActingAsLoggedOnUser extension method from the SAF SPChannelFactoryOperations class, specifying the endpoint address from the load balancer context.

return s_ChannelFactory.CreateChannelActingAsLoggedOnUser(new EndpointAddress(address));

This gives us a WCF channel that authenticates both the executing process and the signed-in user (i.e., using a SAML token that represents the process “acting as” the current user) to the service.

Client.config

Nothing really special here, but I’m including it for completeness. It’s a standard WCF config file with the binding copy-pasted from the service application web.config:

<configuration>
<system.serviceModel>
<client>
<endpoint
name="http"
contract="Sample.Calculator.Client.ICalculatorServiceContract"
binding="customBinding"
bindingConfiguration="CalculatorServiceHttpBinding" />
</client>
<bindings>
<customBinding>
<binding
name="CalculatorServiceHttpBinding">
<security
authenticationMode="IssuedTokenOverTransport"
allowInsecureTransport="true" />
<binaryMessageEncoding>
<readerQuotas
maxStringContentLength="1048576"
maxArrayLength="2097152" />
</binaryMessageEncoding>
<httpTransport
maxReceivedMessageSize="2162688"
authenticationScheme="Anonymous"
useDefaultWebProxy="false" />
</binding>
</customBinding>
</bindings>
</system.serviceModel>
</configuration>

That’s all for now

At this point we have a completely functional service application client, however, we have a little more to do to integrate with the administrator user experience. Next time.

SharePoint Calculator Service Part 9 – Claims Auth

2010-05-13T03:35:36Z

One of the game-changing features of SharePoint 2010 is support for claims-based identities. It opens up a whole new set of exciting scenarios by blowing the doors off of the walled garden of the Active Directory. Well, maybe I exaggerate, but only slightly!

In this article, we’ll modify our Calculator service application to support claims-based authentication (AuthN) and authorization (AuthZ).

About Claims-based Authentication

SharePoint has made a big bet on claims-based authentication in the 2010 release. In fact, it is the only type of authentication explicitly supported by the Service Application Framework.

This decision unifies the authentication model used inside a SharePoint server farm and eliminates the complexities around supporting many different types of authentication.

NOTE: SharePoint 2010 still supports many sign-in authentication options such as Windows authentication, for example, when a user signs-in to a SharePoint site from a browser. What we’re talking about here is authentication between the Web Front End tier and the Application Server tier inside a SharePoint server farm.

I feel like I should draw a picture here:

In this article, we’re specifically talking about the “Claims (only)” arrow connecting the WFE tier to the Application Server tier where our Calculator service application is hosted.

NOTE: It is technically possible to implement your own authentication scheme, but you’ll find that there is no explicit support for this in the Service Application Framework. You’ll end up spending a bunch of time implementing your own authentication and authorization management infrastructure, and your service application will not support the many new scenarios enabled by claims authentication. In short, SharePoint administrators will likely be very unhappy to find this out when they deploy your service.

If you’re interested in more details about some of the scenarios made possible by claims-based authentication, you can read the MSDN documentation or check out the great resources on the SPIdentity blog including three excellent videos linked in this post.

On with the implementation!

First, we need to tell WCF that we want to use claims-based authentication with our service application.

We do that by changing the service binding in our web.config:

web.config

<system.serviceModel>
<services>
<service
name="Sample.Calculator.Service.CalculatorServiceContract">
<endpoint
address=""
contract="Sample.Calculator.Service.ICalculatorServiceContract"
binding="customBinding"
bindingConfiguration="CalculatorServiceHttpBinding" />
</service>
</services>
<bindings>
<customBinding>
<binding
name="CalculatorServiceHttpBinding">
<security
authenticationMode="IssuedTokenOverTransport"
allowInsecureTransport="true" />
<binaryMessageEncoding>
<readerQuotas
maxStringContentLength="1048576"
maxArrayLength="2097152" />
</binaryMessageEncoding>
<httpTransport
maxReceivedMessageSize="2162688"
authenticationScheme="Anonymous"
useDefaultWebProxy="false" />
</binding>
</customBinding>
</bindings>
</system.serviceModel>

The interesting change here is that we specify a custom binding (lines 8, 13-29) with an authentication mode of IssuedTokenOverTransport (line 17).

This tells WCF to require a SAML token (containing claims about the authenticating party) in the security header of any messages sent to the service.

The allowInsecureTransport option is required because we’re using HTTP as our transport (line 24), which means that the SAML token will be sent in plain-text over the wire to the service.

This may be appropriate in scenarios where the physical network is considered secure (e.g., a private back-end LAN connecting WFE and App Server) and performance is the primary consideration.

It’s also appropriate for this article because we haven’t yet covered service application endpoints (something we’ll do in the near future).

We’ll also discuss WCF bindings that are supported and work well for service application scenarios in a future article.

But for now, you can just consider the custom binding to be some magic configuration settings that enable our service to work with claims-based authentication.

Next, we need to turn off IIS authentication, because IIS natively doesn’t know anything about SAML tokens. As far as IIS is concerned, connections to our service will be anonymous. Instead, WCF/WIF will take care of authentication.

We do this in web.config as well:

<system.webServer>
<security>
<authentication>
<anonymousAuthentication enabled="true" />
<windowsAuthentication enabled="false" />
</authentication>
</security>
</system.webServer>

Now, as far as IIS is concerned, we have enabled anonymous authentication.

NOTE: I regret that this last step is necessary, as it should have been the default configuration. It’s just one of those things that slipped through the cracks during the release cycle and unfortunately we’re probably stuck with it now, as a change to the default configuration would be a breaking change.

Configuring the Service Host Factory

Next, we need to implement a service host factory. This is necessary because it is the only WCF extensibility point where we can configure the service host for claims support due to the requirement that the service host be configured before it is opened.

NOTE: If you already have a service host factory, you can continue to use it. Just follow along and insert the serviceHost.Configure method call in your CreateServiceHost override as described below.

To do this, we’ll modify our calculator.svc file to reference a new service host factory class:

calculator.svc

<%@ServiceHost
Language="C#"
Service="Sample.Calculator.Service.CalculatorServiceContract, Sample.Calculator.Service, Version=1.0.0.0, Culture=neutral, PublicKeyToken=d5d38459f57e2f46"
Factory="Sample.Calculator.Service.CalculatorServiceHostFactory, Sample.Calculator.Service, Version=1.0.0.0, Culture=neutral, PublicKeyToken=d5d38459f57e2f46"
%>

Line 4 is the only change from our original WCF service. It simply tells WCF to call our CalculatorServiceHostFactory when creating our service host.

So now we need to implement the service host factory:

CalculatorServiceHostFactory.cs

internal sealed class CalculatorServiceHostFactory : WebServiceHostFactory
{
public override ServiceHostBase CreateServiceHost(
string constructorString,
Uri[] baseAddresses)
{
ServiceHostBase serviceHost = base.CreateServiceHost(constructorString, baseAddresses);
// Configure the service host for claims authentication
serviceHost.Configure(SPServiceAuthenticationMode.Claims);
return serviceHost;
}
}

The interesting code here is the call to serviceHost.Configure (line 10). This is a C# extension method implemented in the Microsoft.SharePoint namespace (specifically, in the SPServiceHostOperations class). Don’t be confused by the extension method syntax. The Configure method is not a WCF method on the ServiceHostBase class. It is a SharePoint method.

This method internally does the following:

1. It configures the service host to support authentication via Windows Identity Foundation (WIF).

2. It configures the service host to use an authorization manager that enforces the service application security policy as configured by an administrator.

3. It attaches a WCF behavior (implemented internally by the Service Application Framework) to the service host that handles an optional ServiceContext SOAP message header. A WCF client can use this header to enable correlation of diagnostic information across machine boundaries, to coerce the server thread locale to match the client request locale, and to support multi-tenancy or partitioning of a service application based on a SharePoint site subscription identifier.

Each of these items deserves more explanation, but that’s for another time. For now, rest assured that the Configure method is doing lots of nice things for your service application.

That’s it!

To summarize, we modified our service binding to support issued token authentication, made a single method call to configure our service host, and our service application magically supports claims-based authentication (AuthN) and authorization (AuthZ).

For example, a farm administrator can now use the Permissions button in the Service Applications Management page to grant or restrict access to our service application:

By default, any identity that has the “Local Farm” claim will have “Full Control” access to the service application:

In effect, this means that any process in the server farm can access the service application. So, services “just work” in a single farm topology by default.

Administrators can customize these permissions to create the advanced topologies I wrote about in a previous post, for example, restricting access to only a specific web application.

Administrators can even use the Publish ribbon button to make the Calculator service application available to clients outside the server farm (“service federation”), and thanks to claims-based authentication, the clients can even be in a different Active Directory domain. In fact, the clients don’t even have to be a member of a Windows domain or have an Active Directory available at all!

As with the Administrators ribbon button that we look at in my last post, service implementers can customize the permissions to provide more granularity than just “Full Control” and enforce these permissions on a per-method basis rather than the basic “all-or-nothing” access enforced by the Connection Permissions settings.

Identity Delegation

Another feature we now have available to our service application is the end-user identity. We can inspect the end-user’s identity (as signed-in on the Web Front End) all the way back in the App Server tier where our service application is executing.

This may seem like an obvious thing, but it wasn’t possible with Windows authentication without a PhD in Kerberos and domain administrator-level access to the Active Directory, because a feature called “delegation” of the user token is required to flow a Windows identity across multiple servers.

Not so with SharePoint claims-based identities. Delegation works out of the box, no PhD required.

We’re not taking advantage of this feature yet, but I’ve got a cool feature planned for the Calculator service that will make good use of it in a future article.

Enjoy!

SharePoint Calculator Service Part 8 – Delegated Administration

2010-05-12T06:15:12Z

In Part 7 of this series, we created a cmdlet to allow an SharePoint farm administrator to easily modify settings of our Calculator service application using PowerShell.

In this article, we’ll add support for delegated administration.

About Delegated Administration

One of the many cool new features of SharePoint 2010 is the ability to grant users the ability to manage a service application without giving them the keys to the entire farm (i.e., without making them a farm administrator).

For example, when a delegated administrator accesses the SharePoint Central Administration site, they see the following:

Notice that the only link available is the “Manage service applications” link.

When a delegated administrator clicks the link with our current Calculator service implementation, they can’t view or manage our service application. They just see a blank list like this:

That’s because our service application doesn’t support delegated administration yet. Let’s fix that.

Implementing Delegated Administration

To add support for delegated administration, we override the AccessibleByDelegatedAdminGroup method in the code-behind for our service application management aspx page. We return true if the current user should have access to the page; otherwise, false.

Not so coincidentally, our service application class has a protected method named CheckAdministrationAccess which will return the appropriate value based on the access granted by a server farm administrator.

So, we just need to hook the AccessibleByDelegatedAdminGroup method of our page up to the CheckAdministrationAccess method of our service application.

First, we implement the AccessibleByDelegatedAdminGroup method:

ManageApplicationPage.aspx.cs

public class ManageApplicationPage : GlobalAdminPageBase
{
protected override bool AccessibleByDelegatedAdminGroup
{
get
{
bool allowed = false;
CalculatorServiceApplication serviceApplication = this.ServiceApplication;
if (null != serviceApplication)
{
allowed = serviceApplication.CheckAdministrationPageAccess();
}
return allowed;
}
}
}

If you remember Part 6 of this series, we already implemented the ServiceApplication property which returns the Calculator service application object that the user wishes to manage from this page.

The AccessibleByDelegatedAdminGroup simply returns the result of calling the CheckAdministrationPageAccess method on the service application (line 12).

Now we just need to implement the CheckAdministrationPageAccess method on our service application:

CalculatorServiceApplication.c

internal sealed class CalculatorServiceApplication : SPIisWebServiceApplication
{
internal bool CheckAdministrationPageAccess()
{
return this.CheckAdministrationAccess(SPCentralAdministrationRights.Read);
}
}

This method returns true if the current user has been granted “Read” administration access to the current service application; otherwise, it returns false.

That’s it!

Not much work, and we’ve enabled a SharePoint server farm administrator to delegate management of our Calculator service application to someone without having to make that person a farm administrator.

This feature may be overkill for our simple Calculator service example, but it is a much-requested feature for complex service applications like Search.

For example, it allows a farm administrator to appoint someone else to have full management control of a Search service application without the risk that this person may accidentally destroy the server farm by clicking the wrong links and changing server farm settings outside the Search service application.

Since it’s so easy to implement, I don’t see any reason why you shouldn’t support this scenario for your service applications.

How to use it

To add a delegated administrator for our Calculator service application, you must first be logged in to the SharePoint Central Administration site as a server farm administrator.

Select a Calculator service application from the Service Applications Management page in the Central Administration site and click the Administrators button in the ribbon:

Then, grant the desired delegated administrator(s) access to the service application:

NOTE: You may be wondering about the “Full Control” permission and whether or not other permissions are possible. The answer is yes, service implementers may customize the rights available to delegated administrators and enforce those rights in their service applications. That’s an advanced topic that we’ll cover in a future article.

After clicking OK, when the delegated administrator navigates to the Service Applications Management page, they’ll see something like the following:

Note that only the “Manage” ribbon button is enabled. All of the other ribbon buttons are disabled because they are actions only available to server farm administrators.

Clicking the “Manage” button will allow the delegated administrator to manage the settings available for the Calculator service application:

And that’s how delegated administration works. Enjoy!

SharePoint Calculator Service Part 7 – Custom Admin Setting PowerShell

2010-05-11T06:29:24Z

In Part 6 of this series, we created a custom setting for our Calculator service application and a web page to manage the setting from the SharePoint Central Administration web site.

In this article, we’ll create the accompanying PowerShell cmdlet so the setting can be scripted.

The proposed syntax of the new cmdlet is:

Set-CalculatorServiceApplication [-Identity] <SPServiceApplicationPipeBind> -Precision <Int32>

Create the Cmdlet

First, we’ll subclass SPCmdlet:

[Cmdlet(VerbsCommon.Set, "CalculatorServiceApplication", SupportsShouldProcess = true)]
[SPCmdlet(RequireLocalFarmExist = true, RequireUserFarmAdmin = true)]
internal sealed class SetCalculatorServiceApplication : SPCmdlet
{
[Parameter(Mandatory = true, Position = 0, ValueFromPipeline = true)]
[ValidateNotNull]
public SPServiceApplicationPipeBind Identity
{
get;
set;
}
[Parameter(Mandatory = true)]
[ValidateRange(1, 20)]
public int Precision
{
get;
set;
}
protected override void InternalProcessRecord()
{
// Read the service application identity from the pipebind parameter
CalculatorServiceApplication serviceApplication = this.Identity.Read() as CalculatorServiceApplication;
// Check for a valid service application
if (null == serviceApplication)
{
// Write an error
WriteError(
new InvalidOperationException("Calculator service application not found."),
ErrorCategory.InvalidArgument,
this.Identity);
// Skip this record
SkipProcessCurrentRecord();
}
if (ShouldProcess(serviceApplication.Name))
{
// Modify service application settings
serviceApplication.Precision = this.Precision;
// Persiste the service application object
serviceApplication.Update();
// Write the object to the pipeline
WriteObject(serviceApplication);
}
}
}

This is very similar to the New-CalculatorServiceApplication cmdlet we created in Part 5 of this series, so feel free to review that article.

The interesting code here is the Identity property of type SPServiceApplicationPipeBind (lines 5-11), which allows a instance of our Calculator service application to be passed to our cmdlet. The parameter can either be a Guid identifier (as a string on the command line), a PowerShell variable that references an SPServiceApplication object, or an SPServiceApplication object on the pipeline.

For example, given the following:

PS C:\> Get-SPServiceApplication

DisplayName TypeName Id
----------- -------- --
Security Token Se... Security Token Se... 7d88501a-a3e0-4289-aa96-62048803b1fb
Application Disco... Application Disco... e79b6d9d-f7a0-4ac9-bdda-a9df8dc5e138
WSS_UsageApplication Usage and Health ... 7f75ee92-3930-4496-b1e2-743829f74cf4
My Calculator Ser... Sample.Calculator... 2b07ed87-e9af-40a2-8a59-8d6b746bb19b

We can then update the Precision setting of the above Calculator service application using any of the following commands:

PS C:\> Set-CalculatorServiceApplication 2b07ed87-e9af-40a2-8a59-8d6b746bb19b -Precision 3

PS C:\> Get-SPServiceApplication 2b07ed87-e9af-40a2-8a59-8d6b746bb19b | Set-CalculatorServiceApplication -Precision 3

PS C:\> $app = Get-SPServiceApplication 2b07ed87-e9af-40a2-8a59-8d6b746bb19b
PS C:\> Set-CalculatorServiceApplication $app -Precision 3

Register the Cmdlet

Don’t forget to register the cmdlet (see Part 5 for details on the registration process):

<ps:Cmdlet>
<ps:VerbName>Set-CalculatorServiceApplication</ps:VerbName>
<ps:ClassName>Sample.Calculator.Service.PowerShell.SetCalculatorServiceApplication</ps:ClassName>
<ps:HelpFile>Sample.Calculator.Service.PowerShell.dll-help.xml</ps:HelpFile>
</ps:Cmdlet>

That’s it!

Administrators can now use our handy Set-CalculatorServiceApplication cmdlet to script the Precision setting.

SharePoint Calculator Service Part 6 – Custom Admin Setting

2010-05-10T21:24:35Z

In Part 5 of this series, we created a PowerShell cmdlet to enable SharePoint administrators to script deployment of our Calculator service application in a server farm.

In this article, we’ll create a custom setting that administrators can use to modify the behavior of our service application.

Specifically, we’ll create a new Precision setting, which is defined as the number of significant digits that are used to represent the result of a calculation.

Create the setting

To do this, we’ll first add the setting to our CalculatorServiceApplication class.

You might think that it would be challenging to create a setting that can be managed from a single location and made available to all servers in a server farm via a distributed multi-tier cache, but that’s actually the easiest part thanks to the SharePoint configuration object model:

internal sealed class CalculatorServiceApplication : SPIisWebServiceApplication
{
[Persisted]
private int precision;
public int Precision
{
get
{
return this.precision;
}
set
{
if ((value < 1) || (value > 20))
{
throw new ArgumentOutOfRangeException("value");
}
this.precision = value;
}
}
}

The precision field (line 4) represents the current precision setting for the service application, and the Precision property (lines 6-22) implement a public property to get and set the field value.

The key to integrating with the SharePoint configuration object model is the [Persisted] attribute (line 3). This attribute instructs SharePoint to persist the field value in the SharePoint configuration database when the Update method is called, and to deserialize it when the class is read from the configuration database.

That’s all it takes for the field value to be available on all machines in the server farm and automatically cached on demand for runtime access!

NOTE: The Service Application Framework does not require service application settings to be stored in the SharePoint configuration database using the [Persisted] attribute described above. For example, if a service has an existing mechanism for storing settings, then that would be fine to use instead. However, you may find this persistence mechanism convenient in many cases.

Use the setting

Next, we’ll read this value at runtime and apply it to the result of our Add method:

internal sealed class CalculatorServiceContract : ICalculatorServiceContract
{
public int Add(int a, int b)
{
return RoundToPrecision(a + b);
}
private CalculatorServiceApplication ServiceApplication
{
get
{
// Lookup executing service application in config db cache
return (CalculatorServiceApplication)SPIisWebServiceApplication.Current;
}
}
private int RoundToPrecision(int value)
{
// Get the current precision setting from the service application configuration
int precision = this.ServiceApplication.Precision;
// Quick-and-dirty round to specified precision
return int.Parse(value.ToString("G" + precision.ToString()), System.Globalization.NumberStyles.Any);
}
}

First, we add a ServiceApplication property to look up and return the executing Calculator service application (lines 8-15).

NOTE: If we had implemented our contract as methods on the CalculatorServiceApplication, this step would be unnecessary, i.e., we could just use “this” to reference the current service application. However, in this example we’re assuming that we’re integrating an existing WCF service contract implementation with SharePoint.

Then, we get the precision setting from our service application using this.ServiceApplication.Precision (line 20) and use it to round our result (line 23).

NOTE: I couldn’t find a nice math function to round a number to an arbitrary precision, so I ended up converting the int to a string formatted to display the given precision and then converting the formatted string back to an int. Not something I’d recommend for production code.

It is important to note that the ServiceApplication lookup (line 13) and the Precision setting (line 2) objects are cached in memory by the SharePoint configuration object model and should not be cached again. This is a common implementation mistake and results in stale setting values. The reason is that SharePoint is smart about invalidating the cache and keeping it fresh when administrators make changes to settings, even from other machines in the server farm. If you cache the result of a lookup, the object will become stale and your application won’t see changes made by administrators until your service host process is recycled.

So, simply follow the pattern above and lookup the setting on every access to ensure that you are reading the most recent value.

Manage the setting

Now let’s provide a way for the administrator to configure the setting. To do this, we’ll integrate with the “Manage” ribbon button on the Service Applications management page:

First, we’ll create a management ASPX page:

ManageApplication.aspx

<asp:content contentplaceholderid="PlaceHolderMain" runat="server">
<table border="0" cellspacing="0" cellpadding="0" width="100%" class="ms-propertysheet">
<wssuc:InputFormSection
Title="Arithmetic Precision"
runat="server">
<Template_Description>
<wssawc:EncodedLiteral runat="server" text="Arithmetic precision is the number of significant digits that are used to represent the result of a calculation." EncodeMethod='HtmlEncodeAllowSimpleTextFormatting'/>
</Template_Description>
<Template_InputFormControls>
<wssuc:InputFormControl runat="server">
<Template_LabelText>
<wssawc:EncodedLiteral text="Precision:" EncodeMethod="HtmlEncode" runat="server"/>
</Template_LabelText>
<Template_control>
<wssawc:InputFormTextBox id="PrecisionTextBox" name="PrecisionTextBox" title="Precision" MaxLength="2" Width="50" class="ms-input" runat="server" />
<wssawc:EncodedLiteral text="digits" EncodeMethod="HtmlEncode" runat="server" />
<wssawc:InputFormRangeValidator
id="PrecisionValidator"
Type="Integer"
MinimumValue="1"
MaximumValue="20"
ControlToValidate="PrecisionTextBox"
ErrorMessage="Specify an integer value in the range 1..20"
runat="server" />
</Template_control>
</wssuc:InputFormControl>
</Template_InputFormControls>
</wssuc:InputFormSection>
<wssuc:ButtonSection runat="server">
<Template_Buttons>
<asp:Button id="OkButton" OnClick="OkButton_Click" UseSubmitBehavior="false" Text="OK" class="ms-ButtonHeightWidth" runat="server" />
</Template_Buttons>
</wssuc:ButtonSection>
</table>
</asp:content>

NOTE: I removed a bunch of standard page template goo for readability.

Then, the code-behind:

ManageApplication.aspx.cs

[PermissionSet(SecurityAction.Demand, Name = "FullTrust")]
[PermissionSet(SecurityAction.InheritanceDemand, Name = "FullTrust")]
public class ManageApplicationPage : GlobalAdminPageBase
{
protected TextBox PrecisionTextBox;
protected override void OnLoad(EventArgs e)
{
base.OnLoad(e);
if (!Page.IsPostBack)
{
CalculatorServiceApplication serviceApplication = this.ServiceApplication;
if (null == serviceApplication)
{
throw new InvalidOperationException("Service application not found.");
}
// Initialize controls from service application
this.PrecisionTextBox.Text = serviceApplication.Precision.ToString();
}
}
private CalculatorServiceApplication ServiceApplication
{
get
{
// Lookup service application by querystring parameter
Guid serviceApplicationGuid = new Guid(HttpContext.Current.Request.QueryString["id"]);
return SPFarm.Local.GetObject(serviceApplicationGuid) as CalculatorServiceApplication;
}
}
protected void OkButton_Click(object sender, EventArgs e)
{
if (Page.IsValid)
{
// Update service application settings
CalculatorServiceApplication serviceApplication = this.ServiceApplication;
serviceApplication.Precision = Int32.Parse(PrecisionTextBox.Text);
serviceApplication.Update();
// Navigate back to the service application management page
RedirectOnOK();
}
}
public override string PageToRedirectOnOK
{
get { return "/_admin/ServiceApplications.aspx"; }
}
public override string PageToRedirectOnCancel
{
get { return "/_admin/ServiceApplications.aspx"; }
}
}

The interesting bit of code here is the ServiceApplication property (lines 24-32). Here we’re assuming that the URL used to navigate to the aspx page will include a querystring parameter named “id” with a value that matches the Guid identifier of the service application to be managed. This is necessary because, if you remember our discussion on service application topologies, there may be more than one of our Calculator service applications in a server farm. We parse the Guid parameter and use it to look up the specified service application using the configuration object model (line 30).

And finally, we’ll hook our new management page up to the ribbon by overriding the ManageLink property of our service application:

internal sealed class CalculatorServiceApplication : SPIisWebServiceApplication
{
public override SPAdministrationLink ManageLink
{
get
{
return new SPAdministrationLink("/_admin/sample/calculator/manageapplication.aspx?id=" + this.Id.ToString());
}
}
}

Note that we include the “id” querystring parameter in the URL required by our management page (line 7).

That’s it!

We’ve added a configurable setting and a page to manage it:

Administrators can create multiple service applications and configure each of them with a different setting.

However, we don’t have a way for administrators to script this new setting using PowerShell. We’ll take care of that next time.

SharePoint Calculator Service Part 5 – Service Application PowerShell

2010-05-01T01:28:00Z

In Part 4 of this series, we integrated our Calculator service application creation and provisioning experience with the SharePoint Central Administration site.

While this provides a nice experience for ad-hoc SharePoint deployments, we would also like to support scripted deployments which are completely automated.

In this article, we’ll build a PowerShell cmdlet to integrate our service application creation experience into the SharePoint 2010 Management Shell to support these scenarios.

We’ll create a cmdlet named New-CalculatorServiceApplication that will take two required parameters: the name of the new service application, and the application pool that will host it. The cmdlet will then create the new service application and provision it.

Here’s the proposed syntax:

PS> gcm New-CalculatorServiceApplication -syntax
New-CalculatorServiceApplication [-Name] <String> [-ApplicationPool] <SPIisWebServiceApplicationPoolPipeBind>

The SPIisWebServiceApplicationPoolPipeBind parameter accepts a service application pool object, which can be created by the New-SPServiceApplicationPool cmdlet. Alternatively, an administration can use the Get-SPServiceApplicationPool cmdlet to select an existing service application pool to be used for the new service application.

The first thing we’ll do is create the New-CalculatorServiceApplication cmdlet by subclassing SPCmdlet:

CalculatorServiceCmdlets.cs

[Cmdlet(VerbsCommon.New, "CalculatorServiceApplication", SupportsShouldProcess = true)]
[SPCmdlet(RequireLocalFarmExist = true, RequireUserFarmAdmin = true)]
internal sealed class NewCalculatorServiceApplication : SPCmdlet
{
private SPIisWebServiceApplicationPoolPipeBind m_ApplicationPool;
[Parameter(Mandatory = true, Position = 0)]
[ValidateNotNullOrEmpty]
public string Name
{
get;
set;
}
[Parameter(Mandatory = true, Position = 1, ValueFromPipeline = true)]
[ValidateNotNull]
public SPIisWebServiceApplicationPoolPipeBind ApplicationPool
{
get { return m_ApplicationPool; }
set { m_ApplicationPool = value; }
}
protected override void InternalProcessRecord()
{
// Ensure that the farm level required objects exist
SPFarm farm = SPFarm.Local;
if (null == farm)
{
ThrowTerminatingError(new InvalidOperationException("SharePoint server farm not found."),
ErrorCategory.ResourceUnavailable, this);
}
// Ensure that the service exists
CalculatorService service = farm.Services.GetValue<CalculatorService>();
if (null == service)
{
ThrowTerminatingError(new InvalidOperationException("Calculator service not found."),
ErrorCategory.ResourceUnavailable, this);
}
// Check for an existing sample web service application
CalculatorServiceApplication existingServiceApplication = service.Applications.GetValue<CalculatorServiceApplication>();
if (null != existingServiceApplication)
{
WriteError(new InvalidOperationException("Calculator service application exists."),
ErrorCategory.ResourceExists, existingServiceApplication);
// Skip the current record
SkipProcessCurrentRecord();
}
// Get a reference to the specified application pool
SPIisWebServiceApplicationPool applicationPool = this.ApplicationPool.Read();
if (null == applicationPool)
{
WriteError(new InvalidOperationException("The specified application pool could not be found."),
ErrorCategory.InvalidArgument, this);
// Skip the current record.
SkipProcessCurrentRecord();
}
if (ShouldProcess(this.Name))
{
// Create the sample application
CalculatorServiceApplication serviceApplication = new CalculatorServiceApplication(
this.Name, service, applicationPool);
serviceApplication.Update();
// Provision the sample application
serviceApplication.Provision();
// Write the new sample application to the pipeline
WriteObject(serviceApplication);
}
}
}

The Cmdlet attribute (line 1) defines the cmdlet verb and noun.

The SPCmdlet attribute (line 2) ensures that the local machine is joined to a SharePoint farm and that the caller is a farm administrator before the cmdlet is executed.

The Name and ApplicationPool properties (lines 5-21) are the two cmdlet parameters. The SPIisWebServiceApplicationPoolPipeBind class is a SharePoint class that has associated cmdlets for creating and looking up application pools that can be passed to the cmdlet as the ApplicationPool parameter, i.e., New-SPServiceApplicationPool.

The InternalProcessRecord method (lines 23-76) is where the work happens.

Lines 25-50 simply validate the farm configuration.

Line 53 reads the SPIisWebServiceApplicationPool parameter from the pipebind parameter.

Lines 65-71 create and provision a Calculator service application, which should look familiar since it’s the same code we used in the Central Administration site UI.

And finally, line 74 writes the new service application object out to the PowerShell pipeline where it can be piped as input to the next cmdlet in the pipeline.

Now, we need to tell SharePoint Management Shell about our new cmdlet. This is done by first creating an xml registration file as follows:

CalculatorServiceApplicationCmdlets.xml

<ps:Config
xmlns:ps="urn:Microsoft.SharePoint.PowerShell"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:Microsoft.SharePoint.PowerShell SPCmdletSchema.xsd">
<ps:Assembly Name="Sample.Calculator.Service, Version=1.0.0.0, Culture=neutral, PublicKeyToken=d5d38459f57e2f46">
<ps:Cmdlet>
<ps:VerbName>New-CalculatorServiceApplication</ps:VerbName>
<ps:ClassName>Sample.Calculator.Service.PowerShell.NewCalculatorServiceApplication</ps:ClassName>
<ps:HelpFile>Sample.Calculator.Service.PowerShell.dll-help.xml</ps:HelpFile>
</ps:Cmdlet>
</ps:Assembly>
</ps:Config>

We simply register our assembly full name (line 5), our cmdlet verb and name (line 7), the class that implements the cmdlet (line 8), and a help file (line 9). We won’t actually create the help file for now since it’s optional.

And finally, we’ll update our temporary installation batch file to copy the xml file to the appropriate location:

xcopy /y "%_SETUPPATH%\PowerShell\*Cmdlets.xml" "%_INSTALLPATH%\Config\PowerShell\registration\*.*"

Done.

So what do we get for this code?

Well, it’s pretty simple for SharePoint administrators to create our service application from the Management Shell now:

PS C:\> $appPool = Get-SPServiceApplicationPool CalculatorServiceAppPool
PS C:\> New-CalculatorServiceApplication "Calculator" $appPool

DisplayName          TypeName             Id
-----------          --------             --
Calculator          Sample.Calculator... 9ed7060a-618a-4363-8753-6b9b4d6a5d15

The first command assigns the application pool named “CalculatorServiceAppPool” (which I previously created using the “New-SPServiceApplicationPool” cmdlet) to a variable, and the second command creates a new CalculatorServiceApplication with the name “Calculator” in the “CalculatorServiceApplicationAppPool”.

Or, I can do this on one line using the PowerShell pipeline:

PS C:\> Get-SPServiceApplicationPool CalculatorServiceAppPool | New-CalculatorServiceApplication "Calculator"

I can also use the built-in cmdlets to manage the new service application. For example:

PS C:\> Get-SPServiceApplication

DisplayName          TypeName             Id
-----------          --------             --
Security Token Se... Security Token Se... 7d88501a-a3e0-4289-aa96-62048803b1fb
Application Disco... Application Disco... e79b6d9d-f7a0-4ac9-bdda-a9df8dc5e138
WSS_UsageApplication Usage and Health ... 7f75ee92-3930-4496-b1e2-743829f74cf4
Calculator           Sample.Calculator... 9ed7060a-618a-4363-8753-6b9b4d6a5d15

So there you have it—a PowerShell cmdlet that makes it easy for administrators to automate deployment of the Calculator service application.

SharePoint Calculator Service Part 4 – New Service Application UI

2010-04-28T06:23:21Z

In Part 3 of this series, we created a service application class that represents a logical endpoint of our Calculator service in the SharePoint server farm topology.

We also created a temporary installer (a batch file) to put our service files in the right places on the disk. (We’ll revisit the proper way to do this in a future article.)

And finally, we saw how an administrator can use PowerShell commands to create a new service application object and deploy our service to any server in the farm.

Pretty neat, except that the PowerShell commands were far from intuitive. Time to fix that.

In this article, we’ll see how to integrate our service application creation and provisioning experience with the SharePoint Central Administration web site. This will allow administrators to simply point and click to deploy a Calculator service application to servers in the farm.

The first thing we’ll do is implement the IServiceApplicationAdministration interface on our CalculatorService class:

CalculatorService.cs

internal sealed class CalculatorService : SPIisWebService, IServiceAdministration
{
#region IServiceAdministration Members
public Type[] GetApplicationTypes()
{
return new Type[] { typeof(CalculatorServiceApplication) };
}
public SPPersistedTypeDescription GetApplicationTypeDescription(
Type serviceApplicationType)
{
if (serviceApplicationType != typeof(CalculatorServiceApplication))
{
throw new NotSupportedException();
}
return new SPPersistedTypeDescription(
"Calculator Service",
"Performs calculations to demonstrate the SharePoint Service Application Framework.");
}
public override SPAdministrationLink GetCreateApplicationLink(
Type serviceApplicationType)
{
return new SPAdministrationLink("/_admin/sample/calculator/createapplication.aspx");
}
public override SPCreateApplicationOptions GetCreateApplicationOptions(
Type serviceApplicationType)
{
// Do not support farm creation wizard
return SPCreateApplicationOptions.None;
}
public SPServiceApplication CreateApplication(
string name,
Type serviceApplicationType,
SPServiceProvisioningContext provisioningContext)
{
throw new NotSupportedException();
}
public SPServiceApplicationProxy CreateProxy(
string name,
SPServiceApplication serviceApplication,
SPServiceProvisioningContext provisioningContext)
{
throw new NotSupportedException();
}
#endregion
}

The GetApplicationTypes method (lines 5-8) tells SharePoint the types of service applications that are supported by our service. In this case, we have one service application type: CalculatorServiceApplication.

The GetApplicationTypeDescription method (lines 10-21) return a user-friendly description of our service application type for display purposes.

The GetCreateApplicationLink method (lines 23-27) return the URI of the ASPX page that provides the user interface for creating our service application. We’ll need to create this page later.

We don’t need to implement the remaining interface methods for now—they are used for integrating with the Farm Configuration Wizard, which we’ll cover in a future article.

Let’s take a look at what we get for this work:

Nice! The Service Applications management page has a new “Calculator Service” drop-down menu item.

If you click “New”, “Calculator Service” right now, you’ll see a “Page Not Found” error in your browser because we haven’t created the “createapplication.aspx” page yet. So let’s create it:

CreateApplication.aspx.cs

public class CalculatorServiceApplicationCreatePage : GlobalAdminPageBase
{
protected TextBox ServiceApplicationNameTextBox;
protected IisWebServiceApplicationPoolSection ServiceApplicationPoolSection;
protected override void OnLoad(EventArgs e)
{
((DialogMaster)Page.Master).OkButton.Enabled = true;
base.OnLoad(e);
}
protected override void OnInit(EventArgs e)
{
((DialogMaster)Page.Master).OkButton.Click += new EventHandler(this.OkButton_Click);
base.OnInit(e);
}
protected void OkButton_Click(object sender, EventArgs e)
{
if (Page.IsValid)
{
CalculatorService service = SPFarm.Local.Services.GetValue<CalculatorService>();
if (service != null)
{
using (SPLongOperation longOperation = new SPLongOperation(this))
{
longOperation.Begin();
string serviceApplicationName = ServiceApplicationNameTextBox.Text.Trim();
CalculatorServiceApplication serviceApplication = new CalculatorServiceApplication(
serviceApplicationName,
service,
this.ServiceApplicationPoolSection.GetOrCreateApplicationPool());
serviceApplication.Update();
serviceApplication.Provision();
longOperation.EndScript("window.frameElement.commitPopup();");
}
}
else
{
throw new InvalidOperationException("The Calculator service is not installed.");
}
}
}
}

The protected members (lines 3-4) reference controls that will be used to prompt for the new service application name and application pool.

The OnLoad and OnInit methods (lines 6-18) enable the “OK” and “Cancel” buttons on the page, which is displayed as a dialog.

The OkButton_Click method (lines 20-51) is called when the OK dialog button is clicked.

Line 24 looks up our CalculatorService object in the configuration database. If it’s not found, we throw an exception (line 47). (It should be installed, otherwise the link to this page in the “New” drop-down menu wouldn’t be there.)

Lines 27-29 start a new SPLongOperation, which displays a fancy progress bar. This will give the administrator something nice to look at while SharePoint churns away deploying the new service application to all of our online service instances in the farm.

Lines 33-38 create a new service application from the administrator input and persist it in the configuration database.

Line 40 is where the magic happens. The Provision method instructs SharePoint to deploy the service application to all online Calculator service instances in the server farm, to include creating an IIS web site and virtual directory as necessary to host our WCF service.

And finally, line 42 ends the SPLongOperation by closing the dialog window.

Here’s the matching ASPX page:

<%@ Page Language="C#" Inherits="Sample.Calculator.Service.UI.Administration.CalculatorServiceApplicationCreatePage, Sample.Calculator.Service, Version=1.0.0.0, Culture=neutral, PublicKeyToken=d5d38459f57e2f46" MasterPageFile="~/_layouts/dialog.master" %>
<%@ Assembly Name="Microsoft.SharePoint.ApplicationPages.Administration, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"%>
<%@ Assembly Name="Microsoft.SharePoint.ApplicationPages.Administration" %>
<%@ Register Tagprefix="wssawc" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register TagPrefix="wssuc" TagName="InputFormSection" src="~/_controltemplates/InputFormSection.ascx" %>
<%@ Register TagPrefix="wssuc" TagName="InputFormControl" src="~/_controltemplates/InputFormControl.ascx" %>
<%@ Register TagPrefix="wssuc" TagName="IisWebServiceApplicationPoolSection" src="~/_admin/IisWebServiceApplicationPoolSection.ascx" %>
<%@ Import Namespace="Microsoft.SharePoint" %>
<%@ Import Namespace="Microsoft.SharePoint.ApplicationPages" %>
<asp:Content ContentPlaceHolderId="PlaceHolderAdditionalPageHead" runat="server">
<wssawc:FormDigest ID="FormDigest" runat="server" />
</asp:Content>
<asp:Content ContentPlaceHolderId="PlaceHolderDialogHeaderPageTitle" runat="server">
<asp:Literal ID='PageTitle' Text="Create New Calculator Service Application" runat="server" />
</asp:Content>
<asp:Content contentplaceholderid="PlaceHolderDialogDescription" runat="server">
<asp:Literal ID='PageDescription' Text="Specify the settings for this new service application." runat="server" />
</asp:Content>
<asp:content contentplaceholderid="PlaceHolderDialogBodyMainSection" runat="server">
<table border="0" cellspacing="0" cellpadding="0" width="100%" class="ms-propertysheet">
<wssuc:InputFormSection
Title="Name"
runat="server">
<Template_InputFormControls>
<wssuc:InputFormControl LabelText="Service Application Name" runat="server" >
<Template_Control>
<wssawc:InputFormTextBox
id="ServiceApplicationNameTextBox"
title="Name"
maxlength="256"
columns="35"
class="ms-input"
runat="server" />
<wssawc:InputFormRequiredFieldValidator
ID="ServiceApplicationNameValidator"
ControlToValidate="ServiceApplicationNameTextBox"
ErrorMessage="You must specify a value for this required field."
runat="server" />
</Template_Control>
</wssuc:InputFormControl>
</Template_InputFormControls>
</wssuc:InputFormSection>
<wssuc:IisWebServiceApplicationPoolSection
id="ServiceApplicationPoolSection"
runat="server" />
</table>
</asp:content>

And here’s a new line in our temporary installer batch file to copy the ASPX page to the right place on disk:

xcopy /y "%_SETUPPATH%\UI\Admin\*.aspx" "%_INSTALLPATH%\template\admin\Sample\Calculator\*.*"

I won’t go through the ASPX code line-by-line, but here’s what it looks like after I filled in some values:

Simply click the “OK” button to create and deploy the new service application to the farm:

Note that SharePoint automatically provides the Delete, Publish, and Permissions pages. So administrators can publish your service application to remote server farms and manage who can access it—without any further coding!

So there you have it—a deployment experience that fits our custom Calculator service neatly into the SharePoint Central Administration site just like the built-in services that ship with the product. Now SharePoint administrators will feel right at home creating and deploying our Calculator service in their server farms.

No doubt some of you are noting that a few of the ribbon buttons are still disabled, namely, the Manage, Administrators, and Properties buttons. Never fear—we’ll fix that soon.

SharePoint Calculator Service Part 3 – The Service Application

2010-04-10T00:45:37Z

In Part 2 of this series, we integrated our Calculator service with the SharePoint server farm topology by extending the SPIisWebService and SPIisWebServiceInstance classes. These two classes allow administrators to use the SharePoint UX to view the topology and to start and stop our service host process on any server in the server farm. However, we haven’t yet created a service application to host, so this isn’t very useful yet.

In this article, we’ll create a service application by extending the SPIisWebServiceApplication class.

CalculatorServiceApplication.cs

[System.Runtime.InteropServices.Guid("AF113976-8384-47CD-8055-0DD6C742B301")]
internal sealed class CalculatorServiceApplication : SPIisWebServiceApplication
{
internal CalculatorServiceApplication(
string name,
CalculatorService service,
SPIisWebServiceApplicationPool applicationPool)
: base(name, service, applicationPool)
{
}
protected override string InstallPath
{
get
{
return SPUtility.GetGenericSetupPath(@"WebServices\Sample.Calculator");
}
}
protected override string VirtualPath
{
get
{
return "calculator.svc";
}
}
}

The base class requires two abstract methods, InstallPath and VirtualPath, to be implemented.

The InstallPath property (lines 12-18) tell SharePoint where to find our service files. This property should return the fully qualified path to a directory in the local server file system that contains our calculator.svc and web.config files. When the service application is provisioned (started) on a given server, SharePoint will create an IIS virtual directory that points to this path.

In this implementation, I am using the SPUtility.GetGenericSetupPath() helper method which returns a path relative to the SharePoint installation directory, in this case, under the “WebServices\Sample.Calculator�� directory. Note that there will be other services in the “WebServices” directory, so be sure to use something unique, like your company name, as a prefix for your subdirectory.

The VirtualPath property (lines 20-26) tells SharePoint the URI of your service endpoint relative to the InstallPath directory, in this case, “calculator.svc”. This will be appended to the URI that identifies that IIS virtual directory where our service application is provisioned in IIS, for example, http://server1/vdir/calculator.svc. SharePoint will take care of figuring out the base portion of the URI, e.g., http://server1/serviceapp1, which is different for each server hosting our service (service instance) and for each service application. We just need to specify anything else that should be tacked on to the end of that path.

Now to finish up, we need some way to create this directory on each server and install the calculator.svc and web.config files. Normally, you would do this using an MSI or a SharePoint solution, but to keep things simple for now, we’ll just use a batch file to xcopy the files.

install.cmd

@echo off
setlocal
set _INSTALLUTIL=%SystemRoot%\Microsoft.NET\Framework64\v2.0.50727\InstallUtil.exe
set _INSTALLPATH=%CommonProgramFiles%\Microsoft Shared\web server extensions\14
set _APPNAME=Sample.Calculator
set _SETUPPATH=%~dp0.
echo Installing service from '%_SETUPPATH%' to '%_INSTALLPATH%\WebServices\%_APPNAME%'...
xcopy /y "%_SETUPPATH%\*.svc" "%_INSTALLPATH%\WebServices\%_APPNAME%\*.*"
xcopy /y "%_SETUPPATH%\web.config" "%_INSTALLPATH%\WebServices\%_APPNAME%\*.*"
%_INSTALLUTIL% "%_SETUPPATH%\%_APPNAME%.Service.dll"
echo Setup complete.

A SharePoint administrator can run this batch file on each server in a farm to install the Calculator service. Note that the batch file assumes that the calculator.svc and web.config files are in the same directory as the batch file (line 7).

That’s it! We’ve created a service application and a script to deploy it to a server farm.

So what do we get for this work?

Well, a SharePoint administrator can now create a Calculator service application and deploy it to all of the online Calculator service instances in the server farm using the PowerShell console. For example:

PS> [System.Reflection.Assembly]::LoadWithPartialName("Sample.Calculator.Service")
PS> $instance = Get-SPServiceInstance | where { $_.GetType().Name -eq "CalculatorServiceInstance" } | select -first 1
PS> $service = $instance.Service
PS> $appPool = Get-SPServiceApplicationPool | select -first 1
PS> $app = New-Object Sample.Calculator.Service.Administration.CalculatorServiceApplication "CalculatorApp1", $service, $appPool
PS> $app.Update()
PS> $app.Provision()

After executing these commands on any one server, we’ll have a brand new service application named “CalculatorApp1” deployed to all of the service instances in the server farm. And, the administrator can start and stop service instances to provision and un-provision the IIS-hosted web service on any server at any time.

Here’s what our service application looks like in the “Manage Service Applications” UX:

And here’s what it looks like in IIS Manager (on a server where the Calculator service instance has been started):

Note that SharePoint has created a virtual directory under the “SharePoint Web Services” IIS site, and that it contains our service files. The virtual directory name is a GUID which uniquely identifies the service application we created.

If we create a second service application, another virtual directory will be created with a different identifier. However, both virtual directories will point to the same physical directory in the file system (the one we specified in our service application InstallPath property).

So it works, but creating the service application sure wasn’t pretty. We’ll fix that next time.