CodePlex Project

The People’s Jukebox

EltonStoneman — Wed, 30 Sep 2009 19:00:38 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

For a forthcoming celebration, I've been working on a jukebox web application:

The client controls the music being played on the server, so its intended for local networks where you want shared control of a central music player. If you can find a use for it, help yourself – it's on CodePlex here: The People's Jukebox. If nothing else it's a straightforward example of a Silverlight 2.0 client talking to WCF REST services, in what's probably a familiar domain.

The user experience is meant to be zero-guidance. You can try it out on a version where the UI functions but doesn't play any music: The People's Jukebox on sixeyed.com.

The initial screen shows what's currently playing and has a big button for you to select a track. In the next screen you choose either to search for a specific track, browse through the collection, or have the jukebox randomly choose some options for you. From any of those routes, you select a track, confirm your choice and it gets queued:

The queuing is what gives The People's Jukebox its democratic flavour – if you select a track which is already queued, you increment its vote count. When the current track finishes, the jukebox picks the next track with the most votes. When a track is selected the UI forces you to wait for a few seconds before you can continue, to discourage The People from abusing their power and making the same selection over and over again.

If no one's choosing tracks, the jukebox will randomly pick one which it hasn't already played, so it should keep playing until all the songs are played, or the web server is stopped.

Usage

Run the MSI and the jukebox Web site and services will be installed with default configuration options, using the installing user's "My Music" as the root folder to look for tracks. It will populate the track catalogue from the file system, expecting to find a conventional root/artist/album/track hierarchy:

My Music
- The Beatles
  - Abbey Road
    - 01. Come Together
    - etc.

Open http://localhost/ThePeoplesJukebox/ and hit Start - the music should start playing and you should be able to navigate around your music collection. The jukebox services log everything they do, by default to C:\TEMP\PeoplesJukeboxService.log, so if nothing happens that's the place to look for clues.

Configuration

The jukebox is configurable through Web.config on the services. Options are documented in comments – the installer sets up the root music directory, and the types of music files in the fileSystemConfiguration element:

<!--Specify the root path for music files, and

the types of files to load. Directory can be

a network path, extensions are comma-separated:-->

<fileSystemCatalogueConfiguration

rootDirectory="x:\My Music"

fileExtensions="*.wav,*.mp3"

rootDirectory can be local or a UNC path, e.g. \\nas\music.

Track Lists

Track lists are what drives the song selection behaviour; this is also configurable. Three types of tracklist are provided. When the jukebox finishes playing a track, it will query the tracklists in priority order until one returns a track, which will be loaded and played next:

<!-- Tracklists to use, and the order in which they are queried.

Specify "chosenByText" to display which tracklist chose the

Now Playing track on the client -->

</trackLists>

In default form, the jukebox lets you start off with some specified songs, moving onto the selections of The People, with the jukebox picking a random track if none are queued, so tracklists are queried in the following order:

1. ConfiguredTrackList – reads a list of specific track names from configuration, and returns them in priority order. Will not play a track that's already been played. Configuration looks like:

</tracks>

</trackConfiguration>

Intended to start the evening off with a known selection, when the configured tracks have been played, the list returns null so the jukebox moves on to the next tracklist.

2. SelectedTrackList – hopefully the main provider, queues up track requests as users make a selection. Operates the voting mechanism, so tracks which are selected multiple times move up the queue. If all queued tracks have the same number of votes, they're played in the order they were first selected. Will allow tracks to be played multiple times, but not sequentially – if you choose a track that's already queued, you increase its vote count; if you choose the same track again whilst its playing, or after it has been played, it gets queued again. Returns null if no tracks are queued.

3. RandomTrackList – failsafe list, to ensure music is always playing, picks tracks at random from the catalogue. Will not play a track that's already been played. Allows the administrator to sneak in some favourites by configuring "must-have" tracks. Must-haves will be inserted between random selections, at a configured frequency:

</mustHaveTracks>

</randomTrackListConfiguration>

- meaning every fifth track will be picked from the configured list, then the next four will be random. If no must-haves are specified, or they have all been played, the selection will be random.

Technical Details

Much of the implementation is straightforward. WCF has in-built support for REST, so you can expose a WCF service with a RESTful endpoint like http://localhost/PeoplesJukebox.Services/CatalogueService.svc/artist/2 (to get the list of tracks from artist with ID=2 from the catalogue service), just by flagging the service implementation with the WebGet attribute:

[WebGet(UriTemplate = "artist/{artistId}", ResponseFormat = WebMessageFormat.Xml)]

public Artist GetArtist(string artistId)

