(Cross-posted from the SharePoint Developer Documentation Team blog.)
By now you’ve probably been hearing some of the big news coming out of the SharePoint Developer Conference being held this week in Las Vegas. Doubtlessly, there’ll be tons more great information coming out of the Conference over the next four days concerning what’s new and notable in SharePoint Foundation 2010 and SharePoint Server 2010. But if you weren’t lucky enough to make it to Vegas this year, or are there but can’t wait for the session on your favorite area of SharePoint development, then have we got something you’ll want to take a close look at:
Introducing the SharePoint 2010 (Beta) Developer Center
That’s right, this morning we launched the SharePoint 2010 (Beta) Developer Center on MSDN. We’re using this new, combined Developer Center to give you your first detailed, public technical information and instruction around both SharePoint Foundation and SharePoint Server 2010. This new sub-site of the revamped SharePoint Developer Center highlights some early videos, documentation, and hands-on lab walkthroughs to introduce you to the exciting developer features on both SharePoint Foundation 2010 and SharePoint Server 2010.
But that‘s not all: we’ve also published a Beta release of the combined SharePoint 2010 SDK!
You’ll definitely want to spend some time on the site, getting ramped up for when the SharePoint 2010 Betas are released in November.
Learn SharePoint from the Ground Up
Of particular interest to developers new to SharePoint will be the Get Started Developing on SharePoint 2010. We’ve put together a series of 10 modules to help you get your feet wet on some of the main areas of SharePoint development, including:
Each module includes multiple video lessons, as well as code samples and hands-on lab walkthroughs, to give you a firm grounding in the topics covered.
Even experienced SharePoint developers will want to take a look at the modules that cover brand new development areas, like the client-side APIs, Silverlight user interfaces, sandboxed solutions, and the new ribbon user interface.
Get Your First Look at What’s New for Developers in SharePoint 2010
For an even deeper look at what’s new and notable in SharePoint Foundation and Server 2010, we’ve posted a Beta version of the combined SharePoint 2010 SDK. It’s packed with conceptual, procedural and reference material covering the major developmental areas of both Foundation and Server. All in all, it’s almost half a million words detailing how to develop SharePoint solutions.
For example, take a look here for what’s new in SharePoint Foundation 2010, including:
And take a look here for what’s new in SharePoint Server 2010, including:
Some other places you might want to start:
· If you’re coming to SharePoint from an ASP.NET development background, but sure and check out the Glide Path for ASP.NET Developers section, which is specifically aimed at developers transitioning from ASP.NET development to development on the SharePoint Foundation platform.
Let Us Know What You Want
Now, this SDK is a Beta release, so you’ll likely see some rough edges. But we’ve combined this SDK to cover both SharePoint Foundation and Server, and restructured it to present the continuum of SharePoint development in as logical and intuitive a way as we could. We then packed it with new and updated conceptual, procedural, and reference material.
We’d love to hear what you think of what we’ve done. As always, as you read through the SDK, if you spot issues, don’t see the information you need, or have suggestions, please drop us a line and let us know how we can improve our developer documentation. It’s easy; just do one of the following:
· Enter a comment in the MSDN ratings box
· Email us directly at docthis (at) Microsoft.com
· Email us through this blog
Be sure and check the SharePoint Developer Documentation Team blog often (or even better, subscribe to its RSS feed), as we plan on using the blog to preview draft versions of additional SDK content as it gets written.
For the last several weeks, I’ve been experimenting with using mind maps, both as a way of brainstorming about developer content, and as a possible way of presenting content in a less-structured way than a typical (linear) table of contents. In regards to that last goal, I really liked how mind maps let you graphically lay out a content area, and draw non-linear relationships between various nodes. I could see how this could be a much more intuitive, discoverable way of presenting content, especially for a technology as complex and interrelated as Windows SharePoint Services. I was using an application called MindManager (from Mindjet) to create my mind maps, and was generally pretty happy with the results.
There was just one problem: in order to share a fully-functioning map with anyone else, they needed to have the same software (or at least a downloadable viewer) installed. Sure, Mind Manager let me save a given mind map as a image map or static PDF, but each of those formats ruled out one of the main selling points on the mind maps themselves: the ability to collapse/expand various nodes on the map, and thereby control the level of information you were looking at. Without that interactive ability, it really seemed like the value of using mind maps as content/resource maps was fairly restricted.
Perhaps MindJet thought the same thing, because the new version of MindManager now lets you save your mind maps as interactive PDF files. Now anyone who can view PDFs can also interact with your maps, and customize the view by collapsing/expanding the nodes of their choice.
So I’ve created an interactive mind map as another way of presenting some of the information we currently have on MSDN, and I’ve love to know what people think of it. Basically, I’ve taken some of the content links present on the Workflow Resource Center and restructured them as a mind map. Rather than present the content based on content type or source, as the Resource Center does, I’ve tried to present the content grouped to present a workflow development overview, as well as by developer tool. Icons next to each link display what type of content I’m linking to (SDK topic, blog, multimedia, etc.); the text color denotes whether the link applies just to Windows SharePoint Services (green text) or Office SharePoint Server as well (blue text).
I’m hoping you’ll take a few minutes and download the map, play with it, and let me know what you think, even if you don’t have any interest in workflow development. More than just does this specific map meet your needs, I’ve love to hear whether you think using such maps in general is a useful/worthwhile way to present developer documentation. Leave a comment after the post or ping me directly through the blog; I’d love to hear from you.
(One minor drawback I can see is how much saving as an interactive PDF bloats the size of the file: this download, of a fairly small map, is 1.5M. Now if we could just get them to add a ‘Save as Silverlight’ feature…)
(Cross-posted from the SharePoint Developer Documentation Team Blog.)
By now you’ve no doubt heard that SP1 for Windows SharePoint Services 3.0, Office SharePoint Server 2007, and Office SharePoint Designer are now available. (And if you haven’t heard, go here to get all the important details before you download and install the Service Packs.)
For a complete listing of the documentation available for SharePoint SP1, check out the What’s New in SharePoint Server 2007 Service Pack 1 page on MSDN, which includes information resources for both WSS and MOSS SP1.
I’m happy to announce that as part of the SP1 push, we’ve again updated the WSS and MOSS SDKs on MSDN:
Here’s a quick run-down of additions and updates we’ve made to the WSS SDK:
New and Updated Material in the Windows SharePoint Services 3.0 SP1 SDK
New conceptual sections and topics that detail new features in Windows SharePoint Services 3.0 SP1 include:
This section provides overview information, installation instructions, and programming examples that introduce you to how Microsoft ASP.NET AJAX interacts with Web Parts. Topics include:
Other new conceptual sections and topics include:
The section discusses how to use the Workflow Actions schema to create and deploy custom workflow actions. The section includes reference topics for each of the 14 elements in the schema, as well as an example .ACTIONS file:
This section provides 8 new topics of overview information and programming tasks to help you work with Windows SharePoint Services 3.0 Alerts.
Significantly revised sections and topics include:
This section has been expanded with nine new topics, including the following new walkthrough:
In addition, reference material for all base field-rendering control types, and most derived types, in Microsoft.SharePoint.WebControls has been expanded.
This section has been expanded with 6 new conceptual topics, including the following new procedural and walkthrough topics:
In addition, reference material for all types in the Microsoft.SharePoint.MobileControls namespace has been added or expanded. The types in this namespace are now fully documented.
Several topics have been expanded.
· All types in the Microsoft.SharePoint namespace that connected to auditing are now fully documented.
· More than 80 code samples rewritten to adhere to the best coding practices as described in the following articles:
· Greatly expanded reference material for 39 types in the Microsoft.SharePoint.Utilities namespace.
This update also includes numerous other updates and revisions to existing SDK content.
And as for the SharePoint Server 2007 SDK, we’ve added and revised quite a bit of material there as well:
New and Updated Material in the SharePoint Server 2007 SP1 SDK
New and Improved Features in Office SharePoint Server 2007 SP1
New Conceptual Topics and How Tos
New Web Services and Class Library Reference Topics
· Microsoft.SharePoint.UserProfiles (56 classes)
· User Profile Web Service (14 classes)
· User Profile Change Web Service (2 classes)
· Exception classes (multiple classes in various namespaces)
· Internal only classes (multiple classes in various namespaces)
· WCM Document Converters Code sample
· Workflow Collect Feedback ASPX sample
Check it out, and as always, let us know what you think—either through rating our content, entering a comment on the topic online, or pinging us with an email through our blog.
Now that I’m managing a documentation team, I just don’t get to blog about SharePoint developer issues nearly as often as I’d like. In part to help remedy that, we’ve launched the SharePoint Developer Documentation Team blog. In the coming months, the programmer-writers for Windows SharePoint Services and Office SharePoint Server will be posting on a range of developer issues, information, and best practices. Our goals with the new blog are several:
· Present “draft” versions of SDK content before it’s available in the SDKs themselves. These drafts are tech-reviewed content that will end up in the SDKS; this is just our way of getting the information out to you as quick as we can.
· Promote content that we publish on MSDN. This includes giving you the latest news on new technical articles, SDK updates, code samples or tools downloads, and anything else new and noteworthy we think you’ll want to take a look at.
· Blog about the developer documentation we produce, and why. Ever wonder why we document what we do, in the way we do? In future posts we’ll explore the decisions we make when planning SharePoint developer documentation, and the data we base those decisions on.
· Engage with users, and find out just how developers are using (or would like to use) the documentation we produce.
· Experiment with presenting developer documentation in new and different formats.
So go check it out. Subscribe to our RSS feed. Even better, drop us a line and tell us what you’d like to see on the blog, or in our developer documentation.
I’m happy to announce that the Windows SharePoint Services 3.0 SDK has been updated online on MSDN!
What’s new in the April update of the WSS 3.0 Online SDK:
New conceptual sections:
Change Log and Synchronizing Applications
Creating Declarative, No-Code Workflow Editors
How to: Create a Custom Field Type and Field Control
How To: Extend the STSADM Utility
Schema reference topics for the following schemas:
Content Migration XML Schema Reference: Contains over 180 element topics that detail the eight migration schemas
Workflow Configuration Schema
Greatly expanded reference material for over 300 types in the following namespaces:
As well as expanded reference material for the following Web Services:
· Authentication Web Service
· Copy Web Service
This update also includes numerous updates and revisions to existing SDK content.
Note: The WSS 3.0 SDK download will be updated with the next online update, currently scheduled for the end of June.
I want to thank everyone who contributed their time and effort to making this update possible. We’ve added an immense amount of detailed technical content, with more to come. Check it out!
OK, we're back. Since it's now officially 2007, it seemed appropriate to focus my first entry of the New Year on Office SharePoint Server 2007, and Office InfoPath 2007.
Shortly before the holidays, someone asked me if I had any guidance for customers who wanted to set up workflow tasks to be bulk editable. To which I promptly replied:
You can do what?
I swear, there's so much functionality crammed in this product that sometimes I think it's going to take me the next two product cycles just to cover it all properly. I had no idea you even could edit workflow tasks as a group.
So, without further ado, here's the scoop:
In Office SharePoint Server 2007, you can define workflow tasks as bulk editable, and provide a custom InfoPath form view to enable users to edit workflow tasks as a group.
Bulk editable tasks are workflow tasks that can be edited as a group. All the tasks must be of the same task type, and from the same workflow association. For example, a user might want to mark all tasks of a certain type as 'complete' for a given workflow association.
In addition, by using an InfoPath form as the workflow task edit form, you can include logic in the InfoPath form to switch form views depending on whether the user is editing an individual task or bulk editing tasks.
Editing Workflow Tasks
Workflow tasks are displayed in task lists, just as any other tasks. When the user navigates to the task list, the tasks are displayed based on the View selected, and the access control list rights (ACLs) of the user. A workflow may have several different types of tasks, but all the tasks from a given workflow association are contained on the same task list. However, a given task list can contain the tasks for multiple workflow template and associations.
Developers can include elements in the workflow template definition that define task types as bulk editable.
For workflow tasks, users can select to process workflow tasks in bulk. Office SharePoint Server then displays a list of the workflow tasks types on that list that are bulk editable, sorted by workflow template. When the user selects a task type from a given workflow template, Office SharePoint Server displays the task edit form for that type. Developers can include logic in their InfoPath task edit forms that changes the form view based on whether the user is editing tasks individually, or in bulk.
The user can then edit the tasks as a group. The workflow task edit form need not contain any special logic to bulk edit the tasks; this is completely handled by Office SharePoint Server. When the user submits the task edit form, Office SharePoint Server writes the submitted data to each task of that task type for that workflow template for all associations of that template, as a timer job.
For information on specifying InfoPath workflow task forms, see Specifying InfoPath 2007 Forms for Workflows.
So, here's how it looks in the user interface, from the user's perspective:
1. Navigate to the task list that contains the workflow tasks you want to bulk edit.
The workflow tasks are displayed based on the View selected, and the your ACLs.
2. From the Actions menu, select Process all tasks.
Office SharePoint Server displays the Bulk Task Selection page. This page lists each task type on the list that is bulk editable. Task types are sorted by workflow template. Workflow associations are listed in parenthesis after the task type name.
3. Select the task type for the workflow template you want to bulk edit, and click OK.
Office SharePoint Server displays the task edit form. If you've included the proper logic in your form, MOSS displays the bulk edit view of the task edit form.
4. Enter your edits, and click Submit.
Office SharePoint Server writes the submitted data to each task of that task type for that workflow template, as a timer job.
Note Because the timer job updates each task, any custom code you have included in an OnTaskChanged event for that task type while run on each task as well.
Defining a Workflow Task as Bulk Editable
To define a task type in a given workflow as bulk editable, you add two elements to the workflow template definition.
How to Define a Workflow Task Type as Bulk Editable
Add the following two elements to the MetaData element in the workflow template definition, where N represents the task type number:
· TaskN_IsBulkActionable Optional Boolean. TRUE to define the task type as a task type that can be edited in bulk.
This element is optional. Office SharePoint Server treats task types that are not explicitly defined as bulk actionable as not bulk actionable.
This element defines the task type as bulk editable for this specific workflow template only. Therefore, can use the same task type in multiple workflows, and decide on a per workflow basis whether the task type is bulk editable.
All tasks of a given type are either bulk actionable or not, within a given workflow template.
· TaskN_BulkActionableFormName Optional Text. The task name to display for this task type in the Office SharePoint Server 2007 user interface. Users click this name to display the workflow bulk edit form.
For more information on workflow template definitions, see Workflow Definition Schema.
The following example has been edited for clarity.
<?xml version="1.0" encoding="utf-8" ?>
<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->
Displaying a Custom Bulk Edit Task Form View
Using InfoPath forms, you can provide a custom form view to enable users to edit workflow tasks as a group. When the user selects the task type they want to bulk edit, Office SharePoint Server displays the task edit form for that workflow task type, passing context data to the form. This context data includes an attribute, isBulkMode, which designates whether the task form is being called for bulk edit operations. Developers can include logic in their forms to specify different views based on whether the isBulkMode attribute is set to TRUE or FALSE.
We recommend that the task edit form for each workflow task type you define as bulk editable contain two views:
· One for individual task editing.
· One for bulk editing of tasks.
The bulk edit view should not load data from any particular task upon load, since Office SharePoint Server applies the data the user submits to every task of that type for the selected workflow association.
How to Display a Custom Bulk Edit View of the Workflow Task Form
· Include logic in the form that parses the context data passed to the form on load. This logic should include having the form display the bulk edit view if the isBulkMode attribute of the context data is set to TRUE.
Note To add the workflow context data to the form, you must first create an XML file that represents the context schema, and then import that file into the form as a secondary data source. For more information, see the Adding Workflow Context Data as a Secondary Data Source section of How to: Configure a Contact Selector Control on Your InfoPath Workflow Form.
For more information on using InfoPath forms with Office SharePoint Server workflows in general, see InfoPath Forms for Workflows.
Ever find something wrong/incomplete with an SDK topic on MSDN, and wish you could slap a Post-It Note with the correction right on the topic? Or come up with the perfect code sample for an object model reference topic, and wish you could annotate the topic with your masterpiece?
Well, now you can. Say hello to the MSDN Wiki.
This new functionality lets members of the community append selected topics on MSDN with their own comments, corrections, and code samples. Now you can share your hard-earned tips, tricks, best practices and gotchas with other developers, and learn from their experience as well. All this without leaving the MSDN library, or even the topic you’re in.
And the best part of it is: the MSDN Wiki is now part of every topic in the Windows SharePoint Services 3.0 and Office SharePoint Server 2007 SDKs.
Here’s how it works:
Every topic in the WSS 3.0 and MOSS 2007 SDKs now has a Community Content section append to the end of the topic. Anyone with a Windows Live account can log in and add content to this section. Got a great tip for a topic? Add it. Want to share a particularly cool piece of code? Add it to the relevant topic. You’ll retain ownership of your content; we only ask for a non-exclusive license so we can share your content with others.
As you can probably tell, I’m pretty jazzed about this. I think this is a great way to harness the power of the SharePoint developer community to help people create the solutions they want. It’s going to be fascinating to see how this evolves.
Just as important to me, personally, is that it gives us SDK writers an avenue to get our content out to the community that much faster. Now, instead of making a correction/addition to an SDK topic and then waiting months until the next SDK republish, I can add my additions directly to the Community Content section and get that information directly in front of our users nearly instantaneously. This is one of the things I had been using my blog for in the past, but this is even better, in that the new information will be presented directly within the relevant topic itself.
So look for us—we’ll be identified by the MSFT designation by our names.
Now that we’ve managed to get the Windows SharePoint Services and Office SharePoint Server SDKs out the door, I’ve had a chance to catch my breath and do a couple of one-off side projects. One of which is (big surprise) another poster highlighting the developer functionality in WSS 3.0.
This time around I’ve focused on the Information Rights Management framework in WSS. In WSS 3.0, administrators can now apply IRM to document libraries and item attachments. IRM lets you create a persistent set of access controls that live with the content, helping you control access to files even after a user downloads them. And if you’ve got custom file types, you can create IRM protectors: custom assemblies that plug into the IRM framework and control the conversion of those file types to and from their encrypted, rights-managed formats.
WSS gives you the choice of creating two types of custom protectors:
· Integrated protectors, which use Windows SharePoint Services to access the Windows Rights Management Services (RMS) platform in order to generate protected versions of files, and to remove protection from rights-managed files.
· Autonomous protectors, on the other hand, configure and execute the entire rights-management process by themselves.
The poster illustrates how the two types of protectors fit into the IRM framework in WSS 3.0, and how WSS uses each to rights manage documents during file upload and download process.
To download the poster, just click on the attachment at the end of this post.
You can read all about the IRM framework in WSS starting here.
Something you might have noticed as you perused the updated Windows SharePoint Services or Office SharePoint Server SDKs--or any MSDN technical article in the last week or so--was that the familiar ratings system has been replaced. Since the new ratings system may not be immediately discoverable or intuitive, I figured it was worth taking a few minutes to show you how to rate an article or provide feedback using the new system.
The first thing you'll notice is that MSDN's standard 9 point ratings scale has been replaced by a five star scale. The rating scale now appears on the article menu bar, right underneath the MSDN menu bar:
If an article hasn't yet been rated, all the stars are white, as in the screenshot above. (And I, for one, will not miss the 'Be the first to rate this page!' message on unrated articles. As a technical writer, nothing was more lonely than checking on your article weeks after it had been published and seeing this auto-generated plea for someone, anyone, to rate your article. But I digress.)
Once an article's been rated, colored stars represent the article or topic's current rating. The article pictured below, for example, has a current rating of four out of five:
So, how do you actually rate the article and enter feedback using the new system? Simply mouse hover over the stars themselves. You can then click on the star that represents the rating you'd like to give the article. The stars then turn red to reflect the rating you're chosen (and they stay that way until you submit your rating). However, you can change your rating up until you submit it.
In addition, the Optional Feedback form opens, enabling you to send us detailed comments on the article.
When you're done, just click the Send button to submit your rating and comments.
As under the old system, you only get to rate an article once. If you hover over the rating on an article you've already rated, you'll get a tooltip to that effect.
One thing I do wish MSDN had retained from the old system was the graph at the end of each article that told you how many people had rated the article, and showed their raw rating scores. As an MSDN user, I found this information very helpful in deciding whether or not to invest my time in reading longer articles.
After all, this:
Tells a much different story than this:
Even though they both result in an article rating of 4.5 (under the old scale). The first tells me that only two people rated the article, one of whom was very pleased with it (and one who might just be a troll rating everything a 1.) The second tells me that a statistically significant number of people found the article of limited utility. This could be good information for a reader to have before reading a 20 page article.
In any case, another cool new feature is the improved 'breadcrumb' functionality. (The term 'breadcrumb' refers to the hierarchical list of pages/nodes you've had to traverse to get to your current location in the MSDN library.) Now, if you hover over an entry in the breadcrumb, you'll get a hot-linked list of the topics/nodes at that same level in the MSDN library table of contents. I think this is going to make our SDK content a lot more discoverable/navigable in the future.
I'd be interested in what you all think of the new system.
I'd be interested in what you all think of the new system.
So now that you've downloaded Windows SharePoint Services 3.0, you're ready to get serious about creating SharePoint solutions, right? If so, let me direct you to another developer tool you'll want to download:
The extensions (as they're known to their friends) were designed specifically to jumpstart developers creating SharePoint solutions in Visual Studio. They include project and item templates for essential SharePoint building blocks like Web parts; team sites, blank sites, and list definitions; custom fields, content types, and modules. Each template includes functionality that makes coding, testing, and deploying these items easier than ever before. If you intent to develop in the SharePoint environment using Visual Studio, this download is for you.
And, if you're planning on using the Web part project template, check out the accompanying article, which provides a quick rundown on how it's done:
And, as always, if you read the article, please take a minute and rate it. Thanks.
So by now you no doubt know that Windows SharePoint Services 3.0 is available for download. But something you might have missed is the fact that we have updated the Windows SharePoint Services 3.0 and Office SharePoint Server 2007 SDKs on MSDN.
You can find the WSS SDK here.
And the MOSS SDK here.
These latest updates represent the "official" (that is, non-Beta) release of both SDKs. We've tried to provide the highest-priority developer information, as completely and accurately as we can. While there are definitely areas of the SDKs we plan on expanding in future updates, if we've done our job then you should have plenty of detailed technical information to get you started developing solutions in the SharePoint environment.
As you go through each SDK, don't be shy about letting us know what works (or doesn't) for you, and what types of information you'd like to see in future updates. I can tell you first hand that the comments you type in on MSDN don't just go into a black hole somewhere; they do indeed make it back to the correct documentation team. And you can always contact me through this blog as well, and I'll try and route your comments to the appropriate person (requests for money or free Zune players will be ignored.)
Just for the sake of completeness, here are the various downloads for WSS:
For these four entries, I’m going to go over in detail how to construct and register a custom parser that enables you to promote and demote properties between your custom file types and Windows SharePoint Services.
Today, I’ll round out the document parser information I’m presenting by talking about how to register your custom parser with WSS. I’ll also give you a quick overview of the ISPDocumentParser interface, which your parser needs to implement to communicate with WSS.
Document Parser Definition Schema Overview
To register a custom document parser with WSS, you must add a node to the document parser definition file that identifies your parser and the file type or types it can parse.
You can specify the file type or types a document parser can parse either by file extension, or file type program ID.
WSS stores the document parser definition file, DOCPARSE.XML, at the following location:
Web Server Extensions\12\CONFIG\DOCPARSE.XML
The document parser definition schema is as follows:
Following is a list of the elements in the document parser definition schema.
Required. Represents the root element of the document parser definition schema.
Required. Each docParser element represents a document parser and its associated file type. This element contains the following attributes:
· Name Required string. The file type associated with the parser. For docParser elements within the ByExtension element, set the Name attribute to the file extension. For docParser elements within the ByProdId element, set the Name attribute to the program Id of the file type. To associate a parser with multiple file types, add a docParser element for each file type.
· ProgId Required string. The program ID of the parser. This represents the ‘friendly name’ of the parser. This enables you to upgrade a parser without having to edit its document parser definition entry in the DOCPARSE.XML file. However, this prevents you from installing different versions of the same parser side-by-side.
Document Parser Definition Example
Below is an example of a document parser definition file.
<docParser name="abc" ProgId="AdventureWorks.AWDocumentParser.ABCParser"/>
<DocParser name="AWApplication.Document" ProgId="AdventureWorks.AWDocumentParser.ABCParser"/>
Document Parser Interface Overview
In order for a custom document parser to perform document property promotion and demotion in WSS, it must implement the following document parser interfaces. These interfaces enable the document parser to be invoked by WSS, and send and receive document properties when so invoked.
Represents a custom document parser. This class includes the methods WSS uses to invoke the document parser.
Represents a property bag object used to transmit document properties between the document parser and WSS. Includes methods that enable the document parser to access the content type and document library schemas for the specified document.
Represents an enumerable document property collection. Includes methods the document parser can use to enumerate through the document property collection.
Represents a single document property. Includes methods for the document parser to get and set the document property value and data type.
For these four entries, I’m going to go over in detail how to construct and register a custom parser that enables you to promote and demote properties between your custom file types and Windows SharePoint Services.
Document Parsing and Content Types
When WSS invokes a document parser to promote document properties, the parser writes all document properties to a property bag object. WSS then determines which of these document properties to promote to matching document library columns. If the document has been assigned a content type, then WSS promotes the document properties that match the columns included in the content type.
Parsing Content Types in Documents
Using the document parser interface, document parsers can access the content type assigned to the document, and, if desired, store the content type in the document itself. If, when WSS invokes the parser to parser a document, the parser writes the document’s content type to the property bag object as a document property, WSS compares this content type to the content types associated with the document library to which the document is being uploaded. If the document’s content type is one that is associated with the document library, WSS promotes the appropriate document properties and saves the document.
However, there are cases where the document’s content type may not actually be associated with the document library to which the user is uploading the document. For example, the user might have created the document from a document template that contained a content type; or the user might move a document from one document library to another.
If the document’s content type is not associated with the document library, WSS takes the following actions:
· If the document contains a document property for content type, but that document property is empty, WSS invokes the parser to demote the default list content type for the document library into the document. WSS then promotes the document properties that match columns in the default list content type, and stores the document.
This would occur if the document had not yet been assigned a content type.
· If the document is assigned a content type not associated with the document library, WSS determines whether the document library allows any content type. If so, WSS leaves the document’s content type as is. WSS does not promote the document content type; however, it does promote any document properties that match document library columns.
Lists can be set to allow any content type. To do this, add the Unknown Document Type content type to the list. If you add this content type to a list, then documents of any content type can be uploaded to the list without having their content types overwritten. This enables users to move a document to the list without losing the document’s metadata, as would happen if the content type was overwritten.
· If the document is assigned a content type not associated with the document library, and the document library does not allow any content types, WSS invokes the parser to demote the default list content type for the document library into the document. WSS then promotes the document properties that match columns in the default list content type, and stores the document.
The figure below details the actions taken by WSS, if the parser includes the document’s content type as a document property in the property bag returned to WSS when the parser parses a document.
WSS never promotes a document’s content type onto a document library.
In my final post of this series, I'll introduce you to the document parser definition schema, and the document parser interface.
In my last entry, I gave you a brief overview of what document parsers are in Windows SharePoint Services V3, and a high-level look at what you need to do to build a custom document parser for your own custom file types. Today we’re going to start digging a little deeper, and examine how a parser interacts with WSS in detail.
Document Parser Processing
When a file is uploaded, or move or copied to a document library, WSS determines if a parser is associated with the document's file type. If one is, WSS invokes the parser, passing it the document to be parsed, and a property bag object. The parser extracts the properties and matching property values from the document, and adds them to the property bag object. The parser extracts all the properties from the document.
WSS accesses the document property bag and determines which properties match the columns for the document. It then promotes those properties, or writes the document property value to the matching document library column. WSS only promotes the properties that match columns applicable to the document. The columns applicable to a document are specified by:
· The document's content type, if it has been assigned a content type.
· The columns in the document library, if the document does not have a content type.
WSS also stores the entire document property collection in a hash table; this hash table can be accessed programmatically by using the SPFile.Properties properties. There is no user interface to access the document properties hash table.
The following figure illustrates the document parsing process. In it, the parser extracts document properties from the document and writes them to the property bag. Of the four document properties, three are included in the document's content type. WSS promotes these properties to the document library; that is, writes their property values to the appropriate columns. WSS does not promote the fourth document property, Status, even though the document library includes a matching column. This is because the document's content type does not include the Status column. WSS also writes all four document properties to a hash table that is stored with the document on the document library.
WSS can also invoke the parser to demote properties, or write a column value into the matching property in the document itself. When WSS invokes the demotion function of the parser, it again passes the parser the document, and a property bag object. In this case, the property bag object contains the properties that WSS expects the parser to demote into the document. The parser demotes the specified properties, and WSS saves the updated document back to the document library.
The figure below illustrates the document property demotion process. To update two document properties, WSS invokes the parser, passing it the document to be updated, and a property bag object containing the two document properties. The parser reads the property values from the property bag, and updates the properties in the document. When the parser finishes updating the document, it passes a parameter back to WSS that indicates that it has changed the document. WSS then saves the updated document to the document library.
Mapping Document Properties to Columns
Once the document parser writes the document properties to the property bag object, WSS promotes the document properties that match columns on the document library. To do this, WSS compares the document property name with the internal names of the columns in the document’s content type, or on the document library itself if the document doesn’t have a content type. When WSS finds a column whose internal name matches the document property, it promotes the document property value into that column for the document.
However, WSS also enables you to explicitly map a document property to a specific column. You specify this mapping information in the column’s field definition schema.
Mapping document properties to columns in the column’s field definition enables you to map document properties to columns that may or may not be named the same. For example, you can map the document property ‘Author’ to the ‘Creator’ column of a content type or document library.
To specify this mapping, add a ParserRef element to the field definition schema, as shown in the example below:
<Field Type=”Text” Name=”Creator” … >
<ParserRef Name=”Author” Assembly=”myParser.Assembly”>
The following elements are used to define a document property mapping:
Optional. Represents a list of document parser references for this column.
Optional. Represents a single document parser reference. This element contains the following attributes:
· Name Required String. The name of the document property to be mapped to this column.
· Assembly Required String. The name of the document parser used.
A column’s field definition might contain multiple parser references, each specifying a different document parser.
In addition, if you are working with files in multiple languages, you can use parser references to manage the mapping of document properties to the appropriate columns in multiple languages, rather than have to build that functionality into the parser itself. The parser can generate a single document property, while you use multiple parser references to make sure the property is mapped to the correct column for that language. For example, suppose a parser extracts a document property named ‘Singer’. You could then map that property to a column named ‘Cantador’, as in the example below:
<Field Type=”Text” Name=”Cantador” … >
<ParserRef Name=”Singer” CLSID=”MyParser”>
<ParserRef Name=”Artist” Assembly=”MP3Parser.Assembly”>
To edit a column’s field definition schema programmatically, use the SPField.SchemaXML object. There is no equivalent user interface for specifying a parsers for a column.
In the next entry, we'll discuss how WSS processes document that contain their content type definition.
Now that I’ve talked about the built-in XML parser, and how you can use it to promote and demote document properties for XML files, you might be thinking: what about custom files types that aren’t XML? What if I’ve got proprietary binary file types from which I want to promote and demote properties to the SharePoint list?
We’ve got you covered there as well.
For the next four entries, I’m going to go over in detail how to construct and register a custom parser that enables you to promote and demote properties between your custom file types and Windows SharePoint Services.
This information will get rolled into the next update of the WSS SDK, so consider this a preview if case you want to work with the parser framework right now.
Custom Document Parser Overview
Managing the metadata associated with your document is one of the most powerful advantages of storing your enterprise content in WSS. However, keeping that information in synch between the document library level and in the document itself is a challenge. WSS provides the document parser infrastructure, which enables you to create and install custom document parsers that can parse your custom file types and update a document for changes made at the document library level, and vice versa. Using a document parser for your custom file types helps ensure that your document metadata is always up-to-date and synchronized between the document library and the document itself.
A document parser is a custom COM assembly that, by implementing the WSS document parser interface, does the following when invoked by WSS:
· Extracts document property values from a document of a certain file type, and pass those property values to WSS for promotion to the document library property columns.
· Receives document properties, and demote those property values into the document itself.
This enables users to edit document properties in the document itself, and have the property values on the document library automatically updated to reflect their changes. Likewise, users can update property values at the document library level, and have those changes automatically written back into the document.
I’ll talk about how WSS invokes document parsers, and how those parsers promote and demote document metadata, in my next entry.
For WSS to use a custom document parser, the document parser must meet the following conditions:
· The document parser must be a COM assembly that implements the document parser interface.
I’ll go over the details of the IParser interface in a later entry.
· The document parser assembly must be installed and registered on each front-end Web server in the WSS installation.
· You must add an entry for the document parser in DOCPARSE.XML, the file that contains the list of document parsers and the file types with which each is associated.
And I’ll give you the specifics of the document parser definition schema in a later entry as well. All in good time.
WSS selects the document parser to invoke based on the file type of the document to be parsed. A given document parser can be associated with multiple file types, but you can associate a given file type with only one parser.
To specify the file type or types that a custom document parser can parse, you add a node to the Docparse.XML file. Each node in this document identifies a document parser assembly, and specifies the file type for which it is to be used. You can specify a file type by either file extension or program ID.
If you specify multiple document parsers for the same file type, WSS invokes the first document parser in the list associated with the file type.
WSS includes built-in document parsers for the following file types:
· OLE: includes DOC, XLS, PPT, MSG, and PUB file formats
· Office 2007 XML formats: includes DOCX, DOCM, PPTX, PPTM, XLSX and XLSM file formats
· HTM: includes HTM, HTML, MHT, MHTM, and ASPX file formats
You cannot create a custom document parser for these file types. With the XML parser, you can use content types to specify which document properties you want to map to which content type columns, and where the document properties reside in your XML documents.
To guarantee that WSS is able to invoke a given parser whenever necessary, you must install each parser assembly on each front end Web server in your WSS installation. Because of this, you can specify only one parser for a given file type across a WSS installation.
The document parser framework does not include the ability to package and deploy a custom document parser as part of a SharePoint feature.
In my next post, I’ll discuss how the document parser actually parses documents and interacts with WSS.
Today I'd like to talk about how to store and manage XML forms (InfoPath and otherwise) in WSS V3.
In general, forms have three special areas of functionality:
· Property Promotion and Demotion This refers to promoting and demoting document data to and from columns in a SharePoint library.
· Link Management This refers to how WSS keeps the link to the form template in the XML file up to date, if any site, sub-site, or library is renamed.
· Merge Forms Sends multiple XML files that have the same schema to a client application to be merged.
In Windows SharePoint Services Version 2, this special functionality was part of the Form Library site template. Now, in WSS V3, it's encapsulated in the Form content type instead. Instead of creating a new form library, you can create a new content type, inheriting from the Form content type. Your new form becomes the template for the content type.
This new approach offers several major advantages over the form libraries:
· Central management of forms Because you're creating a new content type, you gain all the advantages content types offer in terms of centralized management. You can control the form and its metadata from a single location, regardless of how many libraries to which you've added the content type. You can also specify enterprise content management features for your content type, such as property promotion and demotion, workflow, or (if you have Office Server 2007) information policy. And you don't have to republish the form if you make changes to the content type for which it's the form template.
· Add multiple forms to the same library Again, because each type of form is a separate content type, you can add multiple form type to the same library.
· Add forms to the same libraries as documents You can form content types to the same libraries that contain document content types. In a very real sense, there's no distinction between form and document libraries in WSS V3; there're just libraries. Any special functionality is encapsulated in the content types themselves.
(However, the form library site template has been retained in WSS V3 for purposes of backward compatibility with XML-based forms editors that do not support publishing forms to content types, such as InfoPath 2003. But if you are using an XML-based forms editor that supports content types, such as InfoPath 2007, we strongly recommend you use the Form content type instead of the form library template. And with all the obvious advantages, why wouldn't you?)
Publishing InfoPath 2007 Forms to Content Types
So let's talk specifically about InfoPath 2007 forms for WSS V3. InfoPath 2007 includes the ability to publish forms directly into new or existing content types on a WSS installation. This includes setting up property promotion and demotion: you're able to choose which data fields on your form you want to map to which SharePoint columns. You get link management and merge forms functionality for free, because the content type to which you publish your form is a child of the Form content type.
When you publish an InfoPath 2007 form, you have the option to publish it to a SharePoint site. When you do, you have the further option of publishing the form into a new or existing content type.
(You still have the option of publishing your form to a document library, just as you did with InfoPath 2003. In InfoPath 2007, though, you can update both document libraries as well as form libraries, as long as that library’s default content type is a child of the Form content type. If the library doesn’t have multiple content types, then the single library content type must be a child of Form in order for you to update it. In addition, document property demotion now works in document libraries.)
When you choose to create a new content type, you select the content type from which you want your new content type to inherit. By default, the new content type is a direct child of the Form content type, but you can specify any descendant of Form to use as your new content type's parent.
Next, you can choose which data fields you want to promote and demote to and from SharePoint site columns. To do this, you specify the columns to which you want to map the data fields in your form. You can map the data fields to existing site columns, or create new columns.
If you map a data field to an existing site column, InfoPath adds a <FieldRef> element to the content type for that site column. The <FieldRef> element contains a set of attributes you can override for the site column, as it applies to items assigned this content type. These attributes include those that specify where in an XML form the data field information is located. Because you’re mapping a data field (i.e., the data in your XML) to the column, InfoPath uses the Node attribute to specify an XPath expression for where the data resides in the form.
For more information on how the built-in XML parser uses the Node attribute for data promotion and demotion, see this earlier post.
If you create a new site column, InfoPath adds a <Field> element that represents that site column to the site, and then adds a <FieldRef> element to the content type for that site column.
For more information on how <Field> and <FieldRef> elements differ, and how <FieldRef> elements work in a content type, see my earlier post here.
If you choose to update the existing content type itself, you can stick with the existing columns for that content type, or add new ones. You can also remove columns for data fields you've deleted or don't want promoted or demoted anymore. If you do delete a column, InfoPath removes the <FieldRef> element from the content type definition, but leaves the site column intact (that is, the <Field> element for that site column remains in the site definition). You cannot remove any columns the content type inherits from its parent content type.
Once you've published your form to a content type, you can use WSS to further customize the content type, such as adding columns, workflows, and policies. Also, remember that this is a site content type; in order to use the content type in a library, you have to add that site content type to the library through WSS.
Here are a few other things to keeping mind about InfoPath 2007 forms and form content types:
Determining the Content Type of InfoPath Forms
InfoPath forms themselves do not contain the content type ID of the content type they’ve been assigned. Instead, WSS uses the form template to determine the content type of the form. The form template URL is included in the <?xml> processing instruction of the form, and points to the .xsn on which the form is based.
The built-in XML parser included in WSS first attempts to find the content type ID in the XML file, and, failing that, attempts to determine the content type based on the form template. So, for InfoPath forms, the built-in XML parser always fails its first check, and has to use the form template to determine content type.
For more information on how the XML parser determines content type, see this earlier post.
Setting the Product Used to Edit the XML File
The program ID for InfoPath 2007 forms is included in the forms in the progId2 attribute of the <?mso-infopathdocument> processing instruction. In content type definitions, InfoPath maps this to the ProgID column using the PrimaryPITarget and PrimaryPIAttribute attributes.
So, for content types for InfoPath 2007 forms, the attributes for the ProgID <FieldRef> element are set to the following values:
PITarget = mso-infopathdocument
PIAttribute = InfoPath.Document
PrimaryPITarget = mso-infopathdocument
PrimaryPIAttribute = InfoPath.Document.2
Because WSS looks at the PrimaryPITarget and PrimaryPIAttribute pair first, the InfoPath.Document.2 attribute value is promoted to the ProgID column. The ProgID column determines which application WSS calls to open a selected file.
This is the final post in a five-part series on how to use the built-in XML parser in WSS V3 to promote and demote document properties in your XML files, including InfoPath 2007 forms.
You can include namespace prefixes in the XPath expressions you use to specify the location of a document property. To use a namespace prefix, you must first define it in a custom XMLDocument element included in the content type definition.
The namespace for this XML node is:
The structure of the custom XMLDocument node is as follows:
Following is a list of the elements in the schema, and their definitions:
Namespaces The root element. Represents a collection of namespaces for use in XPath expressions.
For each namespace you specify, you must include the following values:
· prefix The prefix to use when designating this namespace.
· value The actual namespace for which you are specifying a prefix.
This schema describes optional XML you can include in a content type as custom information. For more information on including custom information in a content type, see this topic in the WSS V3 Beta 2 SDK.
This is the fourth in a five-part series on how to use the built-in XML parser in WSS V3 to promote and demote document properties in your XML files, including InfoPath 2007 forms.
There are two document properties the built-in XML parser examines to determine the content type to assign to an XML document when a user first uploads it to a given document library. The parser must determine which of the content types associated with the document library to assign the document before the parser can promote or demote document properties.
For a detailed examination of the process the parser performs to match a document’s content type with a content type associated with the document library, see part three.
Specifying Content Type by Content Type ID
The parser first looks for a processing instruction that specifies the document’s content type by content type ID. The location of this processing instruction is included in the definition for the content type ID column template. The processing instruction is named MicrosoftWindowsSharePointServices and contains an attribute named ContentTypeID that represent the ID of the document's content type.
Name="Content Type ID"
By default, all library list templates include a column that represents the content type ID.
Add this processing instruction to your XML document. Set the ContentTypeID attribute to the ID of the document’s content type.
<? MicrosoftWindowsSharePointServices ContentTypeID=”0x010101003D7907A1908011d082BD08005AA74F5E00A557E10DA69DBF4C8BE1E21071B08163”/>
The parser will fail to determine the content type in the following situations:
· The MicrosoftWindowsSharePointServices processing instruction isn’t present in the document
· The processing instruction does not specify a content type
· The specified content type is not associated with the document library
· No parent or child of the specified content type is associated with the document library
If the parser cannot identify the content type by content type ID, it performs a second check, detailed below.
Note The parser looks for the content type ID in whatever document location you specify in the field definition for the Content Type ID column on the document library. You can map the Content Type ID column to any processing instruction or XPath expression you choose. However, we recommend you adhere to the default mapping include in the content type ID column template definition. This minimizes the chance of having content types that specify a different location for this document property than the document library with which they are associated. Such a situation would lead to the XML parser looking in the wrong document location for the content type ID.
Specifying Content Type by Document Template
If the parser fails to determine a suitable content type for the document based on content type ID, the parser then looks for a processing instruction that contains the URL of the document template on which the document is based. The processing instruction is named mso-infoPathSolution that contains an attribute named href that represents the URL of the document template.
This column is included in the Form content type, and is added to a library anytime that content type is added to the library.
So, rather than include a content type ID, you can add this processing instruction to your XML document. Set the href attribute to the URI of the document template on which the document is based.
If the parser finds this processing instruction, it then examines the content types associated with the document library to determine if a content type has the same document template. If so, the parser assigns that content type to the document. If more than one content type associated with the document library has the same matching document template, the parser simply assigns the first content type it finds that matches.
Note The parser looks for the document template URL in whatever document location you specify in the field definition for the Document Template column on the document library. You can map the Document Template column to any processing instruction or XPath expression you choose. However, we recommend you adhere to the default mapping included in the document template column template definition. This minimizes the chance of having content types that specify a different location for this document property than the document library with which they are associated. Such a situation would lead to the XML parser looking in the wrong document location for the document template.
In the final installment of this series, I'll show how you can include namespace prefixes in the XPath expressions you use to specify the location of a document property.
This is the third in a five-part series on how to use the built-in XML parser in WSS V3 to promote and demote document properties in your XML files, including InfoPath 2007 forms.
In order for the built-in XML parser to determine the document’s content type, and thereby access the content type definition, the document itself must contain the content type as a document property. The parser looks for a special processing instruction in your XML documents to identify the document’s content type. You can include processing instructions that identify the document’s content type by content type, and/or document template.
How the Parser Determines Document Content Type
When a user uploads an XML document to a document library, WSS V3 invokes the built-in XML parser. Before the parser can promote document properties, it must first determine the content type, if any, of the document itself.
The parser first looks at the Field element in the document library schema that represents the content type ID column on the document library. The parser examines the Field element for the location in the document where the content type ID should be stored. The parser then determines if the content type ID is indeed stored in the document at this location. If no content type ID is specified at that location, the parser assigns the default content type to the document. The parser then uploads the document and promotes any document properties accordingly.
If the document does contain a content type ID at the specified location, the parser determines if the content type with that ID is also associated with the document library. If it is, the parser uploads the document and promotes any document properties accordingly.
If the parser doesn't find an exact match, it examines ID's of the content types on the document library to determine if one or more are children of the document content type. If so, the parser assigns the closest child content type to the document. The parser then uploads the document and promotes any document properties accordingly.
Note The parser examines the list for content types that are children of the document content type because, in most cases, the document will have been assigned a site content type. In such cases, the matching list content type will be a child of the site content type.
If the parser finds no content type match at all, it then looks at the Field element in the document library schema that represents the document template column on the document library, if such a column is present. If the document library does contain a document template column, the parser examines the Field element for the location in the document where the document template should be stored. The parser then determines if the document template is indeed stored in the document at this location.
If the document does contain a document template, the parser compares the template with the document templates specified in each content type on the document library. If the parser finds a content type with the same document template as the document, the parser assigns that content type to the document. If there are multiple content types with the same document template as the document, the parser simply assigns the first such content type it finds. The parser then uploads the document and promotes any document properties accordingly.
Finally, if the parser cannot find a content type match, the parser assigns the default content type to the document. The parser then uploads the document and promotes any document properties accordingly.
The flow chart below illustrates the checks the parser performs to determine a document's content type.
For more information on how the parser promotes and demotes specific document properties, part two of this series.
One aspect of the parser's operation that bears emphasis is the fact the parser looks to the document library's content type and document template columns to determine where in the XML file to look for those matching document properties. Therefore, in order for promotion and demotion to work correctly, all content types on a given document library must contain content type and document template column definitions that specify the same location for those document properties as the document library columns. Otherwise, the parser will be looking in the wrong location within the document for those properties.
In the next entry, we’ll take a look at how you actually specify the content type of the document, inside that document itself.
This is the second in a five-part series on how to use the built-in XML parser in WSS V3 to promote and demote document properties in your XML files, including InfoPath 2007 forms.
When WSS V3 invokes the built-in XML parser to parse XML files, the parser uses the document's content type to determine which document properties map to which content type columns, and where those document properties are stored in the document itself. Therefore, to have WSS V3 use the built-in XML parser with your XML files, you must:
· Create a content type that includes the necessary parsing information. For each document property you want promoted and demoted, include a field definition that includes the name of the document property that maps to the column the field definition represents, and where the document property is stored in the document.
· Make sure that the content type ID is a document property that is demoted into the document itself. This ensures that the built-in XML parser can identify and access the correct content type for the document. (We’ll talk about this more in a later post.)
Content Type Information for XML Parsing
Document properties are promoted to and demoted from columns on the document library in which the document is stored. If the document is assigned a content type, these columns are specified in the content type definition. In the content type definition XML, each column included in the content type is represented by a FieldRef element.
Note Field elements represent columns that are defined for a site or list. FieldRef elements represent references to columns that are included in the content type. The FieldRef element contains column attributes that you can override for the column as it appears in this specific content type, such as the display name of the column, and whether it is hidden, or required on the content type. This information also includes the location of the document property to map to this column as it appears in the content type. This enables you to specify different locations for the document property that maps to the column in different content types.
Because of this, to specify the information the built-in XML parser needs to promote and demote a document property, you must edit the FieldRef element that represents the document property's corresponding column in the content type definition.
The figure below illustrations the actions the parser takes when an XML file is checked in to a document library. WSS V3 invokes the parser, which looks at the content type ID column to determine where in the document the document's content type ID is stored. The parser then looks inside the document for its content type at this location. The parser then examines the content type, to determine which FieldRef elements contain document property information. For each FieldRef element mapped to a document property, the parser looks for the document property at the location in the document specified in the matching FieldRef element. If the parser finds the document property at the specified location, it promotes that value to the matching column.
When an XML document is first uploaded to a document library, the built-in XML parser must first determine the content type of the document, and whether that content type is associated with the document library.
There are several attributes you can edit in a Field or FieldRef element to map that element to a document property and specify the location of the property in the document.
First, the Field or FieldRef element must contain an ID attribute that specifies the ID of the column in the document library. For example:
Next, add additional attributes to the Field or FieldRef element that specifies the location of the document property in the document. Document properties can be stored in either:
· The XML content of the document, or
· The processing instructions of the document.
The attributes you add to the Field or FieldRef element to specify the property location depends on whether the property is stored as XML content or processing instructions. These attributes are mutually exclusive; if you add an attribute that specifies a location in the XML content, you cannot also add attributes that specify a location in the processing instructions.
To edit a column’s field definition schema programmatically, use the SPField.SchemaXML object.
Specifying Properties in Document XML Content
If you store the document property in the document as XML content, you specify an XPath expression that represents the location of the property within the document. Add a Node attribute to the Field or FieldRef element, and set it equal to the XPath expression. For example:
Document Property Value Collections
If you specify an XPath expression that returns a collection of values, you can also include an aggregation attribute in the Field or FieldRef element. The aggregation attribute specifies the action to take on the value set returned. This action can be either an aggregation function, or an indication of the particular element within the collection.
Possible values include the following:
· plaintext Converts node text content into plain text.
· first Specifies that property promotion and demotion be applied to the first element in the collection.
· last Specifies that property promotion and demotion be applied to the last element in the collection.
Specifying Properties in Document Processing Instructions
Because processing instructions need not be just XML, XPath expressions are insufficient to identify document properties stored in processing instructions. Instead, you must add a pair of attributes to the Field or FieldRef element that specify the processing instruction and processing instruction attribute you want to use as a document property:
· Add a PITarget attribute to specify the processing instruction in which the document property is stored in the document.
· Add a PIAttribute attribute to specify the attribute to use as the document property.
These attributes would instruct the parser to examine the following processing instruction and attribute for the document property value:
You can also add another pair of attributes, PrimaryPITarget and PrimaryPIAttribute. This attribute pair is optional. Like PITarget and PIAttribute, they work in unison to identify the location of the document property. However, if they are present, the built-in XML parser looks for the document property in the location they specify first. If there is a value at that location, the parser uses that value and ignores the PITarget and PIAttribute attributes. Only if the location specified by the PrimaryPITarget and PrimaryPIAttribute attributes returns a null value does the parser then look for the document property at the location specified by the PITarget and PIAttribute attribute pair.
If you specify the PrimaryPITarget and PrimaryPIAttribute attributes, you must also specify PITarget and PIAttribute attributes. The parser only uses the PrimaryPITarget and PrimaryPIAttribute attributes if the processing instruction attribute specified by the PITarget and PIAttribute pair does not exist in the document, not if that attribute exists but is null or empty.
In my next post, we’ll discuss how the XML parser determines a document’s content type in the first place.