Soledad Pano's Blog

Media from Sharepoint to the Cloud

2012-01-22T22:44:00.000-03:00

On my last post I talked about a media processing component developed for Sharepoint 2010. Besides the processing features (video encoding, thumbnail generation, validations, etc…) there was an asset storage manager that enabled us to store the files on a configurable place, inside or outside Sharepoint. I said we initially started with three storage flavors: a Sharepoint library, an FTP server or a shared folder/virtual directory.

My co-worker Dwight Goins has extended the options by adding a cloud based storage manager. In this case he uses the Amazon Simple Storage Service (Amazon S3), which resulted in a great performing storage solution. In his post, he digs deeper in the issues of storing BLOBs (Binary Large Objects) in Sharepoint and the solution that Sharepoint provides, SQL’s Remote BLOB Storage (RBS). Then he talks about our solution and the details of the AmazonS3 client. Check this out!

Media Processing Component for Sharepoint

2012-01-12T14:33:00.000-03:00

I have been working recently on the task of building a media processing component for the Sharepoint project I am working on. The requirements for the component are more or less the following:

The Site Content Creators must be able to upload media assets (images, audio and video) to a Sharepoint list, and these assets must accomplish certain validation rules.
The final destination where the assets are saved after upload must be configurable and extensible. To begin with, we are supporting saving to a Sharepoint library, a network share or an FTP server.
The videos must be encoded to MP4 format, and thumbnail and poster images must be generated. The encoding process must be run asynchronously and the user must be notified by email when it is finished.

Today I want to share the design of the component and the key pieces of code. I will focus on the video upload process which is the more complex one because of the encoding. Audio and image uploads are more straightforward.
The main parts that build the solution are:

Custom Upload Process: This is the front end of the solution. It consists of a custom list with a custom upload form. The list has the link to the media file and more metadata fields (title, author, date, keywords, etc). When you click on create a new item on the list the custom upload form is opened and you can browse for a file to upload. The form has the required validation logic and it serves to save the assets to the configured location, which can be a Sharepoint library or an external location, like File System or FTP server. When the upload finishes you are redirected to the list item edit form so you can enter the metadata. The experience is similar to uploading a file to a Sharepoint document library.
Media Processing Backend Process: This consists of a timer job that queries the Media Assets list for items to process. It encodes the videos, generates thumbnail and poster images and uploads everything to the final destination. Finally, it notifies the user of the result of the process by email. For the video encoding we used the Microsoft Expression Encoder SDK. As I will explain later, this SDK cannot be used inside a Sharepoint process, so it runs in a separated process that is invoked from the timer job.
Storage Manager: this is a flexible and extensible component that abstracts the logic of saving (and deleting) a file to the final location depending on the flavor chosen thru configuration (File System, Sharepoint library or FTP). This component is used both by the front end upload mechanism and the back end media processing job.

Here is a diagram of the overall design for the video processing:

Now I will explain in a little more detail each component:

1. Custom Upload Process

The Media Assets List

This is a Sharepoint list that stores the metadata of the media assets, but not the asset itself (the assets are stored in the definite storage, which can be a Sharepoint assets library, a network shared folder, or an FTP server). The list is based on three custom content types, WebVideo, WebAudio and WebImage, all three inheriting from a base MediaAsset content type. This content type has the required fields for saving the asset metadata. The more important ones for the processing being:

Location: the URL of the asset in its definite location (in the example on the picture it is a sharepoint library called MediaAssetsLib).
Temp Location: As videos needs asynchronous processing, they are saved in a temporary location on upload. It is the timer job that uploads them to the definite location after encoding. The temp location is a shared folder on the network.
Processing Status: It is Success for assets successfully uploaded to the definite storage, Pending for assets waiting for encoding in the back end process and Error in case of encoding fail.

The list has an event receiver attached in order for deleting the assets from the final destination or temporary folder when the items are deleted from the list.
To achieve the storage flexibility, a custom upload form was developed and hooked to the MediaAssets list. When you click on the “Add new item” link of the picture above, the custom upload form is launched. The form is attached to the base content type definition in the Elements file as this:

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <!-- Parent ContentType: Item (0x01) -->
  <ContentType ID="0x01004e4f21afc14c487892253cb129dd5001"
               Name="MyMediaAsset" Group="MyContent Types"
               Description="My Media Asset" Inherits="TRUE"
               Version="0">
    <FieldRefs>    …    </FieldRefs>
    <XmlDocuments>
      <XmlDocument NamespaceURI="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms/url">
        <FormUrls xmlns="http://schemas.microsoft.com/sharepoint/v3/contenttype/forms/url">
          <New>_layouts/MyMedia/Upload.aspx</New>
        </FormUrls>
      </XmlDocument>
    </XmlDocuments>
  </ContentType>
</Elements>

The Upload Form

The form was created as an Application Page (Upload.aspx) in the Layouts folder. It contains the browse control to upload the file.

A useful tip here is how to achieve the same look and feel as the Sharepoint OOB forms. The InputFormSeccion, InputFormControl and ButtonSection controls were used for that matter.

In order to use these controls, you need to register the namespace on the top of the page:

<%@ Register TagPrefix="wssuc" TagName="ButtonSection" Src="/_controltemplates/ButtonSection.ascx" %>
<%@ Register TagPrefix="wssuc" TagName="InputFormSection" Src="/_controltemplates/InputFormSection.ascx" %>
<%@ Register TagPrefix="wssuc" TagName="InputFormControl" Src="/_controltemplates/InputFormControl.ascx" %>

And then include them in the page like this:

<wssuc:InputFormSection ID="InputFormSection1" runat="server"
      Title="Upload Document" Description="Browse to the media asset you intend to upload." >
  <template_inputformcontrols>
    <wssuc:InputFormControl runat="server" LabelText="" >
      <Template_Control>                   
        <div class="ms-authoringcontrols">
          Name: <br />
          <input id="FileToUpload" class="ms-fileinput" size="35" type="file" runat="server">    
          <asp:RequiredFieldValidator id="RequiredFieldValidator" runat="server" ErrorMessage="You must specify a value for the required field." ControlToValidate="FileToUpload"></asp:RequiredFieldValidator>
          <br />
          <asp:RegularExpressionValidator id="FileExtensionValidator" runat="server" ErrorMessage="Invalid file name." ControlToValidate="FileToUpload"></asp:RegularExpressionValidator>
          …                                                                         
        </div>
      </Template_Control>
    </wssuc:InputFormControl>
  </template_inputformcontrols>
</wssuc:InputFormSection>

You can read more about how to use these controls here.

So, what happens in the code behind?

On the OK button submit handler, the file to upload is processed. The logic is different depending on the asset type. Images are copied to the final destination by using the Storage Manager. A thumbnail is also generated and uploaded for them. Duration is calculated for Audio and Video files (Microsoft.WindowsAPICodePack API is used for that). Audio files are also copied to the final destination. Videos instead are leaved in a temporary storage (a network shared folder), because they need to be processed later by the timer job.

In all three cases, a list item is created with the asset metadata, and inserted into the MediaAssets list. Then the user is redirected to the list item Edit form, so he can complete filling the rest of the metadata.

Since the upload process may take a long time, all this happens in the context of an SPLongOperation. This is a Sharepoint class provided to display the “Processing…” dialog with the rotating gear image in it.

Here is part of the code:

protected void btnOk_Click(object sender, EventArgs e)
{
    if (FileToUpload.PostedFile == null || String.IsNullOrEmpty(FileToUpload.PostedFile.FileName))
        return;     //FileToUpload is the HtmlInputFile control
    var originFileInfo = new FileInfo(FileToUpload.PostedFile.FileName);
    SPWeb web = SPContext.Current.Web;
    try
    {
        //create a MediaAsset object to save all asset metadata
        MediaAsset asset = MediaAsset.FromFile(originFileInfo, web.Url, mediaConfig);
        //start long operation to show the user the "Processing..." message
        using (SPLongOperation longOperation = new SPLongOperation(this.Page))
        {
            longOperation.Begin();

            string newFileUniqueName = String.Concat(Guid.NewGuid().ToString(), originFileInfo.Extension);

            SPSecurity.RunWithElevatedPrivileges(delegate()
            {
                //save to file system. Need to elevate privileges for that
                var tempFileInfo = new FileInfo(Path.Combine(mediaConfig.TempLocationFolder, newFileUniqueName));
                FileToUpload.PostedFile.SaveAs(tempFileInfo.FullName);

                asset.TempLocation = tempFileInfo.FullName;
                asset.Duration = MediaLengthCalculator.GetMediaLength(tempFileInfo);
                ...
            });
            
            var list = web.Lists[mediaConfig.MediaAssetsListName];
            int id;
            string contentTypeId;
            //insert new item in the MediaAssets list
            mediaRepository.Insert(list, asset, out id, out contentTypeId);
            //build url of Edit Form to redirect 
            string url = String.Format("{0}?ID={1}&ContentTypeId={2}", list.DefaultEditFormUrl, id, contentTypeId);
            //long operation ends, redirecting to the Edit Form of the new list item
            longOperation.End(url);
        }
    }
    catch (ThreadAbortException) { /* Thrown when redirected */}
    catch (Exception ex)
    {
        logger.LogToOperations(ex, Categories.Media, EventSeverity.Error,
            "Error uploading file to MediaAssets list. FileName: '{0}'.", originFileInfo.Name);

        SPUtility.TransferToErrorPage(ex.Message);
    }
}

Ok, now let’s see how the asynchronous processing part works.

2. Media Processing Backend Process

The backend process consists of a Sharepoint Timer Job that orchestrates the video processing and a console application that performs the actual encoding and generate the images. The console application is invoked by the timer job.

Encoder Console Application

The tool chosen for encoding videos was Microsoft Expression Encoder 4. We used the Pro version (paid) which includes support for H.264 (this means can encode videos to mp4 format as required by our client).

The encoder comes with an SDK, so you can programmatically encode your videos. The thing is that this API depends upon .Net Framework 4.0, and it is also 32-bit only. This is incompatible with a Sharepoint process (either web or timer job), since Sharepoint relies upon .Net 3.5 and runs in 64 bits. Hence the need to build a separate process outside of the Sharepoint Timer Job. The console application was a simple solution, and it could be configured to target .Net Framework 4.0 and x86 Platform.

