Contacts Wiki & Documentation Rss Feed

Updated Wiki: Home

JoeCastro — Mon, 02 Feb 2009 18:25:41 GMT

Use Windows Contacts from C#

Welcome!

Contacts.Net is a managed API for working with the new .Contact format introduced with Microsoft Windows Vista. This lets developers incorporate Windows Contacts into their applications using any .Net language, such as C#, VB.Net, C++/CLI, F#, etc., using a higher level and more strongly typed object model than what's exposed by the COM IContact APIs published with the Windows Vista SDK. Long term it is also intended to be a set of reusable widgets for displaying contact data in the context of larger programs, similar to what the WAB APIs offer.

Coding4Fun

Wow! Contacts.Net has been incorporated into the Coding4Fun developer kit (also hosted on Codeplex) :)
This is part of the Visual Studio Express release, and includes lots of useful utilities beyond contacts. The folks at Clarity Consulting have added classes and services on top of the core library - source included - that make using contacts in your app as easy as dragging items from the toolbar into your app. It even includes a sample address book built on top of it and a quick start guide describing how to create something similar. Very cool stuff! An overview of the entire kit is available at http://msdn2.microsoft.com/en-us/express/future/bb679917.aspx.

The version of Contacts used by C4F is based on Contacts.Net code close to the .8 release, so there's additional goodness in current releases that isn't in the dev kit.

There are some articles online using the C4F dev kit:
This is a sample that uses the Contacts component to copy your Facebook contacts to your bluetooth phone. (C#, VB.Net)
Scott Hanselman wrote a vCard preview handler using the dev kit. Sadly it was without using the Contacts library, but he mentions it kindly at the end of the post. (C#)

Current Release

The current release is called 1.0 and was released in August. It's a fully functional API for working with Contacts. It has all the capabilities of the Vista IContact COM APIs exposed so the property collections are strongly typed in addition to providing access via the property path approach of the native APIs. It contains numerous bug fixes and performance improvements over previous releases of Contacts.Net. This release accomplishes most of what I originally planned with this project, which is reflected in the version number.

The UI originally intended to be part of this has been forked into another project, Conmigo. As such this is still intended to be a developer release. The original loose UI is still present as an example of how the APIs can be used.

Some features contained in Contacts.Net that are more than what is available in the native IContact APIs include

Import and export from vCard format
Better group support, including the ability to work with two different types of groups: one is the .group format supported by WAB in Vista, the other is a format using the underlying XML schema that is consumable by clients directly accessing the XML.
The ability to work with contact collections not rooted in the user's Contacts folder.
User tile framing consistent with the Vista UI.
Per-property attribute information.
UI. For a preview, check out the Screenshots page.
Works on XP.

There's also a secondary release called ContactsBridge (similar to the Vista SDK's VistaBridge). It is purely a .Net wrapper on top of the native IContact APIs accessed via COM Interop. As such bugs and inconsistencies in the Vista implementation are exposed by it. It is a fork of an older version of the Contacts.Net library when more was being done via interop. It's still hosted here for propsperity as an academic example of a large COM interop library (again, similar to VistaBridge) or for those who have a need for using wab32 in a more direct way.

If you've been using previous versions of the library these are the Breaking Changes you should be aware of between different versions.

Code

The Class Diagrams page describes the APIs at a high level.
There is also a Sample Code page with simple examples of the library in action.

MSDN documentation about the COM interfaces provided with the Windows SDK is also available.

As part of developing this API, I've found some interesting behavior in the native implementation of the IContact APIs. These notes might serve well for developers working with the native APIs. They're archived in the Gotchas page.

See other developer tools that are part of Microsoft's shared source initiative at
http://www.microsoft.com/resources/sharedsource/Licensing/Developer.mspx

Updated Wiki: Home

JoeCastro — Fri, 17 Oct 2008 18:55:20 GMT

Use Windows Contacts from C#

First a note:
Please post questions to the discussions tab. That way I can get notifications when questions get asked, and it helps keep threads more organized for other people looking for similar answers. I'll do my best to answer questions wherever they're posted, but I may not notice right away comments made on the wiki pages.
Thanks!

Welcome!

Contacts.Net is a managed API for working with the new .Contact format introduced with Microsoft Windows Vista. This lets developers incorporate Windows Contacts into their applications using any .Net language, such as C#, VB.Net, C++/CLI, F#, etc., using a higher level and more strongly typed object model than what's exposed by the COM IContact APIs published with the Windows Vista SDK. Long term it is also intended to be a set of reusable widgets for displaying contact data in the context of larger programs, similar to what the WAB APIs offer.

Coding4Fun

Wow! Contacts.Net has been incorporated into the Coding4Fun developer kit (also hosted on Codeplex) :)
This is part of the Visual Studio Express release, and includes lots of useful utilities beyond contacts. The folks at Clarity Consulting have added classes and services on top of the core library - source included - that make using contacts in your app as easy as dragging items from the toolbar into your app. It even includes a sample address book built on top of it and a quick start guide describing how to create something similar. Very cool stuff! An overview of the entire kit is available at http://msdn2.microsoft.com/en-us/express/future/bb679917.aspx.

