Both the CrmService and MetadataService provided by the Microsoft Dynamics CRM SDK contain functionality that you can use in your offline programming. You can further extend the Microsoft Dynamics CRM for Outlook client using the Microsoft Dynamics CRM Outlook SDK.
Note
In offline mode the Microsoft Dynamics CRM Web services will always use integrated authentication to authenticate the user. You cannot use impersonation while offline.
You can use the CrmService offline in the same way you use it online. Any data manipulation done in offline mode is stored in the user’s local database and Microsoft Dynamics CRM will automatically synchronize with the main database the next time the user goes online.
Warning
The synchronization process does not merge field-level changes with existing data. If you update a record offline, the sync process will update the entire record on the server. It’s possible to encounter a scenario where an offline user modifies a record, and an online user modified that same record during the time the user was offline. In this scenario, the user who modified the record last wins and his changes survive on the server. This is true even if the two users modified different fields on the record.
You can check whether a CrmService message is available offline by checking its availability, which you can do by querying the sdkmessage entity and checking its availability attribute. Table 10-1 contains a list of the possible availability values and what they mean. If the message can be used for more than one entity, you should also query the sdkmessagefilter entity’s availability attribute to make sure the message works for the entity you are trying to use it with. For example, the Create message works both online and offline, but the AddMemberList message only works online.
Table 10-1. Message Availability Values
Value | Description |
|---|---|
0 | Message is only available on the server (online). |
1 | Message is only available on the client (offline). |
2 | Message is available both on the server and the client (online and offline). |
The Microsoft Dynamics CRM 4.0 SDK contains a list of entities that are available for offline use. You can also check this programmatically by retrieving the entity’s EntityMetadata and checking its EntityMetadata.IsAvailableOffline property. The IsAvailableOffline property is a CrmBoolean data type. The following code sample shows an example of checking an EntityMetadata’s offline availability:
// entityMetadata is an instance of the EntityMetadata class
if (entityMetadata.IsAvailableOffline.Value)
{
// custom offline logic here
}To create an instance of the CrmService offline, you need to extract a few values from the registry. Because the offline Web site is running on the local Cassini Web server we can use "localhost" as the server name. As you can see from the following code sample, we then need to grab the port number from the CassiniPort registry entry and the organization name from the ClientAuthOrganizationName registry entry. We can then construct our server as we normally would.
RegistryKey regkey = Registry.CurrentUser.OpenSubKey("Software\Microsoft\MSCRMClient");
string orgName = regkey.GetValue("ClientAuthOrganizationName").ToString();
string portNumber = regkey.GetValue("CassiniPort").ToString();
string baseUrl = "http://localhost:" + portNumber + "/mscrmservices/2007/";
crmUrl = baseUrl + "crmservice.asmx";
CrmAuthenticationToken token = new CrmAuthenticationToken();
token.OrganizationName = orgName;
token.AuthenticationType = 0;
CrmService service = new CrmService();
service.Credentials = System.Net.CredentialCache.DefaultCredentials;
service.CrmAuthenticationTokenValue = token;
service.Url = crmUrl;
When using the MetadataService offline, only the retrieve messages are available. You cannot manipulate entities—such as programmatically adding an attribute—while offline. This restriction is in place to prevent a conflict when the user goes online and the databases are synchronized. Chapter 8, contains sample code for creating the MetadataService while running in offline mode.
You can use the Microsoft.Crm.Outlook.Sdk assembly to customize Microsoft Dynamics CRM for Outlook. The assembly contains a class named CrmOutlookService that has a few useful methods for programming for offline. To use the CrmOutlookService you create an instance the same way you do with the CrmService class. Table 10-2 lists the methods available for you to use from the CrmOutlookService instance, and Table 10-4 lists all of its properties. The State property of the CrmOutlookService has a value with the type of ClientState. Table 10-5 lists all of the possible ClientState values.
Table 10-2. CrmOutlookService Methods
Name | Description |
|---|---|
Gooffline | Executes the same functionality as the Go offline button. The online database data and customizations are synchronized to the user’s local database. |
GoOnline | Executes the same functionality as the Go Online button. The user’s local database with be synchronized with the online database. |
SetOffline | Sets Microsoft Dynamics CRM for Outlook with offline Access to offline mode without synchronizing the online database with the local offline database. |
Sync | Executes the synchronization between the online Microsoft Dynamics CRM database and Microsoft Dynamics CRM for Outlook. |
The Sync method on the CrmOutlookService takes one argument of the type OutlookSyncType. This determines whether the online data will be synchronized with the client computer’s Outlook store (for example, contacts, tasks, and appointments), the offline database, or the client computer’s Outlook address book. Table 10-3 contains possible values for the OutlookSyncType enumeration.
Table 10-3. OutlookSyncType Members
Name | Description |
|---|---|
Outlook | The synchronization occurs between Microsoft Dynamics CRM and the client computer’s Outlook store. |
AddressBook | The synchronization occurs between Microsoft Dynamics CRM and the client computer’s Outlook address book. |
offline | The synchronization occurs between Microsoft Dynamics CRM and the local offline database. |
Table 10-4. CrmOutlookService Properties
Name | Type | Description |
|---|---|---|
IsCrmClientLoaded | Boolean | Returns true if the Microsoft Dynamics CRM for Outlook client has been loaded by Microsoft Outlook. |
IsCrmClientOffline | Boolean | Returns true if Microsoft Dynamics CRM for Outlook with offline Access is currently in offline mode. |
Boolean | Returns true if Microsoft Dynamics CRM for Outlook has been installed. Returns false if Microsoft Dynamics CRM for Outlook with offline Access has been installed. | |
ServerUri | Uri | Returns the Uri to connect to the Microsoft Dynamics CRM SDK. The return value differs depending on whether the client is online or offline. |
State | ClientState | Returns the current state of the client. |
Table 10-5. ClientState Members
Field | Description |
|---|---|
Online | The client is online. |
Offline | The client is offline. |
SyncToOutlook | The client is currently in the synchronization process between the online server and Outlook. |
SyncToOutlookError | An error has occurred during the synchronization with Outlook. |
Goingoffline | The client is currently in the process of going into offline mode. |
GoingOnline | The client is currently in the process of going into online mode. |
ClientLoadFailure | Microsoft Outlook failed to load the Microsoft Dynamics CRM for Outlook client. |
ClientVersionLower | The client version is lower than the version of Microsoft Dynamics CRM installed on the server. |
ClientVersionHigher | The client version is higher than the version of Microsoft Dynamics CRM installed on the server. |
PostofflineUpgrade | The client has been upgraded while in offline mode. |
OnlineCrmNotAvailable | The online Microsoft Dynamics CRM server is currently unavailable. |
GoingofflineCanceled | The user canceled the process of going offline. |
BackgroundGoingoffline | The process of synchronizing the offline database is currently running in the background. |