This application expects four input parameters: the path to the original video, the desired path for the thumbnail image to generate, the desired path of the poster image to generate and the desired path of the encoded video to generate.

The Encoder SDK provides full flexibility for setting the encoding parameters (like format, size, bitrate, etc). It also provides a set of presets, that let’s you implement the encoding very easily. For example, here is the code for encoding using the H264VimeoSD Preset:

public void EncodeVideo(FileInfo inputFile, FileInfo outputFile)
{
    Microsoft.Expression.Encoder.MediaItem mediaItem = new MediaItem(inputFile.FullName);
    int bitrate = GetBitrate(mediaItem);

    using (Microsoft.Expression.Encoder.Job job = new Job())
    {
        job.OutputDirectory = outputFile.Directory.FullName;
        job.CreateSubfolder = false;
        job.MediaItems.Add(mediaItem);
        //H264VimeoSD preset settings: Output Format: MP4. Container: MP4. Video Codec: H.264 - Main. 
        //Video size: 640, 480. Video Bitrate: 2500 Kbps. Video Encoding: CBR SinglePass. 
        //Audio Codec: AAC. Audio Channels: Stereo. Audio Bitrate: 128 Kbps. Audio Encoding: CBR Single Pass
        job.ApplyPreset(Microsoft.Expression.Encoder.Presets.H264VimeoSD);
        job.Encode();
    }
}

And here is the code for generating the thumbnail or poster images:

public void GenerateVideoImage(FileInfo mediaFile, string imageFilePath, int width, int height)
{
    var video = new MediaItem(mediaFile.FullName);
    using (var bitmap = video.MainMediaFile.GetThumbnail(
        new TimeSpan(0, 0, 5),
        new System.Drawing.Size(width, height)))
    {
        bitmap.Save(imageFilePath, ImageFormat.Jpeg);
    }
}

Media Processing Timer Job

Sharepoint supports asynchronous processing of data through Timer Jobs. These jobs run within the context of a windows service, and are easily managed and deployed using the same tools as any other Sharepoint solution.

As the requirement was to run the job only in one of the application servers, it inherits from SPServerJobDefinition. Here is the Timer Job code:

public class MediaProcessingTimerJob: SPServerJobDefinition { 
    private Logger logger = new Logger(); 

    public MediaProcessingTimerJob() : base() 
    { 
    } 
        
    public MediaProcessingTimerJob(string name,SPServer server):base(name,server) 
    { 
        this.Title = "MediaProcessingTimerJob"; 
    } 

    public override void Execute(SPJobState jobState) 
    { 
        string webUrl = String.Empty; 
        try 
       { 
            webUrl = this.Properties["webUrl"].ToString(); 
            var mediaProcessor = new MediaProcessor(webUrl, MediaConfig.FromConfigRepository(webUrl)); 
            mediaProcessor.ProcessMedia(); 
        } 
        catch(Exception ex) 
        { 
            logger.LogToOperations(ex,TRSCategories.Media, EventSeverity.Error, "Error executing MediaProcessingTimerJob in web '{0}'", webUrl); 
        } 
    } 
}

During the deployment process, the MediaProcessingTimerJob is installed on the required server. The URL of the website for processing the assets are passed thru the job properties.

Here is part of the code of the helper tool that installs the job and sets it to run every 15 minutes:

private static void CreateMediaJob(string webUrl,SPServer server)
{
    var job = new MediaProcessingTimerJob("my-job-media-processing", server);
            
    job.Properties.Add("webUrl", webUrl);
            
    var schedule = new SPMinuteSchedule();
    schedule.BeginSecond = 0;
    schedule.EndSecond = 59;
    schedule.Interval = 15;
    job.Schedule = schedule;
    job.Update();
}

The logic of the timer job resides in the MediaProcessor::ProcessMedia method. It essentially queries the Media Assets List for assets in the “Pending” status and for each of these items it invokes the Encoder process and then uploads the resulting mp4 video and the generated thumbnail and poster images to the final destination. Finally it notifies the user of the result by email.

This is the code that the job uses to call the console application. Since the job tells the console application the output parameters (the path to the images and encoded video files), it doesn’t need to read any output from the console application. It must only read the standard error in case the console application fails.

private void ExecuteMediaProcess(string inVideoPath,string outThumbnailPath, string outPosterPath,string outVideoPath)
{
    string args = String.Format("\"{0}\" \"{1}\" \"{2}\" \"{3}\"", inVideoPath, outThumbnailPath, outPosterPath, outVideoPath);

    ProcessStartInfo startInfo = new ProcessStartInfo(config.EncoderExePath);
    startInfo.Arguments = args;
    startInfo.CreateNoWindow = true;
    startInfo.UseShellExecute = false;
    startInfo.RedirectStandardError = true;
    startInfo.RedirectStandardOutput = true;

    Process process = new Process();
    process.StartInfo = startInfo;
    process.Start();
    string error = process.StandardError.ReadToEnd();
    process.WaitForExit(MaxWaitingProcessMillisecs);

    if (process.ExitCode != 0)
    {
        //the application failed, get error from message from standard error
        throw new MediaProcessingException(String.Format("Video encoder process returned with exit code '{0}'. Error was: '{1}'",
            process.ExitCode, error));
    }
}

3. Storage Manager

The Storage Manager is the piece of code used by both the upload media form and the backend process. It is just a file manager used for abstracting from the actual destination of the files, which is configurable. As I said, we started supporting saving assets to File System, to a Sharepoint library or to an FTP server, but this can be further extended to support other places, like some storage on the Cloud.

The need for a flexibility in the location to store the files may come from bandwidth or space limitations, for a need to share assets with other applications or a need to manage a centralized file store.

Anyway, the interface is very simple:

public interface IAssetStorageManager{
    void Delete(string fileUrl);
    string Save(System.IO.FileInfo file);
    string Save(string fileName, System.IO.Stream fileStream);
}

There is a factory that will give you the particular storage manager framework depending on configuration (all configuration is saved in a Sharepoint list, and the Sharepoint Config Store is used for retrieving it). Here is part of the factory code:

public class AssetStorageFactory{    …
    static public IAssetStorageManager GetStorageManager(string configCategory,string webUrl)
    {
        var configHelper = new ConfigHelper(webUrl);
        string storageMethod = configHelper.GetValue(configCategory, StorageMethodConfigKey);
        if ("SPLibrary".Equals(storageMethod, StringComparison.InvariantCultureIgnoreCase))
        {
            return new SPLibraryAssetStorageManager(webUrl, mediaLibraryName);
        }
        else if ("FileSystem".Equals(storageMethod, StringComparison.InvariantCultureIgnoreCase))
        {
            return new FileSystemAssetStorageManager(storageFolderPath,storageBaseAddress);
        }   
        else if ("FTP".Equals(storageMethod, StringComparison.InvariantCultureIgnoreCase))
        {
            return new FTPAssetStorageManager(ftpServerUrl,ftpServerPullAdress,ftpServerUsername,ftpServerPassword);
        }
        throw new ArgumentException(String.Format("Incorrect configuration Value '{0}' in ConfigStore for category '{1}' and key '{2}'. Supported options are: '{3}'",
            storageMethod, configCategory, StorageMethodConfigKey, "FileSystem|FTP|SPLibrary"));
    }       
}

The implementation for a particular flavor is simple. For example, this is how the FTPAssetStorageManager saves a file stream:

public string Save(string fileName, System.IO.Stream fileStream)
{
    string fileUrl = ftpServerUrl + fileName;
    FtpWebRequest request = (FtpWebRequest)WebRequest.Create(fileUrl);
    request.Method = WebRequestMethods.Ftp.UploadFile;
    request.Credentials = new NetworkCredential(username, password);
    using (Stream ftpStream = request.GetRequestStream())
    {
        FileUtils.CopyStream(fileStream, ftpStream);
    }
    return pullBaseAddress + fileName;
}

And this is how the storage manager is invoked from the Upload form or the Timer Job:

//save to final locationIAssetStorageManager storage = AssetStorageFactory.GetStorageManager("Media", web.Url);
asset.Location = storage.Save(newFileUniqueName, fileInputStream);

Conclusion

Having talked about the most important parts of the Media Processing Component for Sharepoint, I think I’m done here. The code is too much to show everything in a post, but I’ve chosen the most important parts. I might dig deeper in some other post. I will probably write about how to display videos in a web page, too.

The interesting part is that even if this whole component doesn’t apply to another project, maybe some of its pieces can be reused, like the video encoding thing, or the custom upload form and storage manager to save files outside Sharepoint. So I hope it results useful to someone else!

Sharepoint Upload File Error: ‘The remote server returned an error: (409) Conflict’

2011-12-15T09:42:00.001-03:00

I’ve been using the following code to upload a file to a Sharepoint document library using the Client Object Model:

Code Snippet
 public string Save(string fileName, Stream fileStream)
        {
            string destinationUrl = String.Concat(serverRelativeLibraryUrl, "/", fileName);
            ClientContext clientContext = new ClientContext(webUrl);
            {
                Microsoft.SharePoint.Client.File.SaveBinaryDirect(clientContext, destinationUrl, fileStream, true);
            }
 
            return destinationUrl;
        }

where
serverRelativeLibraryUrl = String.Concat(webRelativeUrl, libraryName);

But I kept getting the 409 Conflict Error:
ExceptionType: 'WebException' ExceptionMessage: 'The remote server returned an error: (409) Conflict.'   StackTrace: '
at System.Net.HttpWebRequest.GetResponse()
at Microsoft.SharePoint.Client.SPWebRequestExecutor.Execute()
at Microsoft.SharePoint.Client.File.SaveBinary(ClientContext context, String serverRelativeUrl, Stream stream, String etag, Boolean overwriteIfExists, SaveBinaryCheckMode checkMode)
at Microsoft.SharePoint.Client.File.SaveBinaryDirect(ClientContext context, String serverRelativeUrl, Stream stream, Boolean overwriteIfExists)