The version of Contacts used by C4F is based on Contacts.Net code close to the .8 release, so there's additional goodness in current releases that isn't in the dev kit.

There are some articles online using the C4F dev kit:
This is a sample that uses the Contacts component to copy your Facebook contacts to your bluetooth phone. (C#, VB.Net)
Scott Hanselman wrote a vCard preview handler using the dev kit. Sadly it was without using the Contacts library, but he mentions it kindly at the end of the post. (C#)

Current Release

The current release is called 1.0 and was released in August. It's a fully functional API for working with Contacts. It has all the capabilities of the Vista IContact COM APIs exposed so the property collections are strongly typed in addition to providing access via the property path approach of the native APIs. It contains numerous bug fixes and performance improvements over previous releases of Contacts.Net. This release accomplishes most of what I originally planned with this project, which is reflected in the version number.

The UI originally intended to be part of this has been forked into another project, Conmigo. As such this is still intended to be a developer release. The original loose UI is still present as an example of how the APIs can be used.

Some features contained in Contacts.Net that are more than what is available in the native IContact APIs include

Import and export from vCard format
Better group support, including the ability to work with two different types of groups: one is the .group format supported by WAB in Vista, the other is a format using the underlying XML schema that is consumable by clients directly accessing the XML.
The ability to work with contact collections not rooted in the user's Contacts folder.
User tile framing consistent with the Vista UI.
Per-property attribute information.
UI. For a preview, check out the Screenshots page.
Works on XP.

Updated Wiki: Breaking Changes

JoeCastro — Tue, 02 Sep 2008 16:47:06 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes between 1.0.1 and .9

Added Contact.GetAttributes function.
Added ILabeledPropertyCollection.GetNameAt
Added implicit cast operators for the TypeBuilder to Type conversions for types like Name, EmailAddress, PhysicalAddress, etc. This makes property setting syntax a bit less burdensome in languages like C#.
(New in 1.0.1) Renamed ContactTypes.Business to ContactTypes.Organization, along with the associated file extensions, due to strong customer feedback.

Breaking Changes between .8 and .9

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrint|Type| -> Thumbprint|Type|
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Replaced engendered PersonLabels with androgenous versions, e.g. Mother/Father -> Parent, Brother/Sister -> Sibling.
Changed the properties that are exposed on Person and PersonBuilder so that they don't affect each other as directly. A loaded Contact is no longer available from Person.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs (Not API breaking, but will result in different behaviors).

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

Updated Wiki: Class Diagrams

JoeCastro — Mon, 11 Aug 2008 18:43:50 GMT

These are snapshots of the pertinent class hierarchies in the project.
Sample Code is also available.

Updated Wiki: Breaking Changes

JoeCastro — Mon, 11 Aug 2008 18:36:34 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes between 1.0 and .9

Added Contact.GetAttributes function.
Added ILabeledPropertyCollection.GetNameAt
Added implicit cast operators for the TypeBuilder to Type conversions for types like Name, EmailAddress, PhysicalAddress, etc. This makes property setting syntax a bit less burdensome in languages like C#.

Breaking Changes between .8 and .9

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrint|Type| -> Thumbprint|Type|
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Replaced engendered PersonLabels with androgenous versions, e.g. Mother/Father -> Parent, Brother/Sister -> Sibling.
Changed the properties that are exposed on Person and PersonBuilder so that they don't affect each other as directly. A loaded Contact is no longer available from Person.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs (Not API breaking, but will result in different behaviors).

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

Updated Wiki: Version Roadmap

JoeCastro — Mon, 11 Aug 2008 18:32:33 GMT

Removed

Updated Wiki: Home

JoeCastro — Mon, 11 Aug 2008 18:31:37 GMT

Import and export from vCard format
Better group support, including the ability to work with two different types of groups: one is the .group format supported by WAB in Vista, the other is a format using the underlying XML schema that is consumable by clients directly accessing the XML.
The ability to work with contact collections not rooted in the user's Contacts folder.
User tile framing consistent with the Vista UI.
Per-property attribute information.
UI. For a preview, check out the Screenshots page.
Works on XP.

Updated Wiki: Home

JoeCastro — Mon, 11 Aug 2008 18:29:09 GMT

Import and export from vCard format
The ability to work with two different types of groups: one is the .group format supported by WAB in Vista, the other is a format using the underlying XML schema that is consumable by clients directly accessing the XML.
The ability to work with contact collections not rooted in the user's Contacts folder.
UI. For a preview, check out the Screenshots page.
Works on XP.

There's also a secondary release called ContactsBridge (similar to the Vista SDK's VistaBridge). It is purely a .Net wrapper on top of the native IContact APIs accessed via COM Interop. As such bugs and inconsistencies in the Vista implementation are exposed by it. It is a fork of an older version of the Contacts.Net library when more was being done via interop. It's still hosted here for propsperity as an academic example of a large COM interop library (again, similar to VistaBridge) or for those who have a need for using wab32 in a more direct way.

For specific details on the features being worked on in anticipation of "Contacts.Net 1.0" the Version Roadmap is being worked on.

If you've been using previous versions of the library these are the Breaking Changes you should be aware of between different versions.

Code

The Class Diagrams page describes the APIs at a high level.
There is also a Sample Code page with simple examples of the library in action.

MSDN documentation about the COM interfaces provided with the Windows SDK is also available.

As part of developing this API, I've found some interesting behavior in the native implementation of the IContact APIs. These notes might serve well for developers working with the native APIs. They're archived in the Gotchas page.

See other developer tools that are part of Microsoft's shared source initiative at
http://www.microsoft.com/resources/sharedsource/Licensing/Developer.mspx

Updated Wiki: Breaking Changes

JoeCastro — Thu, 07 Aug 2008 01:36:29 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes in current source tree and .9

Added Contact.GetAttributes function.
Added ILabeledPropertyCollection.GetNameAt
Added implicit cast operators for the TypeBuilder to Type conversions for types like Name, EmailAddress, PhysicalAddress, etc. This makes property setting syntax a bit less burdensome in languages like C#.

Breaking Changes between .8 and .9

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrint|Type| -> Thumbprint|Type|
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Replaced engendered PersonLabels with androgenous versions, e.g. Mother/Father -> Parent, Brother/Sister -> Sibling.
Changed the properties that are exposed on Person and PersonBuilder so that they don't affect each other as directly. A loaded Contact is no longer available from Person.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs (Not API breaking, but will result in different behaviors).

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

UPDATED WIKI: Breaking Changes

JoeCastro — Sat, 12 Apr 2008 22:31:08 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes in current source tree and .9

Added Contact.GetAttributes function.

Breaking Changes between .8 and .9

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrint|Type| -> Thumbprint|Type|
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Replaced engendered PersonLabels with androgenous versions, e.g. Mother/Father -> Parent, Brother/Sister -> Sibling.
Changed the properties that are exposed on Person and PersonBuilder so that they don't affect each other as directly. A loaded Contact is no longer available from Person.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs (Not API breaking, but will result in different behaviors).

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

UPDATED WIKI: Home

JoeCastro — Wed, 13 Feb 2008 16:28:38 GMT

Use Windows Contacts from C#

Welcome!

Contacts.Net is a managed API for working with the new .Contact format introduced with Microsoft Windows Vista. This lets developers incorporate Windows Contacts into their applications using any .Net language, such as C#, VB.Net, C++/CLI, F#, etc., using a higher level and more strongly typed object model than what's exposed by the COM IContact APIs published with the Windows Vista SDK. Long term it is also intended to be a set of reusable widgets for displaying contact data in the context of larger programs, similar to what the WAB APIs offer.

Coding4Fun

Wow! Contacts.Net has been incorporated into the Coding4Fun developer kit (also hosted on Codeplex) :)
This is part of the Visual Studio Express release, and includes lots of useful utilities beyond contacts. The folks at Clarity Consulting have added classes and services on top of the core library - source included - that make using contacts in your app as easy as dragging items from the toolbar into your app. It even includes a sample address book built on top of it and a quick start guide describing how to create something similar. Very cool stuff! An overview of the entire kit is available at http://msdn2.microsoft.com/en-us/express/future/bb679917.aspx.

