While building a service for SP2010 that uploads a document and adds metadata, I ran into some trouble with the document property promotion service in SharePoint.

In short its job is to keep properties in the files in sync with the list item field values. When you upload an Office OpenXML document or an image, SharePoint reads the properties in the file and updates the matching columns in the list item. If you then edit the list item properties in your browser, Sharepoint then updates the file with the modified properties to keep them in sync.

A very nice feature, albeit should you want to upload a document and update the properties yourself. Because the document parser runs asynchronously you will have a race condition. Will you or the document parser get to update the properties last? You can disable document parsers  by removing them from the SPWebService if you are a farm admin. Or you can disable all parsing for a single web if you are a site owner. So can I just set ParserEnabled=false call web.Update (in an elevated operation), then let the user upload the document and then set ParserEnabled back to true? Wrong! The parser runs delayed from the upload operation. So even when ParserEnabled is false when uploading the document, and you set ParserEnabled true immediately after - the upload will still trigger the parser.

The sad conclusion is that if you have to manage document properties programatically at any point, you must leave the web's property promotion disabled from then on.