After struggling for a while, I figured out that the problem was the library name. It contained a dash on it, like “My-LibraryName”. When I renamed it without the dash it started working.

The error in the code is how I built the URL. I was using the library name to build the library URL, but it seems that Sharepoint doesn’t like some characters in the URL, so when you create a library called “My-LibraryName”, the URL is actually http://<server>/MyLibraryName, without the dash.

Technorati Tags: Sharepoint

Sharepoint @ Buenos Aires Codecamp 2011

2011-09-21T00:43:00.001-03:00

BA Codecamp 2011 is coming soon and Tellago is going to be part of it! More than 10 architects from our team will be presenting the most innovative technology sessions on next October 15. I’m very happy to be speaking at this event! Along with my colleague Mariano Escurra, we will be presenting Best Practices using Javascript and JQuery in Sharepoint 2010. Bellow is the abstract. Register!!

Mejores prácticas utilizando Javascript y JQuery en SharePoint 2010
El uso de Javascript es una parte importante en la construcción de cualquier sitio web interactivo, siendo JQuery una de las bibliotecas Javascript más utilizadas. Al crear este tipo de sitios sobre SharePoint 2010, los desarrolladores pueden combinar el uso esta biblioteca con el modelo de objetos cliente Javascript (ECMAScript) mejorando notablemente la experiencia del usuario final.
Durante esta charla abordaremos los aspectos más importantes del modelo de objetos cliente ECMAScript de SharePoint 2010 y su integración con JQuery siguiendo las mejores prácticas.

Fixing Sharepoint’s “Cannot connect to the configuration database” error

2011-06-17T10:35:00.001-03:00

I have Sharepoint Server 2010 installed in my development environment. It happened a couple of times that the computer hangs and the Sharepoint Configuration dabatase remains in a corrupted state. When I try to access the Sharepoint local site from the browser it gives the following error:

Cannot connect to the configuration database.

Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.
Exception Details: Microsoft.SharePoint.WebPartPages.WebPartPageUserException: Cannot connect to the configuration database.

So, how did I fix it?

I first used this addselftosqlsysadmin.cmd script to add my account to the SQLServer sysadmin group.

Then performed the following commands from SQL Server Management Studio:

select state_desc from master.sys.databases where name = 'SharePoint_Config_5ffca14b-db6f-4b30-9dd8-8317ee0f4f45'

The result was: SUSPECT, confirming we had a problem.

Then run:

ALTER DATABASE [SharePoint_Config_5ffca14b-db6f-4b30-9dd8-8317ee0f4f45] SET EMERGENCY;

ALTER DATABASE [SharePoint_Config_5ffca14b-db6f-4b30-9dd8-8317ee0f4f45] SET SINGLE_USER;

DBCC CHECKDB ([SharePoint_Config_5ffca14b-db6f-4b30-9dd8-8317ee0f4f45] , REPAIR_ALLOW_DATA_LOSS) WITH NO_INFOMSGS, ALL_ERRORMSGS;

ALTER DATABASE [SharePoint_Config_5ffca14b-db6f-4b30-9dd8-8317ee0f4f45] SET MULTI_USER;

That’s it! I run the state_desc command again and this time it says: ONLINE

Solved!

Azure Bootcamp @MS Argentina

2011-04-01T10:25:00.000-03:00

I participated yesterday in the Azure Bootcamp that took place at Microsoft Argentina. Along with Vanesa Guccione, my colleague at Lagash, we talked about advanced roles. The contents of the presentation included the new features of the platform, such as full IIS mode, startup tasks, remote desktop plugin and local storage. We also talked about input and internal endpoints and inter-role communication, showing some demo code as well. You can download the material from here.

How to find Visual Studio command bars

2008-10-07T11:08:00.001-03:00

When developing a Visual Studio Addin it is a common task to add custom commands to existing menus and toolbars. It is a common problem too, not to find the proper command bar (we have to traverse all command bars to see its names, the names are not unique, etc). In these two posts: Using IVsProfferCommands to retrieve a Visual Studio CommandBar and Using EnableVSIPLogging to identify menus and commands with VS 2005 + SP1 it is very well explained how to solve this problem.

The answer relies on the fact that every toolbar and menu is uniquely identified in Visual Studio by a ...

Read full article

CodeCamp Buenos Aires 2008

2008-10-05T11:14:00.001-03:00

I attended yesterday to the Microsoft Code Camp event at Buenos Aires. It was fun!

Here's a picture of the Lagash stand:

Read full article

UI Automation Article Published on Level Extreme

2008-03-12T15:40:00.005-02:00

On this month's edition of the Level Extreme .Net Magazine, my article about Building an UI Automation Client Application was published. The article walks through building a client application for automating a win 32 target application (the Windows Address Book). The idea is to show through simple code snippets how to use the UI Automation API for manipulating a target application programmatically through its UI. It shows how to find the UI elements, and how to work with the UI Automation patterns and handle events. The sample client application code contains further examples and can be downloaded from the article's page. Hope you read it!

Read more on the magazine from Martin Salias.

CCF: Listening to External Application Events

2008-01-15T13:09:00.001-02:00

It is often necessary to listen to external application UI events when automating applications in CCF. For example, we may need to save a value in the Context if the user presses a button, or do something when an alert dialog appears. There are many ways we can handle events. In CCF 2008, the Hosted Application Toolkit (HAT) provides an easy way to listen to them. If not using HAT we can hook to events using the UIAutomation or MSAA (Microsoft Active Accessibility) APIs within our own application adapters....

Read full article

Hosting a Window Form Control in a SharePoint WebPart

2007-12-06T22:48:00.001-03:00

Some months ago I posted about Hosting a Windows Form Control in a web page. I explained there how we can run a WinForm control from Internet Explorer by hosting it in a web page using the <object> tag. Now suppose you want to use the same solution in a custom web part that is included in a Sharepoint site. I will describe here where the control library should be placed and how it can be referenced from the web part.

When we develop a custom web part, we place its resources under the _wpresources web site, into a folder named <WebPartAssemblyName>/<WebPartAssemblyVersion>__<PublicKeyToken>. You can create there a subfolder (named "bin" por example) to place the win control assembly. This folder must have execute permissions set to Script Only (not Script and Executables as is the default under a SharePoint site). The picture bellow shows the resulting structure when placing the win form control assembly in a web part called MyCustomWebPart that is part of the MyCustomWebParts assembly: ...

Read full article

CCF HAT - Making use of DDAs from Legacy Adapters

2007-10-30T22:35:00.001-03:00

Although Data Driven Adapters (DDAs) are mainly designed for Automation Adapters in HAT, we can make use of them from legacy adapters, too. Here's an example of an external VB application, which is configured to use a legacy application adapter and a WinDataDrivenAdapter with the corresponding bindings:

<?xml version="1.0" encoding...

Read full article

CCF 2008 Hosted Application Toolkit

2007-10-26T00:40:00.001-03:00

The Hosted Application Toolkit (HAT) is a new component of CCF 2.6 (2008) that facilitates the task of automating the UI of the hosted applications. It consists of two main parts: the Data Driven Adapters (DDA) and the Automations (WF workflows) that automates the hosted application using the DDAs.

Data Driven Adapters

DDAs must inherit from DataDrivenAdapterBase in Microsoft.Ccf.HostedApplicationToolkit. CCF supports two implementations out of the box: WinDataDrivenAdapter and WebDataDrivenAdapter. We can inherit from any of the three to extend the DDA as necessary. The methods the DDAs expose to manipulate the hosted application UI are ExecuteControlAction, FindControl, GetControlValue and SetControlValue. These methods take a friendly name as parameter and lets the application adapters interact with the hosted application UI abstracting from the details of how to obtain the control from that friendly name. The mapping between the controls' friendly names and the directions for the DDA to finding them is called Data Driven Adapter Binding and is part of the hosted app initialization string:...

Read full article

Silverlight article published this month

2007-10-08T10:12:00.001-03:00

My colleagues Ariel Neisen, Federico García, Rodolfo Finochietti and I wrote the cover article of the #42 edition of the .Code Magazine (in Spanish) about Silverlight. The article talks about this new technology's fundamentals, architecture, programming tools, advanced features, code samples and a lot more.

Choosing the right WCF binding

2007-10-01T23:49:00.001-03:00

A WCF binding is the endpoint component that defines how the client needs to communicate with the service. It groups settings such as underlying transport protocol, security requirements, and message encoding.

WCF provides nine built-in bindings:

BasicHttpBinding: Basic web service communication. Exposes WCF services as legacy ASMX web services. Used for interoperability. No security by default.
WSHttpBinding: Web services with WS-* support. Supports transactions and reliable messaging.
WSDualHttpBinding...

Read full article

CCF 2008 New Features

2007-09-28T14:01:00.001-03:00

The 3.0 version of the Customer Care Framework (CCF) is out! Among its new features we'll find:

CCF web services migrated to Windows Communication Foundation (WCF).
Agent Desktop use of Composite Application Block (CAB).
Hosted Application Toolkit (HAT): new sub-system for providing UI automation, that makes use of Workflow Foundation (WF) and Active Accessibility.
ClickOnce support.
Dynamic Applications: 3rd category of hosted applications that allow an agent to dynamically launch or close a hosted application on-demand, via the UI or programmatically in code. ...

Read full article

Hosting a Windows Form Control in a web page

2007-09-28T00:26:00.001-03:00

Although it is not the most common use of it, it is possible to host a Windows Form Control in a Web Page and run it from within Internet Explorer. This allows to build powerful client side functionality with all the advantages of using the .Net framework and executing the control in the client side. Of course there are some restrictions that cannot be left aside. At least the .Net framework must be installed on the client for the control to run. In addition, it is possible that some permission must...

Read full article

WPF Accessibility

2007-09-28T00:24:00.001-03:00

Windows Presentation Foundation (WPF) provides a very interesting API for Accessibility called Microsoft UI Automation. It allows programmatic access to most user interface elements on the desktop, addressing the needs of assistive technology products and also for User Interface (UI) tests automation.

The framework provides solutions for both accessibility providers and clients, and it is conformed of four main components (see UI Automation Overview):