The version of Contacts used by C4F is based on Contacts.Net code close to the .8 release, so there's additional goodness in current releases that isn't in the dev kit.

There are some articles online using the C4F dev kit:
This is a sample that uses the Contacts component to copy your Facebook contacts to your bluetooth phone. (C#, VB.Net)
Scott Hanselman wrote a vCard preview handler using the dev kit. Sadly it was without using the Contacts library, but he mentions it kindly at the end of the post. (C#)

Current Release

The current release is called .9 and was released in October. It's a fully functional API for working with Contacts. It has all the functionality of the Vista IContact COM APIs exposed so the property collections are strongly typed, in addition to providing access via the property path approach of the native APIs. It contains numerous bug fixes over previous releases of Contacts.Net.

This is still intended to be a developer release, although it does contain some loose UI. The point of the release is to solicit feedback on the APIs to verify correctness in implementation and design. As the version gets closer to a 1.0 much greater caution will go into making API and design changes. Code written against this version of the library should be easily changed to work with the eventual 1.0 release.

Some features contained in Contacts.Net that are more than what is available in the native IContact APIs include

Import and export from vCard format
The ability to work with two different types of groups: one is the .group format supported by WAB in Vista, the other is a format using the underlying XML schema that is consumable by clients directly accessing the XML.
The ability to work with contact collections not rooted in the user's Contacts folder.
UI. For a preview, check out the Screenshots page.

There's also a secondary release called ContactsBridge (similar to the Vista SDK's VistaBridge). It is purely a .Net wrapper on top of the native IContact APIs accessed via COM Interop. As such bugs and inconsistencies in the Vista implementation are exposed by it. It is a fork of an older version of the Contacts.Net library when more was being done via interop. It's still hosted here for propsperity as an academic example of a large COM interop library (again, similar to VistaBridge) or for those who have a need for using wab32 in a more direct way.

For specific details on the features being worked on in anticipation of "Contacts.Net 1.0" the Version Roadmap is being worked on.

If you've been using previous versions of the library these are the Breaking Changes you should be aware of between different versions.

Code

The Class Diagrams page describes the APIs at a high level.
There is also a Sample Code page with simple examples of the library in action.

MSDN documentation about the COM interfaces provided with the Windows SDK is also available.

As part of developing this API, I've found some interesting behavior in the native implementation of the IContact APIs. These notes might serve well for developers working with the native APIs. They're archived in the Gotchas page.

See other developer tools that are part of Microsoft's shared source initiative at
http://www.microsoft.com/resources/sharedsource/Licensing/Developer.mspx

UPDATED WIKI: Breaking Changes

JoeCastro — Tue, 30 Oct 2007 19:57:01 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes in current source tree and .9

None so far.

Breaking Changes between .8 and .9

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrint|Type| -> Thumbprint|Type|
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Replaced engendered PersonLabels with androgenous versions, e.g. Mother/Father -> Parent, Brother/Sister -> Sibling.
Changed the properties that are exposed on Person and PersonBuilder so that they don't affect each other as directly. A loaded Contact is no longer available from Person.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs.

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

UPDATED WIKI: Home

JoeCastro — Tue, 30 Oct 2007 19:56:09 GMT

Contacts.Net

Welcome!

Contacts.Net is a managed API for working with the new .Contact format introduced with Microsoft Windows Vista. Long term it is also intended to be a set of reusable widgets for displaying contact data in the context of larger programs, similar to what the WAB APIs offer.

Coding4Fun

Wow! Contacts.Net has been incorporated into the Coding4Fun developer kit (also hosted on Codeplex) :)
This is part of the Visual Studio Express Beta 2 release, and includes lots of useful utilities beyond contacts. The folks at Clarity Consulting have added classes and services on top of the core library - source included - that make using contacts in your app as easy as dragging items from the toolbar into your app. It even includes a sample address book built on top of it and a quick start guide describing how to create something similar. Very cool stuff! An overview of the entire kit is available at http://msdn2.microsoft.com/en-us/express/future/bb679917.aspx.