{...

Task-driven workflow implementation in Silverlight is also straightforward, by hosting multiple pages on the application, all of which are invisible except the current page. When the current page completes, it hides itself and loads the next page – handled through events in Page.xaml.cs:

public Page()

{

InitializeComponent();

foreach (PageBase page in Pages)

{

page.Complete += new PageBase.OnCompleteEventHandler(PageComplete);

page.Cancelled += new PageBase.OnCancelledEventHandler(PageCancelled);

}

this.CurrentPage = this.ucStartPage;

}

Silverlight 2.0 doesn't work so well with non-GET web requests, which is why all the services are GETs where some should really be POSTs.

The only difficult part was playing music files through IIS in a background thread, while continuing to respond to web service and web site requests. If you're really interested in looking into this, you'll see the music playing component is also specified in config:

<!-- Core configuration - which implementations to use for

media player and catalogue components -->

<peoplesJukeboxConfiguration

mediaPlayer="PeoplesJukebox.Core.Players.FMODPlayer, PeoplesJukebox.Core"

mediaCatalogue="PeoplesJukebox.Core.Catalogues.FileSystemCatalogue, PeoplesJukebox.Core"

There are several (failed) implementations in the source which are not built in the solution (under ..\PeoplesJukebox\PeoplesJukebox.Core\Players). Of the five attempts, all of them had showstopper issues except the excellent FMOD library:

DirectX – using the Audio class from the managed wrapper in the DirectX SDK. Redistributable install is massive, which is offputting, but more importantly the Audio.Ending event didn't fire reliably, so playback would intermittently stop and never resume;
Windows Media Player – using the managed WMPLib wrapper in the Windows Media Player SDK, to devolve playing responsibility to Media Player. Didn't like the extra dependency, or the alarming memory profile. Worse, the player would randomly change state to Stopping in the middle of playback and not resume;
Sound – using .NET's native sound player in System.Media. Fine for playing WAVs, at the cost of having to manage your own threads. Main issue that WAVs are not normalized so tracks will be played at their native volume, which is likely to mean volume changes between songs. Unable to play other media types;
Alvas Audio – looked good, but highly unfriendly API. Couldn't get the thing to play at all;
FMOD – highly-featured C++ audio processor which does its own thread management, copes with various media types, plays reliably for extended periods and has an efficient memory model. The library is free for non-commercial use, so The People's Jukebox has the same restriction. The library is complex, but I've used it through FMOD.NET – Rafael Nicoletti's very nice C# wrapper.

The mediaCatalogue element lets you choose how the catalogue is built. Currently, only a file system catalogue is provided, but extending it (e.g. to use SqueezeCenter – now SqueezeBox Server), is an option.

If you download the jukebox and find any issues using it, let me know through a comment or a CodePlex bug.

BizTalk Cache Adapter Samples

EltonStoneman — Tue, 02 Jun 2009 03:11:26 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The sample BizTalk application provided with the BizTalk Cache Adapter on CodePlex illustrates three approaches for using the cache:

Simple Messaging – routes all messages configured for caching to the cache adapter, and sends cache-misses on to the service provider;
Orchestration – explicitly routes messages to either the cache adapter or service provider in orchestration logic;
Complex Messaging – routes messages configured for caching either to the cache adapter or to the service provider.

All the samples use FILE locations for the originating request and ultimate response. The expected locations will be created in the install, with sample request files in the receive locations. Enable the relevant receive location to run the sample, then copy the request file to the receive location again to re-run it – from the second run onwards, the responses should be the cached versions.

Installation

To use the samples, you'll need to install and configure a cache provider, the cache adapter, cache adapter sample, sample service, and the cache viewer (if you want to see the contents of the cache).

Both the Cache Adapter and Sample BizTalk MSIs use PowerShell scripts for their post-processing steps. If you want to install from the MSIs, you'll need to have PowerShell installed and set up to enable script execution (Set-ExecutionPolicy RemoteSigned is fine).

1. Cache Provider.

Download and install NCache Express (this is a free edition, you'll have a product key emailed to you), and configure a cache instance for the samples by modifying the configuration file (config.ncconf – by default in C:\Program Files\NCache Express\config):

<cache-config name="Sixeyed.CacheAdapter.NCacheExpressProvider.Tests" inproc="false">

<eviction-policy default-priority="normal" eviction-ratio="10%" eviction-enabled="true"/>

<perf-counters enabled="false"/>

</cache-config>

</configuration>

This creates a single-node cache on the local machine, limited to 5Mb of system memory. Start the cache by running the startcache tool (C:\Program Files\NCache Express\bin\tools):

startcache Sixeyed.CacheAdapter.NCacheExpressProvider.Tests

- and verify it's there with listcaches. You should see the cache listed as Running:

2. Cache Adapter.

Sixeyed.CacheAdapter.msi is the BizTalk MSI which installs the adapter and artifacts. Import the application into BizTalk and run the installer. Verify the Sixeyed.CacheAdapter application is listed, and add the adapter in the Administration Console through Platform Settings...Adapters...New.

Note: the installer adds the necessary adapter files to the GAC and sets up the registry keys. If you don't use the MSI, manual installation steps are: add the files from the Binaries release to a local directory and to the GAC; modify run the .REG command to specify assembly paths and import the .REG file; add the BizTalk artifact resources to your own application.

2. Cache Adapter Sample.

Sixeyed.CacheAdapterSample.msi is the BizTalk MSI which installs the sample application and artifacts, and configures the ports. Import the application into BizTalk and run the installer. Verify the Sixeyed.CacheAdapterSample application is listed, and that the message types are configured in SSO (check the contents of SSO application Sixeyed.CacheAdapter).

Note: the installer creates FILE send and receive locations, copies sample messages, and sets up SSO configuration for the cached message types. If you don't use the MSI, manual installation should follow the steps in: Source\Sixeyed.CacheAdapterSample\Deployment\Sixeyed.CacheAdapterSample.Install.ps1.

4. Sample Service.

Sixeyed.CacheAdapterSample.Service.msi installs a WCF service for the samples to call. Verify the service has deployed correctly by navigating to http://localhost/Sixeyed.CacheAdapterSample/SampleService.svc?wsdl.

5. Cache Viewer.

Sixeyed.CacheAdapter.CacheViewer.msi installs a Winforms app for viewing cache contents. Run the application and configure it to use the running cache instance, by navigating to the NCacheExpressProvider assembly and selecting the NCacheExpressProvider:

- and specifying the ID of the cache instance:

(This is the same management UI used for configuring cache adapter ports in the BizTalk Administration Console. For the samples the Cache Id is Sixeyed.CacheAdapter.NCacheExpressProvider.Tests).

Simple Messaging

Enable the receive location ReceiveRequest_SimpleMessaging.FILE and you should see the following workflow:

Message is picked up by the receive location, which is using the CacheXMLReceive pipeline. This checks the cache configuration in SSO, where the message type is configured for caching, so context property IsMessageCacheEnabled is set to true;
Send port SimpleMessaging_GetCache picks up the message and sends it to the cache adapter, using the request message to build a cache key, and checking for a response existing in the cache. There is no cached response, so the message returned from the cache adapter is the original request message, with context property IsCached set to false;
Send port SimpleMessaging_SendServiceRequest picks up the message and sends it to the service;
Send port SimpleMessaging_PutCache picks up the service response and adds it to the cache, using the cache key from the original request;
Send port SimpleMessaging_SendServiceResponse picks up the service response and copies it to the output directory.

Check the cache viewer and you will see a byte array cached with a GUID key:

The GUID is the hash of the request message, and the byte array is the response message. Subsequent drops of the same request into the Requests folder will find the cached response at step 2, and the response will be the cached message.

This workflow is suitable for any simple messaging solution, where static ports are used and where the original request and ultimate response can be auctioned by different ports. Configuration of the cache instance is contained in the send ports.

Orchestration

The orchestration sample follows the same workflow as the Simple Messaging sample, and uses the same CacheXMLReceive pipeline to add the caching properties to the incoming message. The orchestration sample makes the cache access with explicit send and receives, and configuration of the cache instance is still contained in the send ports.

Enable the receive location ReceiveRequest_Orchestration.FILE to run the sample. This is suitable for solutions where finer grained control is needed over the caching mechanism, and an orchestration is a viable option.

Complex Messaging

Both the simple implementations use the cache adapter as a passthrough when there is no matching response in the cache – the incoming message is returned by the cache adapter, and a send port picks it up and routes it on the service. This is not suitable for more complex solutions:

where the service is invoked through a dynamic port, as the outbound transport and location set on the original message are not reset by the cache adapter on the passed-through message;
where the originating receive is from a request-response port, as the interchange will accept the passed-through message as a response, and not return the actual service request.

For these scenarios, the cache checking can be moved forward into the originating receive, so the cache adapter is only called if the response is known to exist in the cache. Added complexity here is that the receive pipeline needs to have the cache instance configuration, along with the send ports. This is shown in the Complex Messaging sample – run by enabling the receive location ReceiveRequest_ComplexMessaging.FILE:

Message is picked up by the receive location, which is using a custom pipeline – CheckCacheReceive. This consists of the SetMessageCacheProperties component which checks SSO to see if the message type is configured for caching, followed by the CheckIsCached component which checks is the message response is actually in the cache, and sets the IsCached property:

Note that the cache instance is configured in the pipeline. Using a custom pipeline means you can configure the instance using the Cache Adapter UI in Visual Studio, which is easier and applies validation. While you could use a generic pipeline and modify the configuration per-instance on receive locations, that means manually hacking the XML;
1. If the message response is cached, send port ComplexMessaging_GetCache picks up the message and sends it to the cache adapter. The adapter is configured in the same way as other samples, and uses the same logic – but in this case the response is known to be cached, so it will be returned and the request message should never be passed-through;
2. If the message response is not cached, send port ComplexMessaging_SendServiceRequest calls the service provider passing the original request message;
3. Send port ComplexMessaging_PutCache picks up the service response and adds it to the cache, using the cache key from the original request;
4. Send port ComplexMessaging _SendServiceResponse picks up the service response and copies it to the output directory.

There is a risk in this scenario that the object will exist in cache at the point of checking, but been removed by the time the cache is actually read. In this case the response from step 2 will be a passthrough of the original request – in the sample, this means the originating request will be copied to the output directory. Suspending the message may be a better option, but depending on the solution you may be able to cope with this differently.

BizTalk Cache Adapter

EltonStoneman — Tue, 02 Jun 2009 03:08:31 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

In a recent project we had a requirement for a configurable cache, residing on a BizTalk host and storing responses from WCF services which the BizTalk app had brokered. Producing this as a generic cache adapter was the preferred option, but project timescales didn't allow for it – instead I've written the adapter as an open source component which is available on CodePlex: BizTalkCacheAdapter, and which we're now making use of in the project.

It's a simple design suitable for any situation where BizTalk is brokering services to consumers. The incoming request from the consumer is hashed to generate a cache key, and the response is stored in the cache against the request key. When future requests exactly match, they will receive the cached response; if the response doesn't exist in the cache, the service provider is invoked and the response is added to the cache. The adapter is independent of the cache store being used – currently the only option provided is NCache Express, but extending it to use memcached or Velocity will be straightforward.

Overview

The adapter uses context properties to store cache configuration, so it's suitable for orchestration or messaging solutions. Alongside the adapter on CodePlex is a sample project which demonstrates the approaches. The workflow is the same in both cases:

The consumer sends a service request via the CacheXMLReceive pipeline, which checks if the message type is configured for caching, and promotes the IsMessageCacheEnabled property;
If caching is enabled, a two-way message is sent to the cache adapter. This is a GET request, so the adapter checks the cache using the MessageCacheKey context property – if the context property is not available, the adapter writes it by hashing the contents of the service request in the message body;
The response from the cache adapter promotes the IsCached property, which identifies whether the response is in cache – if so, the body of the response message will be the cached service response, if not the body is the original service request which can be passed on to the service;
If IsCached is false, the service is invoked and a one-way message containing the response is sent to the cache adapter. This is a PUT request, so the adapter adds the message body to the cache using the MessageCacheKey;
The service response (either cached or from the provider) is returned to the consumer.

With the messaging solution, the same workflow is carried out using subscriptions to the promoted cache configuration properties, and the various send ports. This workflow may not be suitable for more complex messaging solutions, where services are invoked through dynamic send ports – there is an alternative workflow which I'll cover in a separate post.

The only real complexity in the adapter is in putting the service response into the cache – the outgoing service request message has the cache configuration properties promoted, but the incoming response does not. In orchestration solutions this isn't a problem, as the cache properties can be stored as state in the orchestration instance. In messaging solutions, the cache properties are retained by temporarily adding them to the cache, keyed by the interchange ID of the service instance, and removing them when the response is added to the cache.

Configuration

The cache adapter can be used with messages of any type, but with XML messages it can employ different cache configurations for different message types - e.g. a service to get current tax rates may configured to live for several days in the cache, while a service to get current exchange rates may use the same cache store, but be configured to expire after an hour. The CacheReceive and CacheReceiveXml pipelines contain properties for configuring the cache – it can be enabled/disabled for all messages, or (for the XML pipeline) only for configured message types:

Message-level configuration uses an SSO application store, which holds a MessageCacheConfigurationCollection object in XML:

<messageType>http://schemas.sixeyed.com/CacheAdapterSample/2009#GetServerDateTime</messageType>

</messageCacheConfiguration>

<messageType>http://schemas.xyz.com/2009#GetXYZ</messageType>

</messageCacheConfiguration>

...

Caching is enabled for a message if:

IsCacheEnabled is true on the pipeline AND
- IsMessageTypeConfigurationEnabled is false on the pipeline OR
- IsMessageTypeConfigurationEnabled is true on the pipeline AND
  - the incoming message type has an entry in the MessageCacheConfigurationCollection in SSO.

The lifespan of the object put into cache will be either the cacheLifespan specified in the MessageCacheConfiguration in SSO, or the defaultLifespan specified in the cache send port:

(The point at which the object is removed from cache will depend on the provider, some will remove it when its lifespan expires, others only when its lifespan expires and the cache is full or the cleanup schedule runs).

Installation

For version 1.0.0.0, the CodePlex project comes with three project releases, which can be used independently or together:

Sixeyed.CacheAdapter.msi - a BizTalk application MSI which can be imported and installed to your BizTalk server(s). The application contains the configuration schema and pipelines, so it can be used as-is, or the relevant artifacts can be moved to your own application;
Sixeyed.CacheAdapter.Binaries.zip – a ZIP file of the adapter binaries you can deploy manually. Use instead of the CacheAdapter MSI, if you don't want to deploy the whole BizTalk application;
Sixeyed.CacheAdapter.CacheViewer.msi – a Windows forms application which lets you view the contents of a cache store (the app uses the configuration components from the adapter management assembly, so it is also cache-provider agnostic):

- a documentation release:

Sixeyed.CacheAdapter.chm – documents the .NET assemblies of the adapter

- and two sample releases which should be deployed together:

Sixeyed.CacheAdapterSample.msi – a BizTalk application MSI which has sample usage of the cache adapter, demonstrating orchestration and messaging approaches;
Sixeyed.CacheAdapterSample.Service.msi – a WCF MSI which provides a service which the BizTalk app can cache.

Pre-requisite for the initial release is the non-commercial NCache Express to use as the cache provider.

To add the sample message-level cache configuration to SSO, the SSO Config Tool can import the provided .ssoconfig file into SSO.

I'll update the project to add a memcached provider, and write an updated post when it's available - and the same when Velocity is released. One advantage in having multiple providers would be in evaluating their performance against your expected caching load, so I'll look at extending the sample solution and adding some LoadGen scripts.

And as Michael Stephenson commented, a nice alternative would be to move the caching up to the WCF layer as a behavior, so WCF requests would check the cache first. Two options for this – it can either be a client behaviour using a local cache store (which could be more performant and would have less impact on server resources, but requires the cache provider to be deployed client-side), or as an operation behaviour using a shared server-side cache (which could be more performant, depending on the type of messages being cached, would impact on server and network resource, but would make the caching transparent to consumers). The complexity is on caching the response message if not already cached – the cache key from the original message will have been lost, so there needs to be a different approach for maintaining state to correlate the WCF service request and response.

Visualizing SOA’s Return on Investment

EltonStoneman — Thu, 26 Mar 2009 18:36:18 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

This is the rather grand title of a WebCast I've recorded recently which tries to illustrate where the return on investment comes after moving to a SOA strategy. The video is on Digital Forum: Visualizing SOA ROI , and the Open Source proof of concept it references is on CodePlex: ESBSimpleSamples.

In the WebCast I start with a blank Visual Studio solution and create a new Web app which consumes an existing service. All in it takes 3 lines of code and around 3 minutes of development (most of it spent correcting typos), and it doesn't require me to have any understanding of the underlying SOA infrastructure – in this case, Microsoft's ESB Guidance package sitting on BizTalk Server 2006 R2. Equally important, assuming the service we consume is in production, the testing and deployment effort needed for the new project is minimal.

This is a rework of a presentation I did with a client where I wanted to show how quick and easy it is to use their SOA implementation. I had reservations of showing a code demonstration to an audience which included IT heads (IT Director and Solution Architects) and project management, but it was surprisingly well received, so I've reproduced it using services and components which are publicly available.

Direct links to the references in the WebCast are here:

ESB Guidance: http://www.codeplex.com/esb
UK SOA/BPM User Group presentation: http://sbug.org.uk/media/p/129.aspx
Blog posts on ESB Guidance: http://geekswithblogs.net/EltonStoneman/category/7947.aspx

Sixeyed.Guidance.CodeGeneration: Technical Walkthrough

EltonStoneman — Mon, 09 Mar 2009 23:05:28 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The Code Generation Guidance Package on CodePlex was designed to be extensible and reusable. There are three main C# projects, which isolate logic for code generation, and the UI and GAX components.

Sixeyed.CodeGeneration

This is the core project, defining how metadata is represented and retrieved, and defining configuration for code generation runs. Metadata is defined in terms of:

A metadata source, which contains the logic for connecting to the source
A metadata provider, which uses the source to provide a list of available items, and to populate requested items
Metadata items, which are a representation of the metadata, typically using an appropriate .NET framework class

Code generation and UI logic always works on the interfaces which define these components, and the relationships between them:

In the Add Generated Items recipe, the available source types, sources and providers are populated from the collection of IMetadataSource objects held in the static SourceContainer class (additional sources can be added to the container at runtime using the SourceAssemblyConfiguration recipe argument – described in Sixeyed.Guidance.CodeGeneration Sample Package). When a provider is selected, GetItemNames is called to populate the list of available metadata items. When the selected items are iterated over in a code generation run, GetItem is called and the populated IMetadataItem is loaded as a property for the T4 template. The metadata item exposes the provider, and the provider exposes the source so the template can connect directly to the metadata if it needs to.

Each metadata interface has an abstract base class which implements it and contains core logic. For a given source, there may be an additional base class which abstracts logic common to that type of source. In Sixeyed.CodeGeneration.Metadata.Database.Source, DatabaseSource contains logic for accessing ADO.NET data sources in terms of IDbConnection and IDbCommand objects; SqlServerSource contains overriding logic to specify SqlConnection and SqlCommand usage – any additional database sources would do the same. Similarly for the SOAP metadata source, the logic for accessing WSDL is abstracted into a base class which may be used by other sources (e.g. a WCF specific source):

IMetadataProvider contains logic for accessing the source and retrieving a list of available items, and for populating a named item. The majority of logic is in the generic base class, so provider classes are quite simple. Simpler still are metadata item classes, which inherit the generic ItemBase class, specifying the underlying type of the item (XmlSchema in this case), without requiring any additional code.

Logic for populating template properties and executing T4 templates is located in the Guidance project rather than the code generation project, as it is dependent on the specific T4 engine being used.

Sixeyed.CodeGeneration.UI

The UI project contains generic user controls which represent metadata selections, and expose various events to notify of selection changes. The Guidance package Wizard uses these components rather than defining its own UI – the controls from this assembly allow code generation to be configured and invoked from a different UI host.

Sixeyed.Guidance.CodeGeneration

This project defines the GAX package and links together the code generation and UI components. The Guidance package is quite straightforward – it contains a single class AddGeneratedItems for the action of generating items from metadata and adding them to the selected project. The action expects SourceConfiguration, SelectedItems and TemplateConfiguration arguments; it connects to the source, iterates over the selected items and executes the template for each item.

To collect the argument values, there are custom wizard pages and value providers for each, allowing a recipe to provide ready-configured settings, or build a UI to gather them from the user:

Sixeyed.Guidance.CodeGeneration.CustomWizardPages. The custom Wizard pages use the static Metadata class to share state for the configured metadata source and provider. They override IsDataValid to determine if the page has collected enough information for the Wizard to proceed and the base class provides EnableNextStep which will advance the Wizard by enabling the Next or Finish button as appropriate. The base class will read the SourceAssemblyConfiguration recipe argument if provided, and use it to add any extra metadata assemblies at runtime.
Sixeyed.Guidance.CodeGeneration.ValueProviders. The value provider classes are straightforward, reading optional arguments from the recipe and populating the relevant metadata settings. Custom recipes can specify value providers to load settings instead of Wizard pages, so the Wizard UI can be restricted.

TODOs

There are a couple of minor changes I'd like to make to the current codebase:

Sixeyed.Guidance.CodeGeneration.CustomWizardPages.SelectTemplate defines its own UI, which should be moved to a user control in the UI project;
Sixeyed.CodeGeneration.Generation.MemberName contains methods for providing valid field and property names, but the Pascal and camel-case conversion is very basic;
Sixeyed.CodeGeneration.UI.SourceUri has some ugly hard-coding to decide which UI dialog it should show for different types of URI. It should be configurable, but I'm not happy moving it to an attribute of IMetadataSource, as that brings the UI into the core project.

And some additional metadata sources which I'll add at a future point – a Clipboard source providing access to clipboard data through text or XML providers, and a BizTalk source which will use the ExplorerOM for providers supplying application, group and instance information as metadata.

Sixeyed.Guidance.CodeGeneration Sample Package

EltonStoneman — Sun, 08 Mar 2009 22:46:00 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The basic Code Generation Guidance Package on CodePlex comes with an additional sample Guidance package. This sample is intended to demonstrate how the functionality of the base package can be customised to create a project-specific Guidance package, where you can easily add tailored code generation recipes to your package. In the basic package are the Wizard steps necessary to configure ad-hoc code generation, but there are also ValueProviders which can read configuration from recipes without requiring the whole user interface.

Installation

You'll need to modify the hard-coded paths and URIs in the sample package, so it doesn't come with an installed release. If you open the Sixeyed.Guidance.CodeGenerationSample solution you'll see that it references the base Sixeyed.Guidance.CodeGeneration and Sixeyed.CodeGeneration assemblies. The sample contains a set of T4 templates in the \Templates\Text directory, the XML configuration for the package and the XML includes for individual recipes. There's no additional code in the sample project, all the required functionality is in the referenced base package.

Together with the GAX project, there's a database project which you can use to create a SQL Server database suitable for the data-bound recipes to run against. To install, run the CreateDatabase script and then execute the SSIS package to populate data from the included Excel workbook (this is only necessary if you want to run the recipes as-is, otherwise you can modify the XML to use your own database).

Sample T4 Templates

There are T4 templates for each of the metadata providers in the base package. The scripts named _Simple.tt are straightforward and begin with the name of the expected provider; to run them, you can use Add Generated Items from the base package, select the relevant metadata and point to the template. To demonstrate more useful code generation, there are two more substantial templates:

ConfigurationSection.cs.tt – use the File source and the Text provider on this template. If you select Configuration.txt (from the database project) as the source, the recipe will generate a typed configuration class, which has a static property to access the current config settings. The template can be easily extended to add a Default value for optional settings, and the same text file can be used to drive a different T4 template to generate the actual configuration settings;
StoredProcedure.cs.tt – use the SQL Server database source and the Stored Procedure provider. Select a procedure and the recipe will generate a DAL class to execute the stored procedure. This class won't compile, as it inherits from a base class which isn't provided, but it demonstrates one approach for DAL generation.

Sample Recipes

The included recipes demonstrate configuring one or more settings for code generation so that the Wizard can be tailored or avoided altogether. Generate Stored Procedure shows this best, configuring the metadata provider using the SourceConfigurationValueProvider:

<ValueProvider Type="SourceConfigurationValueProvider"

SourceTypeName="Database"

SourceName="SqlServer Database"

SourceUri="Data Source=x\y;Integrated Security=True;Initial Catalog=Scratchpad;"

ProviderName="Stored Procedure Provider">

</ValueProvider>

</Argument>

These settings are the equivalent of the first Wizard page, selecting the metadata source. It specifies the source type and source name, the URI for the source (in this case, the Scratchpad database included with the sample), and the metadata provider name. Having the SourceConfiguration argument pre-populated means the first Wizard page will be skipped. The recipe also specifies the T4 template to use with the TemplateConfigurationValueProvider:

<ValueProvider Type="TemplateConfigurationValueProvider"

TemplatePath="x:\y\z\Templates\Text\StoredProcedure.cs.tt">

</ValueProvider>

</Argument>

Only the template path is specified here, but other settings (target namespace, class name etc.) can also be provided. Having the TemplateConfiguration argument populated means the third Wizard page will not be shown. Running this recipe gives you a Wizard form which only contains the second page, for selecting metadata items, pre-populated with the list which has already been loaded from the configured database:

- note that the other pages are not available, so the user is constrained to using the configured source and T4 template.

Other recipes demonstrate configuring all or part of the settings needed for code generation. Generate Simple runs a template which requires no metadata, so it connects to the metadata source, runs the template and adds the project output with no user intervention. Additional Source demonstrates how you can extend the base code generation guidance package with additional metadata sources and providers of your own, without rebuilding the base package. Specify the SourceAssemblyConfiguration argument:

<ValueProvider Type="SourceAssemblyConfigurationValueProvider"

AssemblyList="Sixeyed.CodeGeneration.Tests">

</ValueProvider>

</Argument>

- and the .NET assemblies named in AssemblyList (semi-colon separated) will be interrogated at run-time to identify IMetadataSource and IMetadataProvider implementations (there'll be more detail on those interfaces in a coming post). Any available classes will be added to the list of sources and providers shown in Add Generated Items, and can also be used in SourceConfiguration argument values.

Usage

By providing custom recipes, you can tailor your own Guidance packages which contain recipes for generating classes or other artifacts based on established patterns. This gives the project team an easy way of ensuring consistency for common coding problems in the domain – configuration sections and stored procedure wrappers are simple examples. Note that the URIs and paths are hard-coded. The code generation guidance package will attempt to find a T4 template if the path is not fully stated, but it won't always succeed (there's an issue with returning the running GuidancePackage instance that I haven't tracked down). In a typical project though, templates would be in SCM and source URIs would be consistent among developers, so fully-qualified hard-coded text shouldn't be a problem.

I'll be extending the sample package to include other templates that may be useful starting points for common code generation tasks – enums to represent reference data, unit tests for .NET and BizTalk artifacts, MSBuild scripts and anything else that occurs. If you have any templates of your own which would fit in a standard library, let me know and I'll add you as a CodePlex contributor.

Code Generation Guidance Package

EltonStoneman — Sun, 08 Mar 2009 01:51:14 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

I've been working on a Guidance package which lets you use Visual Studio as a front end to generate items from T4 templates. Using a recipe wizard you choose your metadata from a Web service, database or file system source, and the template is rendered against each of the metadata objects you select. It's on CodePlex here: Code Generation Guidance Package, and comes in two flavours. The basic Guidance package has a single recipe "Add generated items" – when you run it, you specify a metadata provider, select the items to use for metadata and the T4 template to render against the items.

The second package is a sample which extends the functionality of the main Guidance package with custom recipes. This demonstrates how you can define recipes for pre-configured generation types, so the user does not need to complete all the wizard pages – one example specifies a database connection string and a T4 template for generating stored procedure wrappers; to add a new DAL class, the user runs the recipe and just selects which stored procedure(s) they want generated.

Neither package comes with any Visual Studio solution or project templates, and they do not need to be used to create the original solution. Any existing project can make use of the code generation features by enabling the package(s) through Tools…Guidance Package Manager.

In this post I'll give an overview of using the basic Sixeyed.Guidance.CodeGeneration package, and in future posts I'll add some technical detail and give a walkthrough of the sample project.

Add Generated Items

Run the Add generated items recipe from the Guidance Package Manager, or from the context menu of any project in Solution Explorer. The wizard loads to collect settings - in the first page you select the metadata source type, configure the source and select the metadata provider:

During generation, the provider will load each of the selected metadata items and provide them as a property which can be accessed in the T4 template. For instance if you use the SQL Server Stored Procedure provider, your T4 script will have a populated SqlCommand object available to use.

Provided with the basic Guidance package are the following Sources and Providers:

File System
- File source – for using one or more files as metadata
  - XML File provider – for using XML file contents, exposed to the template as an XmlDocument instance
  - Text File provider – for using text file contents, exposed as a string
  - Assembly File provider – for using a .NET assembly, exposed as an Assembly instance
- Directory source – for using a list of directory contents as metadata
  - File List provider – for using a list of file names, exposed as a List<string> instance
  - Directory provider – for using a directory, exposed as a DirectoryInfo instance
Database
- SQL Server Database
  - Query Result provider – for executing a SQL query and exposing the results in a populated DataSet
  - Table provider – for using a table as metadata, exposed as an empty DataTable with the correct structure
  - Stored Procedure provider – for using stored procedures, exposed as a populated SqlCommand object
WSDL
- SOAP source
  - Web Method provider – for using a Web service method, exposed as a MethodInfo object
  - Schema provider – for using the WSDL of the service, exposed as an XmlSchema object

When you select a provider, it will load a list of all available metadata items, and you select which items you want to run the T4 template against:

The item selection is always a simple list displaying the item name – this will be the name of the file, table, Web method etc (an exception is the QueryResult provider which uses this page to capture the SQL query to be executed).

In the final screen, select the T4 template to use:

The file dialog will default to the "Templates" folder of the Guidance package, but you can navigate to any T4 file. If you want to override the output settings from the T4 file, specifying a different target filename, namespace extension or class name you can do it in the additional properties in this step:

Finish the wizard and the recipe will iterate over each of the selected items, populating a representation of the metadata and passing it to the T4 template property.

T4 Template Properties

In order to access metadata item information and create the output, your T4 script needs to specify two properties which will be populated using the Guidance PropertyProcessor engine:

<#@ property processor="PropertyProcessor" name="MetadataItem" #>

<#@ property processor="PropertyProcessor" name="TemplateConfiguration" #>

The MetadataItem property is an object implementing Sixeyed.CodeGeneration.Metadata.Interfaces.IMetadataItem:

The underlying Item property gives you access to the populated metadata item – the object type will depend on the provider, and will be specified in the ItemType property. The Key for the item (the name shown in the Select Items wizard page) is available, as is the metadata Provider which can be used to navigate up to the source.

The TemplateConfiguration property allows you to control the output of the template, setting default values for the target file name etc. (which can be overridden in the Select Template wizard page). It's an object of type Sixeyed.CodeGeneration.Generation.TemplateConfiguration:

Sample Templates

The CodeGeneration.Sample Guidance package contains a sample template for each of the metadata providers, demonstrating the type of object they expose and how it can be used. The scripts don't do much other than demonstrate usage, but there are fully-fledged scripts for generating wrappers for SQL Server stored procedures, and configuration sections from text files. The full script for the Table provider sample makes straightforward use of the underlying DataTable object:

<#@ template language="C#" #>

<#@ property processor="PropertyProcessor" name="MetadataItem" #>

<#@ property processor="PropertyProcessor" name="TemplateConfiguration" #>

<#@ assembly name="System.dll" #>

<#@ assembly name="System.Data.dll" #>

<#@ assembly name="System.Xml.dll" #>

<#@ assembly name="Sixeyed.CodeGeneration.dll" #>

<#@ import namespace="System.Data" #>

<#@ import namespace="Sixeyed.CodeGeneration.Generation" #>

<# PrepareOutput(); #>

Table name (from metadata): <#= MetadataItem.Key #>

Table name (from table): <#= dataTable.TableName #>

Columns:

<# foreach (DataColumn column in dataTable.Columns)

{

#>Column Name: <#= column.ColumnName #>

Data Type: <#= column.DataType #>

<#} #>

<#+

private DataTable dataTable

{

get{ return MetadataItem.Item as DataTable; }

}

private void PrepareOutput()

{

TemplateConfiguration.ClassName = string.Format("Table_{0}", MemberName.ToPascalCase(MetadataItem.Key, true));

TemplateConfiguration.FileExtension = "cs";

}

(If you don't already have it, the T4 Editor Community Edition from Clarius makes editing templates much easier).

The directives specify the expected properties, and import the relevant reference assemblies and namespaces. The script provides the dataTable property to easily access the metadata item as a typed DataTable object. In the PrepareOutput method (called at the start of the template), the script sets up the target class name and file extension. In this case a target filename is not specified, so the engine will use the class name and file extension for the filename. Note there are some helper methods in Sixeyed.CodeGeneration.Generation.MemberName for preparing valid member names.

Selecting a single table called Manufacturers for this script generates and adds a file called Table_Manufacturers.cs to the selected project, containing the following output:

Table name (from metadata): Manufacturers

Table name (from table): Manufacturers

Columns:

Column Name: ManufacturerId

Data Type: System.Int16

Column Name: ManufacturerName

Data Type: System.String

Column Name: AvailableFromDate

Data Type: System.DateTime

Column Name: AvailableToDate

Data Type: System.DateTime

Usage

For ad-hoc code generation, this basic Guidance package lets you specify metadata to execute against a T4 template. For commonly used scripts and standard patterns you can build a custom Guidance package which contains your solution structure, and specific recipes for generating known types of item – for DAL classes, entities, configuration sections, proxies or anything else that is based on external metadata.

Using the WCF SQL Adapter in .NET: Calling Stored Procedures

EltonStoneman — Tue, 03 Mar 2009 00:42:45 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The Adapter Pack 2.0 for BizTalk has been released in public beta recently, and among the WCF Line Of Business adapters it contains the WCF SQL adapter. This exposes SQL Server connections as WCF service endpoints, and lets you connect to a SQL Server source using the standard ServiceModel stack. The adapter pack will be released under the BizTalk brand, but the adapters themselves are not limited to BizTalk – the WCF SQL adapter can be used natively in .NET code.

This is a brief walkthrough covering the SQL Adapter for executing stored procedures, and I'll be covering SQL statements in a subsequent post.

Installation

Installation of the Adapter Pack is straightforward – you'll need .NET 3.5 Service Pack 1 with the latest hotfixes applied, and you'll need to install the WCF LOB Adapter SDK and then the BizTalk Adapter Pack 2.0 Evaluation (the beta version is limited to 120-day use). Note, you do not need to have BizTalk installed, and the tooling to support the WCF LOB adapters runs under Visual Studio 2008 as well as 2005. Help files for all the adapters are included, and although in pre-release form they are detailed and thorough.

Walkthrough: Consuming a Stored Procedure

The Adapter Pack adds a new context menu to code projects in Visual Studio – Add Adapter Service Reference. Run this and you're given a generic form for configuring your WCF LOB adapter. Choose sqlBinding to set up a WCF SQL connection:

Click Configure and you specify the connection configuration that will be used to build the binding. In the case of the WCF SQL adapter, you need to specify:

Client Credential Type (Windows for integrated authentication);
Server (database server name);
Instance (SQL instance name, if configured);
Initial catalog (the database to connect to).

This will build you a URI of the form: mssql://<server>/<instance>/<initialCatalog>? – with the ending question mark used to separate the core connection details from any configuration options.

Click Connect and you have the option to generate a Client binding, for making outbound requests to SQL Server (executing SQL statements, stored procedures etc.), or a Service binding which will react to inbound calls from SQL Server (for Query Notification or polling). Choose Client and the category view will be populated with a hierarchy of database objects which can be generated as WCF client proxies:

Generated Code

For stored procedure calls, the adapter can create generic proxies for weakly-typed calls returning populated DataSets, or strongly-typed calls which will generate entities representing the return from the call. In this case I've selected a Strongly-Typed Stored Procedure called GetManufacturer; add the selection and with the default options the adapter generates two items:

App.config – containing the WCF binding configuration;
SqlAdapterBindingClient.cs – containing the generated entity types and proxy classes.

The full binding configuration for the SQL adapter looks like this:

<system.serviceModel>

<binding name="SqlAdapterBinding" closeTimeout="00:01:00" openTimeout="00:01:00"

receiveTimeout="00:10:00" sendTimeout="00:01:00" maxConnectionPoolSize="100"

encrypt="false" workstationId="" useAmbientTransaction="true"

batchSize="20" polledDataAvailableStatement="" pollingStatement=""

pollingIntervalInSeconds="30" pollWhileDataFound="false" notificationStatement=""

notifyOnListenerStart="true" enableBizTalkCompatibilityMode="true"

chunkSize="4194304" inboundOperationType="Polling" useDatabaseNameInXsdNamespace="false"

allowIdentityInsert="false" enablePerformanceCounters="false"

xmlStoredProcedureRootNodeName="" xmlStoredProcedureRootNodeNamespace="" />

</sqlBinding>

</bindings>

<endpoint address="mssql://x/y/z?" binding="sqlBinding"

bindingConfiguration="SqlAdapterBinding" contract="TypedProcedures_dbo"

name="SqlAdapterBinding_TypedProcedures_dbo" />

</client>

</system.serviceModel>

- note that the binding contains some familiar WCF settings (sendTimeout, receiveTimeout), but the majority are SQL Server specific connection options. The client element specifies the contract as TypedProcedures_dbo, the ServiceContract interface generated by the adapter, which has a single OperationContract defined:

GetManufacturerResponse GetManufacturer(GetManufacturerRequest request);

The proxy code for the client is all generated, so to invoke the stored procedure in your own code it's a familiar case of instantiating the client and calling the service, and of course you have full IntelliSense on the entity representing the resultset:

It's the content of the generated code that's interesting. The service, request, response and entity objects here are contained in 166 lines of generated code. The entity object is just a plain DTO-style class which implements IExtensibleDataObject to allow access to any returned data that hasn't been mapped, and has a DataContract attribute with the schema name representing the stored procedure. The mapping between the entity properties and the returned columns is done with standard System.Runtime.Serialization attributes, so the ManufacturerId column is represented as:

[System.Runtime.Serialization.DataMemberAttribute()]

public System.Nullable<short> ManufacturerId {

get {

return this.ManufacturerIdField;

}

set {

this.ManufacturerIdField = value;

}

- note that this is an optional field in the database table, so it's generated as nullable in the entity. No other flags or code are used to map data, so the WCF SQL adapter is effectively deserializing the resultset from the stored procedure call straight into the DataContract.

The generated code works well and is cleanly produced, but it has a few quirks you may not be happy with. A typed client class is generated for each individual procedure, whereas you might want them grouped into a single class which represents the full suite; and the class names are a bit cumbersome ("StoredProcedureResultSet0", "TypedProcedures_dboClient"). However, the code needed to actually connect to SQL through WCF and map the response is so simple that it's a straightforward task to generate your own code from custom templates.

Potential Usage

After an initial look, the WCF SQL adapter seems to be an attractive option for generating and powering the data access layer of a .NET application, entirely apart from its primary purpose as a BizTalk adapter. It repositions data access as a service call and uses the standard WCF mechanisms of ServiceContract and DataContract for information exchange. Assuming other data providers follow suit, or other WCF-database adapters follow from the community, it's a nice way of isolating your application from the physical database, so swapping to MySQL or Oracle could become a simple matter of changing your WCF binding.

It'll be interesting to see the licensing of the WCF LOB adapters from Microsoft. Currently the availability of a comprehensive suite of adapters is being positioned as one of the attractions of BizTalk as the Integration Server, compared to WF+WCF+Dublin as the Application Server. With the WCF SQL adapter there's a lot of potential take-up as a simpler alternative to the ADO.NET Entity Framework, so if it requires a BizTalk license, there will be room for an open source alternative.

Introducing: BizTalkCop

EltonStoneman — Fri, 14 Nov 2008 16:36:06 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

To make good on a rash comment around the lack of standards-enforcement for BizTalk, I've put together a set of FxCop rules which allow you to run static analysis over BizTalk solutions. It covers all aspects by running rules against compiled artifact assemblies and configured BizTalk applications. It's on CodePlex here: BizTalkCop.

The first release(1.0) contains a full ruleset for validating BizTalk application artifact names, based on Scott Colestock's naming conventions. By default the rules are more strict in places, but they're configurable so you can modify them to suit your own standards.

Usage

Currently BizTalk projects don't integrate fully with static analysis in VS 2005, so you'll need the separate FxCop UI – latest version is FxCop 1.36. Once you've installed FxCop, run the BizTalkCop installer and it will add BizTalkCop.Rules.dll and BizTalkCop.Rules.chm to the FxCop rules folder (default: Program Files\Microsoft FxCop 1.36\Rules). Open FxCop and there are three steps to configure your BizTalk project:

1. Add Targets

Add the compiled BizTalk assemblies you want to check to the FxCop project. For compiled artifacts, BizTalkCop covers orchestrations, maps, schemas and pipelines so you can add any assemblies that contain these:

2. Select Rules

If you've used the default installation, then the BizTalkCop rule set should be listed in the Rules tab (if not you'll need to navigate to add it). Check BizTalkCop and uncheck all the others:

3. Set up Application Configuration

In order to validate the configured BizTalk Application, you'll need to specify the location of your management database, and the name of the Applications to check. Open the ApplicationConfig rule properties (this is a dummy rule which is only there to capture BizTalk Server config), and modify the Settings to specify your server, and the Applications to run over (semi-colon separated if more than one) – you only need to do this once, and all Application rules will use these settings:

When you run FxCop it'll list all the rule failures, some of which may have multiple issues (e.g. ReceiveLocationNamesShouldIndicateTransport will flag an issue for every configured location that doesn't have its transport type as a suffix). There should be no locks on targets, so you can change the artifacts and recompile, or edit application config with FxCop open, and then re-run it.

Most rules are configurable, so you can modify the prefixes and suffixes to suit your standards, or ignore any rules you don't care for. Save the project as a .FxCop file and you can integrate this into your build process using the MSBuild Community Tasks.

Development

There's potential for rules to cover a lot more than the "Naming" category. Certain of the recommendations in the BizTalk Performance Optimization Guide are candidates for a "Performance" category, and there are a few gotchas that could be avoided with warnings from a "Design" category. I'm not planning to add these for a while, but if you want to get involved let me know and I'll add you as a contributor.

FxCop runs over compiled assemblies, so introducing it to BizTalk meant for a few workarounds. If you want to extend BizTalkCop by adding new rules, there are a set of base classes which will help:

RuleBase – general base class for rules using normal introspection over classes; contains methods for determining if targets are maps, schemas etc;
ConfiguredRuleBase – base class for rules which have default setting values which can be overridden in the project file;
ApplicationRuleBase – base class for rules analysing BizTalk Applications; wraps the Explorer OM (so not good for 64-bit) to get the current config;
OrchestrationRuleBase – base class for analysing Orchestrations; typically the compiled code is too dense for analysis, so the base class exposes methods for accessing the shape and OM configuration. This is stored as XML in the compiled class, and the base class provides XPath helpers to access it.

The code for running the rule is quite straightforward, although tracking down the XML elements to check can be fiddly for orchestration rules (if you can find any schemas for the shape or OM XML, let me know and I'll modify it all to use entity classes). The source code contains a sample BizTalk project which fails all known rules, so you can add to this to check your own rules run as expected.

Quite possibly the CSD have something like this in place for the VS 2008 integration coming in BizTalk Server 2009. If not, it should be a trivial job to migrate these rules to run under VS, and in any case the ability to separate them out for running in the build should be useful.

I've run the rules over a few solutions and they've been accurate, but if you come across any issues, log them on CodePlex and I'll have a look.

SSO Config Tool

EltonStoneman — Mon, 30 Jun 2008 00:41:30 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The Enterprise Single Sign On database can function as a centralized configuration store, as well as an identity store, which is available to all BizTalk instances in a group, and also to custom .Net apps. For a clear explanation of the benefits and drawbacks of the EntSSO approach (and the alternative options), see Michael Stephenson's post Where do I store my custom configuration for a BizTalk solution.

Here I'll look at overcoming some of the practical issues in developing, deploying and maintaining config in an EntSSO store using another tool I've been using for a while and have recently put onto CodePlex: SSO Config Tool.

The original purpose was to codegen a strongly-typed configuration model that abstracted away the EntSSO store, and made read-only config values available from a static class for expressions:

- or .Net code:

//extract the UDDI config settings:

string uddiUrl = ConsolidatedGyroscope_App1Config.UDDIServerUrl;

uint uddiTimeout = ConsolidatedGyroscope_App1Config.UDDICacheTimeout;

So it does that (if you're looking for an app which just lets you manage SSO stores, have a look at Richard Seroter's Config Application Manager), and it also gives you:

a console app to generate the config, and to import/export between EntSSO and an XML config file
MSBuild task versions of the console functionality
a UI version of the console functionality, which also lets you maintain config settings:

There are a couple of things worth noting here.

Application Settings

These are all mandatory. The Groups specify who has access to read and update the config store settings. Groups must exist at the time you try and save the app to EntSSO, and they cannot be built-in groups or the "Everyone" group (not that you would…). The BizTalk groups are sensible options, so they're the default for the UI.

Fields

Field types are limited (by EntSSO) to one of the following built-in types:

String
Int32
UInt32
Boolean

The type you select will be emitted as the type of the property in the generated config model. Values are validated against the given type. The Masked option is a little misleading – all entries in EntSSO are encrypted, but if the field is defined as Masked in the config store then you can only retrieve it if you access EntSSO with a specific flag. The generated config model gives itself this permission, so the Masked value has no effect if you only use the config model.

XML

A custom schema is used so I can capture the expected field data type (rather than inferring it) – so it's similar but not compatible with the structure used by ssomanage.

Generated Code

The config model produced by SSOConfigTool uses a couple of helper classes in the SSOConfig namespace. When you generate the model, you can either generate the source code (so you'll have to add the SSOConfig assembly to your app as well as adding the C# class), or a compiled assembly (which contains the configuration model in your selected namespace, and the helper classes in SSOConfig, so you can use it on its own). The API (Microsoft.BizTalk.Interop.SSOClient) should be in the GAC.

Structure is quite basic – there's an SSOApplication class that represents the config store for an application, and the business of wrapping the EntSSO API is done in SSOHelper. The config class uses SSOApplication behind the scenes to get field values, and exposes them as the correct type. The class also exposes a CacheSSOAccess property which determines whether values are fetched from EntSSO on each call, or lazy loaded – it defaults to being lazy loaded (this is a static class so be aware of the thread implications if you're changing this value).

Some quirks with the EntSSO API are documented here:

For the config tool, the implication is that it creates a dummy field in the config app, but you won't see it unless you look in SSODB.

Usage

I've mainly used the UI to create the app in the EntSSO store, then used the MSBuild tasks to extract the app as XML and generate code from it. Alternatively you can use the build tasks to create the SSO store and/or generate code from a saved config file. The sample MSBuild files in the project show these uses.

Work Outstanding

Only a couple of things – firstly the SSO Config Tool (in its various guises) expects the EntSSO store to be available locally, so currently it doesn't allow you to run it from one machine to update SSO on another. The other one is more of an annoying niggle – if you try to open an SSO app from the UI, you'll probably find the dropdown list of available apps empty. This is down to ISSOMapper.GetApplications always returning an empty list, so until I work out why it thinks the user isn't entitled to view them, you'll need to type in the name of the app. Think of it as a security measure.