The Provider API (UIAutomationProvider.dll and UIAutomationTypes.dll) defines a ...

Read full article

Also blogging @ weblogs.asp.net

2007-09-28T00:17:00.001-03:00

Earlier this month I opened an account to start blogging at weblogs.asp.net. I moved the latest contents from here to there, and I will be cross-posting future entries to have both blogs synchronized. Check it out: http://weblogs.asp.net/spano/.

Working around VSTO SE's lack of document-customization for Excel 2007

2007-06-10T20:42:00.001-03:00

I've been doing some research on Visual Studio Tools for Office (VSTO) and Excel 2007 recently and found out that some very interesting features available in previous versions of VSTO for Excel 2003 are not available for Excel 2007. Here's a summary of the current situation and the workarounds I figured out.

State of the Art

VSTO has basically two kinds of Excel add-ins: document-level customization an application-level add-ins.

The document-level customization lets you customize an Excel workbook and also reference the Application to add buttons to the command bar and so forth. The resulting add-in will be only available to the customized workbook. The great benefit of document-level customization is that you can add controls to the spreadsheets within Visual Studio, being these controls part of the VSTO object model. The VSTO objects are wrappers around the Interop ones and they add very interesting functionality, like events and databinding. The VSTO controls are in the Microsoft.Office.Tools.Excel namespace whereas the Interop ones are in Microsoft.Office.Interop.Excel.

Document-level customization project template

Document-level customization project

On the other and, an application-level add-in is, as its name implies, always visible for the host Application regardless of the opened workbook. The only class added by Visual Studio is the TheAddin one, no workbook or worksheet editors are provided. The VSTO controls are not available neither. All Excel objects that we can get access through TheAddin class are from the Microsoft.Office.Interop.Excel API.

Application-level add-in project template

Application-level add-in project

The problem is that, whereas document-level customization is available for Excel2003, is not yet available for Excel 2007. So, the spreadsheet editor is not available within Visual Studio and the VSTO extended controls cannot be used. The table below shows which kinds of add-in are available for each product combination (see Features available by product combination for the complete table listing all Office applications).

VSTO 2005 or Visual Studio Team System

VSTO 2005 SE installed with VSTO 2005 or Visual Studio Team System

VSTO 2005 SE installed with Visual Studio 2005 Professional Edition

Document-level customizations

Excel 2003

Not available

Application-level add-ins

Not available

Excel 2003

Excel 2007

Excel 2003

Excel 2007

Workarounds

In order to make a document-level customization (or at least something similar) to target Excel 2007 I found out that some of the following things can be done:

1- Develop for Excel 2003 and deploy in Excel 2007

It is possible to develop a document-level customization in Visual Studio for Excel 2003 using VSTO 2005. The resulting customized document can then be opened in Excel 2007 in compatibility mode with the same functionality. The drawbacks of this approach is that Excel 2003 needs to be installed in the developer's machine and that you won't have Office 2007 features like custom panes and ribbon extensibility available.

2- Develop for Excel 2007 with VSTO SE and try to emulate the document-level customization.

In order to target Excel 2007, VSTO SE is needed and the only option by the moment is to create an application level add-in. For emulating the document customization you can create an Excel's template file within Excel application, add the desired named ranges, tables, graphics, etc...and then access these controls trough the add-in's code to make custom automation. The drawback of this approach is that the extended functionality of VSTO's controls is not available. For example, you won't be able to use the ListObject databinding support. In order to access the workbook controls, the Interop API must be used. Another drawback, is that the Interop API is not as well documented as the VSTO's.

3- Develop an application-level add-in for Excel 2007 and create the VSTO's objects from code.

Actually I'm not sure wheter this is really a choice, since I couldn't make it work. What I tried here was to create a new instance of a VSTO worksheet to wrap an Interop worksheet. In ThisAddin class I have the following code:

 
using Excel = Microsoft.Office.Interop.Excel;
using Vsto = Microsoft.Office.Tools.Excel;
 
namespace ExcelAddIn1
{
    public partial class ThisAddIn
    {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
            #region VSTO generated code
 
            this.Application = (Excel.Application)Microsoft.Office.Tools.Excel.ExcelLocale1033Proxy.Wrap(typeof(Excel.Application), this.Application);
 
            #endregion
 
            try
            {
                Excel.Worksheet newSheet = (Excel.Worksheet)this.Application.ActiveWorkbook.Worksheets.Add(Type.Missing, Type.Missing, Type.Missing, Type.Missing);
                Microsoft.Office.Tools.Excel.Worksheet extendedSheet = GetExtendedWorksheet(newSheet);
                extendedSheet.Controls.AddNamedRange(extendedSheet.Range["A1","C2"], "NamedRange");
            }
            catch (Exception ex) {
                MessageBox.Show(ex.ToString());
            }
        }
 
        private Vsto.Worksheet GetExtendedWorksheet(Excel.Worksheet nativeWorksheet)
        {
            //Get the IHostItemProvider instance.
            Microsoft.VisualStudio.Tools.Applications.Runtime.IHostItemProvider hostItemProvider = (Microsoft.VisualStudio.Tools.Applications.Runtime.IHostItemProvider)
                RuntimeCallback.GetService(typeof(Microsoft.VisualStudio.Tools.Applications.Runtime.IHostItemProvider));
            //Create the new worksheet and return it to calling function.
            return new Vsto.Worksheet(hostItemProvider, RuntimeCallback, nativeWorksheet.CodeName,
               null, nativeWorksheet.Name);
        }

But, when trying to add the NamedRange to the extended worksheet this Exception is thrown:

This document might not function as expected because the following control is missing: Sheet4. Data that relies on this control will not be automatically displayed or updated, and other custom functionality will not be available. Contact your administrator or the author of this document for further assistance.
at Microsoft.Office.Tools.Excel.Worksheet.GetObjects()
at Microsoft.Office.Tools.Excel.Worksheet.GetPrimaryControl()
at Microsoft.Office.Tools.Excel.Worksheet.get_Range()
at ExcelAddIn1.ThisAddIn.ThisAddIn_Startup(Object sender, EventArgs e) in C:\...\Projects\ExcelAddIn1\ExcelAddIn1\ThisAddIn.cs:line 26

Conclusion

Although VSTO's document-level customization is not available for Excel 2007 yet, there still are some choices for developing add-ins targeting this application version. Besides, the good news is that this lack will be supplied soon. VSTO "Orcas" will provide document-level customization for Excel 2007 within its new features. So, anyway, it's just a matter of time...

Developing a Custom Property Comparison Validator using Entlib's VAP

2007-05-16T14:03:00.001-03:00

Here's a sample scenario where, in an application using Entlib's Validation Application Block (VAP), the validation of an entity's member depends on the value of another property. In this case the entity I want to validate has two properties. Using the attributes approach to support validation, the entity's code looks like this:

public class MyEntity
{
    private string myVar1;
 
    [NotNullValidator()]
    [StringLengthValidator(0, 20, MessageTemplate = "MyProperty1 must be less than 20 characters length")]
    public string MyProperty1
    {
        get { return myVar1; }
        set { myVar1 = value; }
    }
 
    private string myVar2;
 