It's still beta (as is Contacts.Net) so feedback is appreciated. If you use it drop a line on the project's discussion page and let them know what you think.

Note: the version of Contacts used by C4F is close to the .8 release, plus extensions done by Clarity Consulting.

Current Release

The current release is called .9 and was released in October. It's a fully functional API for working with Contacts. It has all the functionality of the Vista IContact COM APIs exposed so the property collections are strongly typed, in addition to providing access via the property path approach of the native APIs. It contains numerous bug fixes over previous releases of Contacts.Net.

This is still intended to be a developer release, although it does contain some loose UI. The point of the release is to solicit feedback on the APIs to verify correctness in implementation and design. As the version gets closer to a 1.0 much greater caution will go into making API and design changes. Code written against this version of the library should be easily changed to work with the eventual 1.0 release.

Some features contained in Contacts.Net that are more than what is available in the native IContact APIs include

Import and export from vCard format
The ability to work with two different types of groups: one is the .group format supported by WAB in Vista, the other is a format using the underlying XML schema that is consumable by clients directly accessing the XML.
The ability to work with contact collections not rooted in the user's Contacts folder.
UI. For a preview, check out the Screenshots page.

There's also a secondary release called ContactsBridge (similar to the Vista SDK's VistaBridge). It is purely a .Net wrapper on top of the native IContact APIs accessed via COM Interop. As such bugs and inconsistencies in the Vista implementation are exposed by it. It is a fork of an older version of the Contacts.Net library when more was being done via interop. It's still hosted here for propsperity as an academic example of a large COM interop library (again, similar to VistaBridge) or for those who have a need for using wab32 in a more direct way.

