Win32 Cryptographic Documentation: Building blocks of keeping secrets

At the end of April I moved from the BizTalk UA team to Windows Server UA team. I have gone from writing content about BAM to working with the documentation for building Cryptographic systems.

When I came to the team my concept of cryptography was limited to the actual encryption of the data. Now that I have been here for a month and a half I have had my eyes opened and I am just beginning to scratch the surface of what a cryptographic system really is. I am working my way through Applied Cryptography by Bruce Schneier, a truly fascinating read.

The major areas of documentation that I now 'own' can be found at

http://msdn2.microsoft.com/en-us/library/aa380255.aspx and http://msdn2.microsoft.com/en-us/library/aa376210.aspx

As to the future of this blog, I would like to accomplish the following:

• Solicit feedback on new topics that I am working on.
• Hear about areas in the existing documentation that need improvement
• Find out about real work applications or the technologies that you would like share that will help others better understand the usages.

Currently we are working toward a monthly refresh cycle on the MSDN docs. So you should see on going improvement in the documentation. One big push that I am working on is getting all the TBD's eliminated from the existing MSDN documentation.

I look forward to hearing from you.

Recently I have noticed quite a few questions about continuations coming through on the the BizTalk technical discussion lists.  This leads me to believe there is an opportunity to enhance the documentation around continuations, but to do that I need some feedback from you. What are the typical issues you run into when creating continuations? What type of documentation would help you most?

 For reference here are the topics that currently cover using continuations:

Continuation and ContinuationID Nodes http://msdn2.microsoft.com/en-us/library/aa577968.aspx 

How to Create a Continuation  http://msdn2.microsoft.com/en-us/library/aa559486.aspx

Using Multiple Continuations http://msdn2.microsoft.com/en-us/library/bb203851.aspx

We also have the following code developer specific documentation: 

Activity Continuation   http://msdn2.microsoft.com/en-us/library/aa559916.aspx

Development Walkthrough http://msdn2.microsoft.com/en-us/library/aa995587.aspx

The first in a series of papers addressing developing code for BAM solutions is now live at

http://download.microsoft.com/download/b/1/d/b1d9ddf9-88c6-4d4e-abea-4787fdc85bec/DevelopingWithBAM101.exe

This paper covers the basics of using EventStreams to instrument your existing business processess.

I have received requests for what might be called "Developing for BAM 101". To address these requests I am planning to provide a topic set that will help the new BAM code developer get started. I have outlined our proposed set of topics below. I welcome your feedback on these topics. Does this set of topics address the needs of the new BAM developer?

The topics in this table of contents will initially be delivered as a stand alone document set. on the Microsoft Dev Center. Moving forward the contents of this guide will be pushed into the core documentation for the BizTalk Server.
The target audience for this document is the new BAM developer. This document will focus on development tasks associated with handling BAM events.

Getting Started Developing For BAM

My first tidbit.

A recurring issue that pops up with the BAM feature is that of the locale/culture setting. BAM is made up of a number of separate components, SQL, web services, custom tools, and more.  In order for each of the components to operate together effectively, they must all be set to the same locale/culture. In addition, your system and user locale/culture should match those set for BAM.

For example, Suppose you are using a Russian deployment of Excel and you create a BAM definition that contains Russian strings for field names and deploy this definition to a BizTalk Server installation that is using US-English.

When the user navigates to the portal and view date/times or sorted lists. The Russian strings will sort with the US-English collation order and dates will be input and displayed using US-English rules.

To address this you can change the BAMPortal\Web.config file, by modifying the culture attribute under the <globalization> tag.

<globalization requestEncoding="utf-8" responseEncoding="utf-8" culture="ru-RU" uiCulture="en" />

Another instance where this can be a problem changing the system or user locale. Say you install Windows Server 2003, English edition and change the system locale to Dutch/Belgium. You then install Microsoft Office 2003 without the MUI packs. When you attempt to deploy a workbook containing  BAM definition you will receive the following error:

C:\myBAM>bm deploy-all -definitionfile:TCM119292-result.xls

Microsoft (R) Business Activity Monitoring Utility Version 3.5.1535.0

Copyright (C) 2006 Microsoft Corporation.  All rights reserved.

Using 'BAMPrimaryImport' BAM Primary Import database on server 'KW0083'...

ERROR: Failed to open BAM Excel workbook file - 'C:\ myBAM \TCM119292-result.xls'.

Old format or invalid type library. (Exception from HRESULT: 0x80028018 (TYPE_E_INVDATAREAD))

To deploy the workbook, change you locale back to English and redeploy the workbook.

Hello!

First let me introduce myself. I am Don Glover, Programming Writer for the Business Activity Monitoring (BAM) feature of BizTalk Server. Many of you will never have heard of a Programming Writer, so here is just a smidgin of back ground information. A Programming Writer is a technical writer who has come over to the writing field from a technical, typically development, back ground. Programming Writers are able to bring a deeper understanding of development issues to a product to better support those products that are used by developers.

This blog will be primarily about subjects relating to the BAM feature, though it may occasionally it may touch on broader BizTalk issues. It will also be a place where, when you have questions about the docs, or complaints, you can contact me, the writer, directly  and I can address them by answering your questions and back filling the information into the documentation.  This will be an opportunity for a two way conversation on the state of the documention. The goal is to provide the best documentaion possible.

I look forward to hearing your feedback as we go forward with this endeavor.