    [MyProp2Validator()]
    public string MyProperty2
    {
        get { return myVar2; }
        set { myVar2 = value; }
    }
}

The validators for Property1 are built in validators, no big deal with that. The thing here is that I want the second property to be validated against the value of the first one. Let’s say, for example, that Property2 is valid if it begins with the value of Property1.

Although the VAP ships with a PropertyComparisonValidator, it is limited to comparisons of type =, !=, >, >=, <>. So it seems that a custom validator has to be made. But how to obtain the actual value of Property1 from the Property2's custom validator?

One approach is to use reflection. Using reflection the DoValidate method of MyProperty2Validator would look something like this:

protected override void DoValidate(string objectToValidate, object currentTarget, string key, ValidationResults validationResults){
    //obtain the other property value through reflection
    PropertyInfo prop = currentTarget.GetType().GetProperty("MyProperty1");
    string myProp1Value = prop.GetValue(currentTarget, null) as string;
    //some custom logic here
    if (! objectToValidate.StartsWith( myProp1Value ){
        LogValidationResult(validationResults,"msg",currentTarget,key);
    }
}

But the dropdown of using reflection is that it wouldn't work with UI integration.

What do work with integration is what the built-in PropertyComparisonValidator does, and that is using the ValueAccess class. The ValueAccess class allow us to find other members in an integration friendly way throuhg its GetValue method. See how this is done in our Property2 valdiator:

[ConfigurationElementType(typeof(MyProp2ValidatorData))]
class MyProp2Validator : Validator<string> {
    private ValueAccess valueAccess;
    internal const string OtherPropName = "MyProperty1";
 
    public MyProp2Validator(ValueAccess valueAccess):base (Resources.MyProp2ValidatorMessageTemplate,null){
        this.valueAccess = valueAccess;
    }
 
    protected override void DoValidate(string objectToValidate, object currentTarget, string key, ValidationResults validationResults){
        object myProp1;
        string valueAccessFailureMessage;
        //try to obtain the value of property 1.
        if (!this.valueAccess.GetValue(currentTarget, out myProp1, out valueAccessFailureMessage)) {
            base.LogValidationResult(validationResults, string.Format(CultureInfo.CurrentUICulture, Resources.MyProp2ValidatorFailureToRetrieveProp1, new object[] { this.valueAccess.Key, valueAccessFailureMessage }), currentTarget, key);
        }
        else {
            //custom validation logic between prop1 and prop2
            if (!objectToValidate.StartsWith((string)myProp1)) { 
                base.LogValidationResult(validationResults, string.Format(CultureInfo.CurrentUICulture, this.MessageTemplate, new object[] { objectToValidate, myProp1 }), currentTarget, key);
            }
        }
    }
 
    protected override string DefaultMessageTemplate {
        get { return Resources.MyProp2ValidatorDefaultMessageTemplate; }
    }
}

What’s left is to provide the ValueAccess to the validator’s constructor. This is done in the MyProp2ValidatorAttribute class, if using attributes to place validators, or in the MyProp2ValidatorData if using configuration files. MyProp2ValidatorAttribute would look like this:

public class MyProp2ValidatorAttribute : ValueValidatorAttribute
{
    protected override Validator DoCreateValidator(Type targetType)
    {
        throw new InvalidOperationException("A member value access builder is needed.");
    }
 
    protected override Validator DoCreateValidator(Type targetType, Type ownerType, MemberValueAccessBuilder memberValueAccessBuilder)
    {
        PropertyInfo propertyInfo = ownerType.GetProperty(MyProp2Validator.OtherPropName);
        if (propertyInfo == null)
        {
            throw new InvalidOperationException(String.Format(Resources.MyProp2ValidatorAttributeCouldNotFindProperty, new string[] { ownerType.Name, MyProp2Validator.OtherPropName }));
        }
        return new MyProp2Validator(memberValueAccessBuilder.GetPropertyValueAccess(propertyInfo));
    }
}

Finally, you can test the validation logic using the following code:

private void buttonValidate_Click(object sender, EventArgs e)
{
    MyEntity ent = new MyEntity();
    ent.MyProperty1 = textBoxProp1.Text;
    ent.MyProperty2 = textBoxProp2.Text;
    ValidationResults r = Validation.Validate<MyEntity>(ent);        
    if (!r.IsValid)
    {
        DisplayValidationResults(r);
    }
    else {
        MessageBox.Show("ok");
    }
}

It's only left to provide the UI integration for the custom validator to assure averything's working right. I hope to be posting this in a second part soon.

Workflow Foundation conference's material

2007-04-16T12:27:00.000-03:00

The material (powerpoint presentation and code samples) of the Introduction To Workflow Foundation conference is now available for download.

Sign up in the WF's conference @ MS Argentina

2007-03-20T13:03:00.000-03:00

On Thursday the 12^th (from 9 am to 1 pm) I will take part in the “Introduction to Windows Workflow Foundation” conference given at Microsoft Argentina, along with Diego Gonzalez (MVP) and Jorge Fioranelli.

Here is the conference abstract:

“Between the new technologies included in the recently released .Net Framework 3.0, we found Windows Workflow Foundation, which consists on the most innovating tool set included in this new framework’s version. The possibility of extracting the workflow concept from the applications as a reusable and extensible element is an extremely innovating aspect in terms of application design. Tools are also included that let you visually edit workflows, enabling analysts and users without programming knowledge to extend applications with a minimum impact in the whole application.

The conference will consist on an introduction to the technology, showing its main characteristics, a demonstration of its more relevant advanced aspects, and will end with two examples of real projects where Windows Workflow Foundation has been used in combination with other technologies to solve common issues.”

You can see the details and sign up here.

See you there!

Environmental Overrides

2007-03-17T19:31:00.000-03:00

February 2007 CTP of Enterprise Library 3.0 includes a very cool feature called "Environmental Overrides". This feature provides the capability of defining different environments in your application's configuration, and overriding some of the configuration settings in these environments. This is very useful in common scenarios, such as having different connection strings in development, testing and production. For a more detail explanation of how this works, read here, directly from its creator.

The tool sounded very promising to me, but pitifully, I couldn't make it work. I found the following two issues:

When I generate the merged file for one environment (by clicking the "Save merged configuration" item of its context menu), the resulting file do not have the property's value overridden. This is an important problem for me, since it prevents the whole override feature to work. I reported this in more detail here, but the P&P people couldn't reproduce the bug.
After reopening the app.config file, and loading one delta file for an environment, the settings for my overridden properties do not appear as expected. I see the "Don't Override Properties" option instead. I have also reported this with no luck here.

Is anyone having the same problem? Did anyone make it work?

How-To: Implement a WCF Authorization Manager Using AzMan

2007-03-12T14:45:00.000-03:00

This article intends to explain how to use AzMan to implement a custom authorization policy in WCF.

AzMan (Windows Authorizacion Manager) is a role-based application framework which provides runtime access validation methods, storage, and a UI to manage access control. The Authorization Manager runtime is separated from the authorization policy store, which may be stored in Active Directory, ADAM, or XML. AzMan is composed of two parts:

Runtime: Provided by AZROLES.DLL, exposes a set of COM interfaces used by applications that employ role-based security.
Administration UI: MMC snap-in that you can try out by running AZMAN.MSC or by adding the Authorization Manager snap-in to your MMC console of choice:

Follow these steps to use AzMan from within a custom authorization policy in your WCF Service:

1. Put AzMan to work with ADAM as the authorization policy store.

As I said before, the authorization policy store is independent from the authorization runtime. In this example I used ADAM as the policy store, but you can use an xml file as well.

1.1. Download and Install AzMan: AzMan comes with Windows Server 2003. For othe versions of windows, the Windows Server 2003 SP1 Administration ToolPack can be installed.

1.2. Download ADAM and create a new ADAM Instance (not available for Windows Vista)
1.3 Configure AzMan to use ADAM as the policy store

Steps 1.2 and 1.3 are explained in detail in steps 1 and 2 of this article, so you can follow the from there.

The ADAM instance can be administrated from the Adam ADSI Edit tool:

2. Ask for the user's permissions programmatically.

Once you have your role-based policy created in AzMan, is time to know how to ask for permissions programmatically.

2.1 In your .Net project add a reference to the Microsoft.Interop.Security.AzRoles assembly (found at %AzMan Download Dir%\Windows(R) 2000 Authorization Manager Runtime\PIA\1.2).
2.2 In order to connect to your AzMan application you can use the following lines of code:

AzAuthorizationStore store = new AzAuthorizationStore();
store.Initialize(0, ConfigurationManager.AppSettings["azManStore"], null);
IAzManApplication app = store.OpenApplication(
ConfigurationManager.AppSettings["azManAppName"], null);

The azManStore configuration entry is of the form:
"msldap://localhost:389/CN=AzManADAMStore,OU=SecNetPartition,O=SecNet,C=AR" for an ADAM repository, or
"msxml://c:/TestAuthStore.xml" for an xml file repository

2.3 To ask if a user has access to a given operation you need to istantiate an IAzClientContext from the user identity and then ask the context whether it has access to a given operation.

To obtain the client context from his user name:

IAzClientContext ctx = app.InitializeClientContextFromName(user, domain, null);

To obtain it from a System.Security.Principal.WindowsIdentity:

HandleRef handle = new HandleRef(this, identity.Token);
IAzClientContext ctx = app.InitializeClientContextFromToken(
(UInt64)handle.Handle, 0);

To ask for access to a given operation:
object[] operations = { (object)operationId };
object[] scopes = { (object)"" };
object[] results = (object[])context.AccessCheck(app.Name, (object)scopes, (object)operations, null, null, null, null, null);

If the result is 0 the access is granted.

Note that the query is made for the operation id, as it was entered in the AzMan operation definition. Usually you'll need a mapping between the operations ids and some friendly name.

3. Implement your a WCF custom Authorization Manager that relies on AzMan for authorization.

Now we have code access to AzMan to query for authorization, we want to integrate that to our WCF Service. We will implement a custom authorizationManager for that, since is the WCF natural extensibility point for authorization (although you can do it in a custom behavior also, the AuthorizationManager would be more accurate).

The custom AuthorizationManager must derive from System.ServiceModel.ServiceAuthorizationManager and override the CheckAccessCore method. For more information see How To: Create a Custom AuthorizationManager for a Service

In this example we will obtain the required action and the username from the operationContext and then use our AzMan utility class (AthorizationRepository) to ask whether the user has access to the given operation.

class MyAuthorizationManager : ServiceAuthorizationManager {

protected override bool CheckAccessCore(OperationContext operationContext) {

//Instanciate our AzMan utility class
AuthorizationRepository azMan = new AuthorizationRepository();

//Obtain the requested action from the context
string action = operationContext.RequestContext.RequestMessage.Headers.Action;

// Iterate through the various claimsets in the authorization context // to obtain the user name
foreach (ClaimSet cs in operationContext.ServiceSecurityContext.AuthorizationContext.ClaimSets) {

foreach (Claim c in cs.FindClaims(ClaimTypes.Name,
Rights.PossessProperty)) {

string userName = c.Resource.ToString();
//check access
if (azMan.HasAccess(userName, action)) {
return true;
}
}
}
return false;
}
}

Hope it result useful!

Some links:

AzMan
Developing Applications Using Windows Authorization Manager
Use Role-Based Security in Your Middle Tier .NET Apps with Authorization Manager

ADAM
Windows Server 2003 Active Directory Application Mode
How To: Use ADAM for Roles in ASP.NET 2.0

WCF Authorization
How To: Create a Custom AuthorizationManager for a Service (WCF)
How To: STS/Windows Authentication with ADAM/AD, Roles in AzMan with WCF (using WCF behaviours)

Documentation Generation in .Net 2.0

2007-03-11T10:34:00.000-03:00

I found out that generating chm documentation from xml code comments in .Net 2.0 is not as easy as it was before. Thing is that NDoc has not been upgraded. Although it is available an NDoc2.0 alpha version, the product does not seem to be maintained.

Apparently, this is due to the throw of Sandcastle, the Microsoft's official documentation compiler (which is also included in Visual Studio's SDK Feb 2007). Though the documentation generation using this tool involves several steps, some of its users have already published scripts and tools that automate this task.

Reflector's addins

2007-01-22T18:08:00.001-03:00

I've been told of two addins for this great tool Reflector.

One is the File Disassembler addin, which you can use to generate code, in any language, from any assembly. This maybe useful for translating from one language to another, or to view the code in Visual Studio rather than in Reflector, but the truth is I haven't got the opportunity to need it yet.

The other addin, which I do use a lot, is the Code Metrics Addin. This one computes several code quality metrics of the assembly, such as the number of members of a class, the cyclomatic complexity, or the distance to the main sequence.

Since the link for downloading seems to be broken, I've upload it here.

Blogging tools

2007-01-22T17:35:00.001-03:00

I've recently discover two handy tools for blogging. The first one is the Windows Live Writer. It is a little more friendly than the Blogger's editor, besides the advantage of allowing you to write offline. I have no problems in writing here to Blogger, despite of not being able to upload images.

The other tool I started using last week is the Google Reader. It is really cool, like all other google stuff. It has the drawback of you having to request the page, but you can access it from any computer.

More on WF: Getting Started

2007-01-22T14:02:00.001-03:00

Continuing with the research on Workflow Foundation, here goes just a couple of things to get started with.

1- Quickly create your first sequence workflow

[See my previous post about the requirements for developing .Net framework 3 features.]

I am not going to put many details here, but to create your first workflow you need to select one of the workflow project templates in Visual Studio 2005. Just to start select the Sequential Workflow Console Application template. This generates a project with the references to the WF assemblies, the workflow itself and a test program.

By clicking on the workflow class the workflow is shown in the designer. Here is where you can drag activities from the toolbox. For example drag a CodeActivity. In the CodeActivity ExecuteCode property, type a method's name and press enter. VS will generate the method stub for you. Just write hello world to console there. Pressing the "view code" tab, the partial class with the workflow code (wfl properties, event_handlers, methods, etc) appears. You can see that the workflow inherits from SequentialWorkflowActivity.

So far we have the workflow defined with a set of activities. What we need now is to host the workflow and execute it. The generated program shows us how to do it:

using(WorkflowRuntime workflowRuntime = new WorkflowRuntime()) {

...

WorkflowInstance instance = workflowRuntime.CreateWorkflow(typeof(WorkflowConsoleApplication1.Workflow1));

instance.Start();

...

}

So, just press F5 and see the greeting message!

2- Get a feel of the Pre-build Activities

Some of the pre-build activities I have been experiencing with:

CallExternalMethod
Code
Delay
IfElse
Listen
Sequence
HandleExternalEvent

They are more or less self explained...I only want to mention one thing that may be a constraint in some circumstances:

The CallExternalMethod activity needs the following properties to execute:

InterfaceType
MethodName
Parameters

and the HandleExternalEvent similar properties:

InterfaceType
EventName
Parameters

In both cases the InterfaceType must be an Interface decorated with the ExternalDataExchange attribute, only this type of interfaces will be listed by the object browser. So the presence of that attribute is what I think may be a restriction as you can't use just any already built assembly.

3- Pass data to the WF:

There are two general approaches for receiving data into a workflow when it is started. They are Parameters and Events. With parameters, a list of parameter names and types are defined with the workflow. These parameter values are passed in by a host when it starts a new instance of the workflow type. With events, workflow authors add an activity that receives an event and data associated with the event. Events are generally specific to the host and custom activities that have been designed to handle the event.

The parameters can be passed in the CreateWorkflow method as shown here:

using(WorkflowRuntime workflowRuntime = new WorkflowRuntime()) {

...

Dictionary<string, object> parameters = new Dictionary<string, object>();
parameters.Add("FirstName", "Tom");
parameters.Add("LastName", "Sawyer");
WorkflowInstance instance = wr.CreateWorkflow(typeof(HelloWorldWorkflow.Workflow1), parameters);
instance.Start();

...

}

4- Make use of Conditions

A rule condition is a condition statement that is created in a dialog and stored as XML with the workflow. It can include predicates that compare workflow state and Boolean algebra combining multiple predicates. The conditions can be used in various activities including IfElse, While, ConditionedActivityGroup, and Replicator.

Take for example the IfElse activity. A condition can be set to one or both of its branches using the activity's properties. You can specify a CodeCondition or a DeclarativeCondition. In the first case you just enter the method's name. When you press enter the condition handler will be generated and shown in the code window. Put your logic in there, for instance:

public void If_Condition(object sender, ConditionalEventArgs e){

e.Result = this.reviewArgs.Review.Approved;

}

When using the DeclarativeCondition, you can use the Condition Editor to create it. You can access the workflow properties by intellisense.

My turn in the blog-tag game!

2007-01-16T14:24:00.000-03:00

As I’ve been tagged by my boyfriend, I suppose it’s my turn in this blogger’s game to play. So, here goes 5 things some people may don’t know about me:

I went to live on my own a few months ago, to a very cute apartment in Almagro, 5 blocks from my parents. It can’t actually be said a live “alone” since I have this eternal, and of course very welcome and lovely visit, my boyfriend.

I have a degree in Electronic Engineer from the University of Buenos Aires, but I’ve never worked as such. I have always worked as a software developer, nowadays in a great software company: Lagash Systems.

I have always like Maths. I kind of have it in the blood since both my parents are mathematicians. I’ve always teach math, first giving particular lessons and since many years now at the university, where I still teach “Algebra II” and used to teach “Probability and Statistics” too.

When I was young I studied music for many years (since I was 6 till 15) at the National Conservatory. I played piano and flout. Unfortunately I have a very bad memory and can’t remember a single piece of music. But I can still play if I’m in front of the sheet. I play mostly classic, despite for some Queen songs I learned when I was a teen and a great fan of them.

In my free time? I like to walk, dance, and go biking a lot. I try to go by feet everywhere whenever it is possible. I don’t like to stay much inside, I prefer to take some air. I really enjoy going anywhere with my boyfriend, going to the country house on Sundays with the family and hanging out with my friends.

Now it's time to tag another 5 people: RodolfoF, Zaiden, PabloC , Cyn and Pede.

First steps in Workflow Foundation

2006-12-05T14:49:00.000-03:00

I have started to play with Windows Workflow Foundation (WF) a few days ago. So far it seems very interesting, shipping with handy pre-build activities, persistence and tracking services, prity designers for visual studio, the capability of hosting these designers anywhere else…web services interaction, etc. Promising.

I just want to take down some notes here so I don't forget what I've learned.

Some Material

MS E-Learning course
Hands on Lab
WF Documentation (Programming model, samples, tools)

Some Concepts

Windows Workflow Foundation (WF): Set of components, tools, and a designer that developers can use to create and implement workflows in .NET Framework applications. It is part of the Microsoft .NET Framework version 3.0.
Workflow: a set of activities that are stored as a model that describes a real-world process. A workflow is designed by laying out activities.
Activity: A step in a workflow. The unit of execution, re-use and composition for a workflow.
Types of workflows (Here is a post about how to decide which type to use):

Sequential: Consists of activities that execute in a predefined order. Has a clear direction of flow from top to bottom, although it can include loops, conditional tests, and other flow-control structures.
State-Machine: Consists of states and transitions that change a workflow instance from one state to another. Although there is an initial state and a final state, the states have no fixed order, and an instance can move through the workflow in one of many paths.
Data-Driven: Is usually a sequential workflow that contains constrained activity groups and policies. In a data-driven or rules-based workflow, rules that check external data determine the path of a workflow instance. The constrained activities check rules to determine the activities that can occur.

The framework component model

The WF framework consists on 3 assemblies, containing the following namespaces:

System.Workflow.Activities

System.Workflow.Activities: Defines activities that can be added to workflows to create and run an executable representation of a work process.
System.Workflow.Activities.Configuration: Provides classes that represent sections of the configuration file.
System.Workflow.Activities.Rules: Contains a set of classes that define the conditions and actions that form a rule.
System.Workflow.Activities.Rules.Design: Contains a set of classes that manage the Rule Set Editor and the Rule Condition Editor dialog boxes.

System.Workflow.ComponentModel

System.Workflow.ComponentModel: Provides the base classes, interfaces, and core modeling constructs that are used to create activities and workflows.
System.Workflow.ComponentModel.Compiler: Provides infrastructure for validating and compiling activities and workflows.
System.Workflow.ComponentModel.Design: Contains classes that developers can use to build custom design-time behavior for workflows and activities and user interfaces for configuring workflows and activities at design time. The design-time environment provides systems that enable developers to arrange workflows and activities and configure their properties. The classes and interfaces defined within this namespace can be used to build design-time behavior for activities and workflows, access design-time services, and implement customized design-time configuration interfaces. It includes the TypeBrowserEditor, a cool feature that can be reused.
System.Workflow.ComponentModel.Serialization: Provides the infrastructure for managing the serialization of activities and workflows to and from extensible Application Markup Language (XAML) and CodeDOM.

System.Workflow.Runtime

System.Workflow.Runtime: Classes and interfaces that control the workflow runtime engine and the execution of a workflow instance.
System.Workflow.Runtime.Configuration: Classes for configuring the workflow runtime engine.
System.Workflow.Runtime.DebugEngine: Classes and interfaces for use in debugging workflow instances.
System.Workflow.Runtime.Hosting: Classes that are related to services provided to the workflow runtime engine by the host application.
System.Workflow.Runtime.Tracking: Classes and an interface related to tracking services.

Wix install sequence

2006-12-05T13:52:00.000-03:00

I am trying to figure out the exact behavor of the install sequence in the setup, as defined in a wix .wxs file. The confusion comes from the presence of the InstallUISequence and the InstallExecuteSequence tags, leaving aside the fact that there are actually four tags related to the actions sequence (AdminUiSequence and AdminExecuteSequence are used in administrative installs). As it is said in the wix turorial, "InstallExecuteSequence is always consulted by the installer to determine the actions, InstallUISequence is only considered when the installer runs in full or reduced UI mode." So, if executing without user interface, the order is determined for the InstallExecuteSequence and no doubts remain. But, if executing in full or reduced UI mode, both sequences are consulted. So, what is the resulting order of execution? If an action is placed in both sequences, it is executed twice?

As for the executing order, what I suppose happens is that all actions in the InstallUISequence are run first (since they gather the information required for the installation) and then those from the InstallExecuteSequence. But it is possible that some actions need to be executed before any UI dialog, so then we should place them in both sequences.

If an action is placed in both sequences, they will be apparently executed twice. Al least one exception for this rule is the AppSearch action. In the schema reference it says: “AppSearch should be authored into the InstallUISequence table and InstallExecuteSequence table. The installer prevents The AppSearch action from running in the InstallExecuteSequence sequence if the action has already run in InstallUISequence sequence.”

For custom actions, the execute attribute can be used for preventing the double execution.

Isolating Office Extensions with the COM Shim Wizard

2006-11-07T17:03:00.000-03:00

This article explains the importance of using a shim when implementing managed extensions for Office. It also provides a wizard to easily generate the shim from the managed extension. Very recommendable.

Problem with NAnt's xmlpoke task

2006-11-07T15:26:00.000-03:00

There's an issue when trying to replace some part of an xml file that is under a default namespace using NAnt’s xmlpoke task. It happened to me the other day when trying to replace the version attribute in the following wix file:
<?xml version="1.0" encoding="utf-8"?> <Wix xmlns="http://schemas.microsoft.com/wix/2003/01/wi"> <Product Name="MyProduct" Id="847A8D24-0F98-4b9f-AEA0-070ABD49F86C" Language="1033" Codepage="1252" Version="1.0.0" Manufacturer="MyCompany"> ...... </Product> </Wix>
Because of the namespace definition in the Wix element, calling xmlpoke simple as
<xmlpoke file="${wix.file}" xpath="/Wix/Product/@Version" value="${build.new.version}"/>
does not work.

What it does work is the following use of the task:
<xmlpoke file="${wix.file}" xpath="/wx:Wix/wx:Product/@Version" value="${build.version}"> <namespaces> <namespace prefix="wx" uri="http://schemas.microsoft.com/wix/2003/01/wi" /> </namespaces> </xmlpoke>

NAnt.Contrib

2006-11-07T15:24:00.000-03:00

NAnt Contrib is a project that contributes with a lot of additional tasks to NAnt. For example, two of the most useful tasks for me are the trycatch and choose tasks.

MSDN Conference's Material

2006-08-27T20:25:00.000-03:00

The presentation of the conference about "Testing and guarantee of quality with Visual Studio Team System" that we gave at Microsoft last Thursday can be downloaded from Rodolfo's blog.

How to add a custom rule to VSTS Code Analysis

2006-08-20T15:20:00.000-03:00

The code analysis feature that ships with Visual Studio Team System (VSTS), FxCop, comes with a rich API to write custom rules. Since the API almost lacks of documentation, I've been struggling for a while before I got my custom rules to work. That's why I've decided to write this short guide on how to make your own rules: (It is required that you have the VSTS version of Visual Studio 2005 intalled)

Create a new class library project.
Add references to the Microsoft.cci.dll and FxCopSdk.dll assemblies (typically installed in C:\Program Files\Microsoft Visual Studio 8\Team Tools\Static Analysis Tools\FxCop).
Create your custom rule class and make it derive from BaseIntrospectionRule.

Make the constructor of your class call its base constructor, which has three parameters: the rule's name, the name of the rule descriptor file (see step 4), and the assembly that contains the rule. Note that, if your project will consist on more than a single rule, it is convenient to write your own base class for all the rules not to repeat code.

I took as example the base class of the FxCop design rules:

using System;
using Microsoft.Cci;
using Microsoft.FxCop.Sdk;
using Microsoft.FxCop.Sdk.Introspection;

namespace Microsoft.FxCop.Rules.Design{