For specific details on the features being worked on in anticipation of "Contacts.Net 1.0" the Version Roadmap is being worked on.

If you've been using previous versions of the library these are the Breaking Changes you should be aware of between different versions.

Code

The Class Diagrams page describes the APIs at a high level.
There is also a Sample Code page with simple examples of the library in action.

MSDN documentation about the COM interfaces provided with the Windows SDK is also available.

As part of developing this API, I've found some interesting behavior in the native implementation of the IContact APIs. These notes might serve well for developers working with the native APIs. They're archived in the Gotchas page.

See other developer tools that are part of Microsoft's shared source initiative at
http://www.microsoft.com/resources/sharedsource/Licensing/Developer.mspx

UPDATED WIKI: Breaking Changes

JoeCastro — Sun, 07 Oct 2007 06:26:55 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes in current source tree and .8

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrint|Type| -> Thumbprint|Type|
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Replaced engendered PersonLabels with androgenous versions, e.g. Mother/Father -> Parent, Brother/Sister -> Sibling.
Changed the properties that are exposed on Person and PersonBuilder so that they don't affect each other as directly. A loaded Contact is no longer available from Person.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs.

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

UPDATED WIKI: Breaking Changes

JoeCastro — Sun, 07 Oct 2007 06:15:53 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes in current source tree and .8

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrint|Type| -> Thumbprint|Type|
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Replaced engendered PersonLabels with androgenous versions, e.g. Mother/Father -> Parent, Brother/Sister -> Sibling.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs.

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

UPDATED WIKI: Breaking Changes

JoeCastro — Sun, 26 Aug 2007 06:16:11 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes in current source tree and .8

Renamed ContactManager.Import to ContactManager.AddContact.
The interop namespace is no longer public. It's functionality is still available through the ContactBridge project but the current release isn't so much wrapping the COM APIs as it is reimplementing the functionality. As such what's left of the namespace has been internalized.
FxCop property and class name cleanup, including:

Certificate/CertificateBuilder: Type -> ValueType, ThumbPrintType -> ThumbprintType
ContactType -> ContactTypes
EmailAddress/EmailAddressBuilder: Type -> AddressType
Name/NameBuilder: NickName -> Nickname
ContactCommitOptions.ForceSyncStorageWithFormattedName no longer includes the non-force flag value.
ContactCollectionChangedEventHandler -> EventHandler<ContactCollectionChangedEventArgs>

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs.

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

UPDATED WIKI: Home

JoeCastro — Mon, 13 Aug 2007 00:20:03 GMT

Contacts.Net

Welcome!

Contacts.Net is a managed API for working with the new .Contact format introduced with Microsoft Windows Vista. Long term it is also intended to be a set of reusable widgets for displaying contact data in the context of larger programs, similar to what the WAB APIs offer.

Coding4Fun

Wow! Contacts.Net has been incorporated into the Coding4Fun developer kit (also hosted on Codeplex) :)
This is part of the Visual Studio Express Beta 2 release, and includes lots of useful utilities beyond contacts. The folks at Clarity Consulting have added classes and services on top of the core library - source included - that make using contacts in your app as easy as dragging items from the toolbar into your app. It even includes a sample address book built on top of it and a quick start guide describing how to create something similar. Very cool stuff! An overview of the entire kit is available at http://msdn2.microsoft.com/en-us/express/future/bb679917.aspx.

It's still beta (as is Contacts.Net) so feedback is appreciated. If you use it drop a line on the project's discussion page and let them know what you think.

Current Release

There are actually two current releases:

The primary current release is called .8 and was released in June. It's a fully functional API for working with Contacts. It has all the functionality of the Vista IContact COM APIs exposed so the property collections are strongly typed, in addition to providing access via the property path approach of the native APIs.

There's also a secondary release called ContactsBridge (similar to the Vista SDK's VistaBridge). It is purely a .Net wrapper on top of the native IContact APIs accessed via COM Interop. As such bugs and inconsistencies in the Vista implementation are exposed by it. Your mileage may vary, but there are performance reasons one may want to use this one over version .8.

Both of these are still intended to be developer releases, though .8 does contain some loose UI. The point of the release is to solicit feedback on the APIs to verify correctness in implementation and design. As the version gets closer to a 1.0 much greater caution will go into making any API or design changes. Code written against this version of the library should be easily changed to work with the eventual 1.0 release.

Some features contained in Contacts.Net that are more than what is available in the native IContact APIs include

Import and export from vCard format
The ability to work with two different types of groups: one is the .group format supported by WAB in Vista, the other is a format using the underlying XML schema that is consumable by clients directly accessing the XML.
The ability to work with contact collections not rooted in the user's Contacts folder.
UI. For a preview, check out the Screenshots page.

For specific details on the features being worked on in anticipation of "Contacts.Net 1.0" the Version Roadmap is being worked on.

If you've been using previous versions of the library these are the Breaking Changes you should be aware of between different versions.

Code

The Class Diagrams page describes the APIs at a high level.
There is also a Sample Code page with simple examples of the library in action.

MSDN documentation about the COM interfaces provided with the Windows SDK is also available.

As part of developing this API, I've found some interesting behavior in the native implementation of the IContact APIs. These notes might serve well for developers working with the native APIs. They're archived in the Gotchas page.

See other developer tools that are part of Microsoft's shared source initiative at
http://www.microsoft.com/resources/sharedsource/Licensing/Developer.mspx

UPDATED WIKI: Breaking Changes

JoeCastro — Sat, 11 Aug 2007 22:15:52 GMT

This generally only covers changes to APIs that existed in the prior release. For overviews of architectural changes and additions you should consult the class diagrams that accompany the release.