  internal abstract class DesignIntrospectionRule 
           : BaseIntrospectionRule {

    protected DesignIntrospectionRule(string name)
      : base(name, 
            "Microsoft.FxCop.Rules.Design.DesignRules",
            typeof(DesignIntrospectionRule).Assembly) {
    }

    public override void AfterAnalysis(){
       DesignRuleUtilities.Clear();
    }
  }
}

Override one of the Check methods to implement your custom rule's logic. Here's a snippet of one of the design rules that overrides the Check(TypeNode) method. Other Check overloads are available, for checking members, types, modules, etc. If it happends that the target being analyzed does not match the rule's condition, a new Problem is added to the Problems collection, and this collection is returned by the check method. The GetResolution method allows you to fetch a resolution from the rules xml file.

internal sealed class AbstractTypesShouldNotHaveConstructors 
   : DesignIntrospectionRule {

public AbstractTypesShouldNotHaveConstructors()
   : base("AbstractTypesShouldNotHaveConstructors") {
}

public override ProblemCollection Check(TypeNode type) {
   if (!type.IsAbstract) {
       return null;
   }
   for (int num1 = 0; num1 < type.Members.Length; num1++) {
        InstanceInitializer initializer1 = type.Members[num1] 
                    as InstanceInitializer;
        if ((initializer1 != null) && initializer1.IsPublic) {
           Resolution resolution1 = base.GetResolution(new string[]
                                        { type.Name.Name });
           Problem problem1 = new Problem(resolution1);
           base.Problems.Add(problem1);
           break;
        }
   }
   return base.Problems;
 }
 ...
}

Eventually override the BeforeAnalysis or AfterAnalysis methods if you need to execute something before or after the analysis process takes place respectivelly.

Add the rules .xml descriptor file to the project as an embedded resource, with the not copy to the target directory option set. The file's name (including it's namespace, and without the extension) must match the second parameter of the BaseIntrospectionRule constructor. It seems that there's no schema available for the xml, but here's a portion of the DesignRules descriptor:

<Rules FriendlyName="Design Rules">
...
<Rule TypeName="AbstractTypesShouldNotHaveConstructors" 
         Category="Microsoft.Design" 
         CheckId="CA1012">
<Name>Abstract types should not have constructors</Name>
<Description>Public constructors for abstract types do 
   not make sense because you cannot create instances of 
   abstract types.</Description>
<Url>/Design/AbstractTypesShouldNotHaveConstructors.html</Url>
<Resolution>Change the accessibility of all public constructors 
     in '{0}' to protected.</Resolution>
<Email>
</Email>
<MessageLevel Certainty="95">CriticalWarning</MessageLevel>
<FixCategories>NonBreaking</FixCategories>
<Owner />
</Rule>
...
</Rules>

Integrate the custom rules with visual studio's code analysis
- In order to register your rules with VS, you just need to copy the assembly containing your rules to the rules directory (c:\Program Files\Microsoft Visual Studio 8\Team Tools\Static Analysis Tools\FxCop\Rules).
- All the rules contained in the assembly will be enabled by default.
- You can now simply run the code analysis over a project to evaluate it with your own rules.

MSDN Conference

2006-08-01T21:08:00.000-03:00

This month I will take a little part in an MSDN conference at Microsoft Argentina. Along with Diego Gonzalez and Rodolfo Finochietti we will speak about Testing and quality assurance with Visual Studio Team System (VSTS).

It is the first time I am backwards the blackboard at a Microsoft's conference, so I am very enthusiastic about that. I hope to see everyone there. It is on August 24th and here's the link to register.

Starting developing in .Net Framework 3.0

2006-07-04T14:29:00.000-03:00

Here's a how to start developing .Net Framework 3.0 applications.

For any doubts on OS and framework's compatibility, read the article Deploying .Net Framework 3.0.

What's nedded for developing .Net3 applications (taken from here):

.Net Framework 3 Runtime Components (already ships with WindowsVista and Longhorn)
Windows SDK: includes the documentation, samples, tools and build environments to develop Windows applications - either native or .NET Framework 3.0.
[Optional] Visual Studio 2005
[Optional] "Orcas" .NET Framework 3.0 Development Tools: development tools that work with Visual Studio 2005 and provide functionality such as XAML Intellisense support through schema extensions for the editor, project templates for the Windows Presentation Foundation and Windows Communication Foundation namespaces and .NET Framework 3.0 SDK documentation integration.
[Optional] Visual Studio 2005 Extensions for Windows Workflow Foundation:extensions to Visual Studio 2005 include project templates, intellisense support for the Workflow namespace (System.Workflow) and integrated documentation.

.Net Glossary 3.0

2006-07-04T13:54:00.000-03:00

This is just a summary of the new terms incorporated by the third generation of the .Net Framework.

.Net Framework 3.0 (codename WinFX)

The new managed-code programming model for Windows.
It's basically the sum of the .NET Framework 2.0 plus some new technologies.
It will ship with Windows Vista.
It is available for Windows XP and 2000 with SP2 and for Windows Server 2003.
Here's the .Net Framework 3.0's diagram (stolen from MSDN):

Authentic Energic Reflexive Open (AERO): Windows Vista's Look & Feel. Refers back to the UX Guidelines.
Card Space (ex InfoCard): Unified Digital Identity.
eXtensible Application Markup Language (XAML): XML based languaged used to code the WPF's object model.
Microsoft Expression: multimedia software package for graphic designers. It ships with 3 applications:

Acrilyc Graphic Designer: Design tool compatible with bitmaps and vectorial graphics.

Sparkle Interactive Designer: XAML, MS alternative to Macromedia Flash.

Quartz Web Designer: MS Frontpage's replacement.

ORCAS: codename for the next version of Visual Studio.
Team Foundation Server (TFS): workflow collaboration engine that enables the use of a team's customized process, as well as a centralized data warehouse that collects real-time intelligence on project history.
The LINQ Proyect: codename for a set of extensions to the .NET Framework that encompass Language-INtegrated Query, set, and transform operations. It extends C# and Visual Basic with native language syntax for queries and provides class libraries to take advantage of these capabilities.
User Experience (UX) Guidelines (UX Guide): Contain information on what’s new in Windows Vista, design principles, guidelines for controls, text, windows, and aesthetics.
Windows Comunication Foundation (WCF) (codename Indigo): Unified set of technologies to build Service Oriented Applications.
Windows Presentation Foundation (WPF) (codename Avalon)
WindowsVista (codename Longhorn): Major Windows Operating System
Windows Workflow Foundation (WF): programming model, engine and tools for quickly building workflow enabled applications.

Dependencies Metrics

2006-07-04T09:44:00.000-03:00

In his paper about Stability (1997), Robert C. Martin describes a set of principles and metrics that can be used to measure the quality of a large object oriented designed proyect in terms of the interdependence between its packages.

The metrics