Breaking Changes in current source tree and .8

Renamed ContactManager.Import to ContactManager.AddContact.
Much of the interop namespace is gone. Its functionality still available through the ContactBridge release but the COM interop declarations are being removed as they are no longer needed.

Breaking Changes between .8 and Contacts Bridge 1.0

Removed ContactManager constructors that allow for different RootDirectories
Removed ContactType enumeration and property from Contact

By extension, ContactCollection support for types other than .contact has been removed.

Removed GroupView and MapiGroupView
Removed managed shims atop IContactPropertyCollection and IContactManager - implementations are now direct callthroughs to Vista COM APIs.

Breaking Changes between .1 and .8

Renamed ContactManager.Load to ContactManager.GetContact
Person struct changed to add strong-typing to the PersonId format.
ILabeledPropertyCollection interface changed to have more indexer overloads so XAML will parse it.
Renamed ContactCommitOptions.Default to ContactCommitOptions.None (FxCop)
(Please add any others)

UPDATED WIKI: Gotchas

JoeCastro — Fri, 10 Aug 2007 20:11:59 GMT

This is a list of funny behavior found in the IContact APIs. Feel free to add and update as appropriate.
(To avoid accidental markup tags, some _'s are displayed at -'s)

IContactProperties

CreateArrayNode

The fAppend parameter only accepts 1 (TRUE) and 0 (FALSE). This is a stricter interpretation of the BOOL type than is generally used. Using any other value will return E_INVALIDARG.

DeleteArrayNode/DeleteProperty

These two can generally be used interchangeably. If validation is needed generally checking whether the last character is ']' should be sufficient.

GetLabels

Returns S-OK with an empty label-set for properties that don't exist in the contact (even ones that don't represent array nodes, like "Notes"). According to documentation (and reasonable expectations) it should return HRESULT-FROM-WIN32(ERROR-PATH-NOT-FOUND). If it matters, check for whether the property exists before requesting its labels.
Returns E_FAIL for simple extension array nodes that don't exist in the contact.

GetString

Returns S-OK for existing simple extension array nodes when there are child values. It's supposed to return S-FALSE, as that's the way to check for an array-node's existence. In addition, the concatenated child values are returned as the result of the GetString call.

SetBinary

The provided stream must both support Stat and have its Seek pointer set to the beginning of the stream, otherwise the function will return E_UNEXPECTED. This isn't currently documented in the IDL file or on MSDN.
The provided stream must also be non-empty.

SetString

Calls on simple extension array nodes return S-OK. It should return HRESULT-FROM-WIN32(ERROR-INVALID-DATA-TYPE). I haven't checked where it ends up in the backing XML or whether GetString returns the data, callers just shouldn't call SetString this way. The reason for calling this out is that the error code is a fast way of catching the mistake of setting the string on the return value of CreateArrayNode and forgetting to append an L3 property, so clients need to be a bit more proactively aware.

Contact's implementation of IPersistStream

Load

The internal implementation takes a reference to the provided stream via AddRef. It basically assumes that the stream is immutable, so in some circumstances it may reparse the stream. Callers need to be careful not to change it after it's been passed to the Load call. Managed callers need to be careful to respect the AddRef semantics and not dispose of the stream.

Save

For this call to work right clients need to ensure that the seek pointer of the stream being saved to is at the beginning of the stream and that the starting size of the stream is not larger than the contact data. If the contact is smaller than the original content then the garbage is left at the end and the stream won't contain valid XML.

IContactPropertyCollection

IContactPropertyCollection will sometimes skip over hierarchically stored simple extension properties. The rub of whether it gets skipped or not depends on whether the backing contact is in read-only mode. If the contact instance hasn't modified any data since it was loaded then generally it won't skip these values; otherwise it generally does. The workaround is to reload the contact for the enumeration, but I realize this isn't possible or pragmatic for most uses. A way to work around this is to save the contact to disk somewhere and then load the copy, performing the enumeration on that snapshot. (This is the way some versions of Contacts.Net hide the behavior).

Regarding Labels

Note that the following is about conventions. The following is not enforced by the APIs, native or managed.
Contacts use labels on hierarchical properties to provide additional context about data. For example, a physical address with the label "Personal" would indicate a home address. To avoid situations where a third party program's addition of a label changes the attributes of a property--e.g. adding "Summer House" to the "Personal" address doesn't necessarily make it no longer the home address--additional labels may be required on general properties to prevent ambiguities. This makes more sense with examples:

Use the "Voice" label for standard phone numbers. This disambiguates a "Business" phone number from a "Business" "Fax" phone number. Generally "Fax", "Pager", "Voice", "Video", and "TTY" are mutually exclusive and exactly one should be on any phone number.
To make a Photo appear as a user tile in programs, add the "UserTile" label.

UPDATED WIKI: Gotchas

JoeCastro — Thu, 09 Aug 2007 21:31:27 GMT

This is a list of funny behavior found in the IContact APIs. Feel free to add and update as appropriate.
(To avoid accidental markup tags, some _'s are displayed at -'s)

IContactProperties

CreateArrayNode

The fAppend parameter only accepts 1 (TRUE) and 0 (FALSE). This is a stricter interpretation of the BOOL type than is generally used. Using any other value will return E_INVALIDARG.

DeleteArrayNode/DeleteProperty

These two can generally be used interchangeably. If validation is needed generally checking whether the last character is ']' should be sufficient.

GetLabels

Returns S-OK with an empty label-set for properties that don't exist in the contact (even ones that don't represent array nodes, like "Notes"). According to documentation (and reasonable expectations) it should return HRESULT-FROM-WIN32(ERROR-PATH-NOT-FOUND). If it matters, check for whether the property exists before requesting its labels.
Returns E_FAIL for simple extension array nodes that don't exist in the contact.

GetString

Returns S-OK for existing simple extension array nodes when there are child values. It's supposed to return S-FALSE, as that's the way to check for an array-node's existence. In addition, the concatenated child values are returned as the result of the GetString call.

SetBinary

The provided stream must both support Stat and have its Seek pointer set to the beginning of the stream, otherwise the function will return E_UNEXPECTED. This isn't currently documented in the IDL file or on MSDN.
The provided stream must also be non-empty.

SetString

Calls on simple extension array nodes return S-OK. It should return HRESULT-FROM-WIN32(ERROR-INVALID-DATA-TYPE). I haven't checked where it ends up in the backing XML or whether GetString returns the data, callers just shouldn't call SetString this way. The reason for calling this out is that the error code is a fast way of catching the mistake of setting the string on the return value of CreateArrayNode and forgetting to append an L3 property, so clients need to be a bit more proactively aware.

Contact's implementation of IPersistStream

For this call to work right clients need to ensure that the seek pointer is at the beginning of the stream and that the starting size of the stream is not larger than the contact data. If the contact is smaller than the original content then the garbage is left at the end and the stream won't contain valid XML.

IContactPropertyCollection

IContactPropertyCollection will sometimes skip over hierarchically stored simple extension properties. The rub of whether it gets skipped or not depends on whether the backing contact is in read-only mode. If the contact instance hasn't modified any data since it was loaded then generally it won't skip these values; otherwise it generally does. The workaround is to reload the contact for the enumeration, but I realize this isn't possible or pragmatic for most uses. A way to work around this is to save the contact to disk somewhere and then load the copy, performing the enumeration on that snapshot. (This is the way some versions of Contacts.Net hide the behavior).

Regarding Labels

Note that the following is about conventions. The following is not enforced by the APIs, native or managed.
Contacts use labels on hierarchical properties to provide additional context about data. For example, a physical address with the label "Personal" would indicate a home address. To avoid situations where a third party program's addition of a label changes the attributes of a property--e.g. adding "Summer House" to the "Personal" address doesn't necessarily make it no longer the home address--additional labels may be required on general properties to prevent ambiguities. This makes more sense with examples:

Use the "Voice" label for standard phone numbers. This disambiguates a "Business" phone number from a "Business" "Fax" phone number. Generally "Fax", "Pager", "Voice", "Video", and "TTY" are mutually exclusive and exactly one should be on any phone number.
To make a Photo appear as a user tile in programs, add the "UserTile" label.