Abstract types: The number of abstract types contained in the assembly.
Total types: The number of total types contained in the assembly.
Abstractness (A): The ratio of abstract types in the assembly to the total number of types. A = abstract types / total types.
Efferent Couplings (Ce): The number of types inside the assembly that depend upon types outside the assembly.
Afferent Couplings (Ca): The number of types outside the assembly that depend upon types within the assembly.
Instability (I): I = Ce / (Ce+Ca). Measure of the facility in changing the assembly.
Distance from the Main Sequence (D): In an Abstraction vs Instability space, the distance from the assembly (I,A) possition to the Main Sequence (the line of maximum balance between abstractness and instability). D = |A+I-1|/sqrt(2)
Normalized Distance (D'): The above distance ranged between [0,1]. D’ = |A+I-1|

The Principles

Stable Abstraction Principle (SAP): Reference's direction must be from a less abstract to a more abstract assembly.
Stable Dependency Principle (SDP): Reference's directon must be from a more instable assembly to a more stable assembly.

Examples

<- The figure on the left shows a bad dependency (the red arrow) because As1 depends on As2, but As2 in less abstract than As1 and more instable too.

-> The figure on the right shows a good dependency because it goes in the abstraction's direction (As1 is more abstract thanAs2) and also in the stability's direction (As1 is more stable -less instable- than As2).

Why to use them

They are easy to calculate (already exists tools to do the job -at least for java-)
They are widely used and approved.
They will help a lot in determining the proyect's health in terms of its dependencies, although it is possible that not ALL references seen as bad references below the eye of this principles are REALLY bad references.
They allow to continuously monitor the quality aspects of code that can affect the long-term viability of your software architecture.

Tools for calculating them

For Java:

For .Net:

NDepend

Testing Data Access Layers (DALs)

2006-06-20T00:50:00.000-03:00

It seems that testing DALs is harder than I thought. One of the problems I have run into is how to preserve DB integrity. Some of the alternatives are:

Create mock objects that replace the database.
Have a separate DB for testing.
Restore the DB on every test run.
Run the test inside transactions and then rollback.

Another concern is: How the tests must be designed in order for their success or failure to depend only on the coding and not on the data state?

Related Links

Testing Frameworks:

Unit Testing in .Net Proyects by Jay Flowers

Transaction approach:

Simplify Data Layer Unit Testing using Enterprise Services
Alternative Testing Frameworks

Mock Objects:

Mock Objects to the Rescue! Test your .NET code with NMock
Mocks Aren't Stubs by Martin Fowler

Testing sequences (useful for CRUD operations):

Advanced Unit Testing, Part III - Testing Processes by Marc Clifton

DSL Tools for VS2005

2006-05-26T12:01:00.000-03:00

This is a guide for Building a DSL Designer using the DSL Tools for VS2005.

Pre-requisites:

These components must be intalled:

Visual Studio 2005
Visual Studio 2005 SDK
DSL Tools for Visual Studio 2005

1. Create a new project in VS2005

The project template must be: Other Project Types -> Extensibility -> Domain Specific Language Designer.

Choose a template for the designer.

Note that VS has created a solution with 2 projects: Designer and DomainModel.

A DSL Designer consists of 3 components:

1. Domain elements (Domain Model)
2. Notational elements
3. Mapping between Domain and Notational elements

2. The Domain Model

The Domain Model is in the DomainModel.dsldm in the DomainModel Project. You can edit it by gragging and dropping the Domain Model Designer Tools of the Toolbox.

The Model contains classes and relationships. Classes may contain value properties.

3. The Notation

The Notation is represented in an xml file. The default description is in the file Designer.dsldd in the Designer Project.

The notation can include shapes which appear in the toolbox and can be dragged onto the design surface, connector for the shapes, etc.

4. Domain-Notation Mapping

This is also defined in the dsldd file. In general the mapping is between shapes and connector lines to classes and relationships respectively. So when a user creates shapes and connectors in the designer he also creates the classes and relationships in the domain.

5. Generate code and build

Click on the "Transform All Templates" button in the Solution Explorer Toolbar.
Build the solution.
Press Ctrl+F5 to run the designer.

6. Consuming the DSL

Templates consist of some directives followed by a mixture of literal blocks and control blocks. Literal blocks are just plain text in the template that you want to pass straight through to the output. Control blocks are things with some kind of <# #> marker around them.

The content of these blocks in your template contributes to a class which the templating system generates. This class derives from the abstract class Microsoft.VisualStudio.TextTemplating.TextTransformation and overrides the abstract method TransformText which, when executed, writes out the desired output of the transformation of the template. If you do nothing else in your template, this method will write out all of the text in literal blocks by simply writing out the raw text using a simple WriteLine()-style statement. The base class provides this WriteLine method (in various flavors) as well as Error and Warning methods that you can use in your custom template code.

7. Deployment

Add a Setup package to build a deployable designer.

DSL - A first approach to.

2006-05-26T11:37:00.000-03:00

This is a summary of the Martin Fowler's article on Language Workbenches: The Killer-App for Domain Specific Languages? which I have recently read and found very interesting.

Terminology

Language Workbench: IDE tools to help Language Oriented Programming.

Language Oriented Programming: a style of development which operates about the idea of building software around a set of Domain Specific Languages.

Domain Specific Language (DSL): Limited form of computer language designed for a specific class of problems.

DSL

Imagine you build a class library to solve some particular problem and that the objects involved are parameterizable. So, you need a first step to set up configuration and wire up composite objects before putting them to do the work.

When building this kind of class library, there is a marked distinction between the abstraction itself and the configuration. The abstraction may be reusable and less often to change, while the configuration tends to be specific, more simple, and likely to change more often.

This leads to the idea of putting the configuration out of the code, for example, in xml files or in some custom syntax file (what may be more readily). The structure of this configuration, the mapping with the objects in the abstraction, the parameters, etc, are nothing but a kind of Domain Specific Language, a very small programming language, suitable for the only purpose of solving some specific problem.

If we leave the configuration in the code, instead of moving it to a configuration file, we still have a case of DSL, a DSL embedded in the host language. So here comes the distinction between internal and external DSL.

External DSL: DSL written in a different language than the main language of an application.

Internal DSL: DSL written in the same language of the main language of an application.

Language Oriented Programming

Language oriented programming is about describing a system through multiple DSLs. It does not have to be a black or white thing; you can represent little or a lot of functionality of your system in DSLs.

Pros and Cons of Language Oriented Programming

External DSL

Pros

Cons

Parameters can be changed without recompiling. Evaluated at runtime.
Format / grammar free.

A translator needs to be built.
Lack of symbolic integration.
Refactoring will not propagate to the DSL.
Lack of sophisticated editor.
Language cacophony: a new language must be learned.
Difficulty of designing DSLs.

Internal DSL

Pros

Cons

Symbolic Integration.
Host language IDE can be used.
Easy refactoring.
Sophisticated editors.

Recompilation required when making changes (in most languages).
Format / grammar free.

Language Workbenches

Language Workbenches are complex tools that help implementing DSLs. They are based on the same model as post-IntelliJ IDEs, which consists of having four different representations of the code:

Abstract representation: In-memory representation. Helps with things like name completion and refactoring. It is the key persistent source that you manipulate (through the editable representation). It can persist incomplete or contradictory information.

Editable representation: Projection of the abstract representation in order to edit it. It does not have to be complete. There can be multiple projections, one for each aspect.

Storage representation: Serialization of the abstract representation, often as XML.

Executable representation: The CLR byte code. A code generator turns the abstract representation into the executable representation.

So, when defining a new DSL you need to:

Define the abstract syntax, the schema of the abstract representation.
Define an editor to let people manipulate the abstract representation through a projection.
Define a generator to translate the abstract representation into an executable representation. In practice the generator defines the semantics of the DSL.

Configuration Files & NUnit

2006-05-04T10:12:00.000-03:00

When using an application configuration file (App.config) in a nunit library application project, the following post build event is needed to copy the config file to the target directory:
copy "$(ProjectDir)App.config" "$(TargetPath).config"
Once this is done, we can access any configuration item through:
System.Configuration.ConfigurationSettings.AppSettings["myConfigItem"]

Generating Documentation for .NET Project

2006-03-08T11:38:00.000-03:00

Suppose we need to generate documentation for a .net project in the Microsoft HTML Help style, more known as .chm files. Different tools can be used depending on what it is being documenting.

Documenting code

We can use xml documentation by placing comments inside xml tags (like <summary> or <remarks>) within any line beginning with three space bars

. For a complete tag reference see TagsForDocumentationComments .

The C# compiler processes documentation comments within the code to an XML file. This is done in the build process if the documentation xml file was specified in the project's build properties. (Notice that a lot of warnings about documentation will prompt if warning level is set to 4 in the project properties.)

Now, once we have the xml file, we want to parse it in order to generate easy reading documentation. Luckily, there is a free tool that does that: NDoc. Ndoc provides several output formats, including the MSDN one.

Including custom content in the chm file

If we need to include custom content in the chm file, other than the code documentation generated by NDoc, we have to write it in HTML format and then compile it into the chm file. The HTML Help SDK can be used for the last purpose. The SDK shipps with a tool, the HTML Help Workshop (\hhw.exe), that is used to create HTML Help Projects.

An HTML Help project consists of three parts:

The Project itself (.hhp file)
The Table of Contents (.hhc file)
The Index (.hhk file)

Documenting XML schemas

It seems that the documentation of xml schemas is a little more complicated task. First we need to place comments inside the schema and then we need to generate the HTML help from them.

In order to place documentation inside an xml schema, the annotation component can be used..

But again, a way for generating the HTML Help from the documented schema is needed. This time I have found no free tool to do that. I have found a nice tool, Document!X, neither free nor open source. So, I decided to generate the MSDN documentation myself by transforming the xsd file into an HTML help file through a style sheet. The generated HTML file is later included in the chm file as any else custom content.

Links:

http://www.mshelpwiki.com/index.php?
http://www.microsoft.com/downloads/details.aspx?familyid=ce1b26dc-d6af-42a1-a9a4-88c4eb456d87&displaylang=en

Blog's Birth

2006-03-06T18:34:00.000-03:00

My blog has born at last!

What is this blog about? This is a developer's blog, so just technical issues will be posted. The idea is to use this blog as a sort of knowlage base, just to write the daily little research and findings, for others to read and for me to remember. I was definitely needing a place to store all my writings and links and stuff, so I am very happy for this beginning and hope to keep it updated.

Of course averyone is welcome to contribute by posting comments or contact me.