Development Environment

Now that we've reviewed the key server-side integration points within the server SDK, we hope that you're excited to actually create your own code that will work with Microsoft CRM. However, even if you're an expert developer, setting up and configuring a development environment for Microsoft CRM requires you to know a trick or two unique to the software. We've consolidated some of the key points into three categories:

• Configuring multiple Microsoft CRM installations

• WSDL reference

• Coding and testing tips

Configuring Multiple Microsoft CRM Installations

When you're creating custom code with the SDK, you obviously don't want your development coding to interfere with your Microsoft CRM users when they're using the system. Therefore, you should plan on creating at least two Microsoft CRM installations to minimize the impact of any coding development on your users. We'll refer to the system that your users are on as the production environment, and you'll write your code in the development environment. If possible, we recommend creating a third Microsoft CRM environment, commonly known as staging, for testing your changes before you push them live to production. Figure 9-13 shows one possible implementation of development, staging, and production environments.

Figure 9-13: Microsoft CRM environments

We recommend that you create at least two domains, one for production and one for development and staging. When planning your Microsoft CRM environments, be sure to keep the following in mind:

• You need a dedicated Web server for each of the staging and development environments, but these two environments can share the same Microsoft Active Directory domain and the same server running SQL Server between them. Virtual servers work well for your development and testing Web server environments, but try to avoid putting SQL Server on a virtual server, because you might experience mediocre performance.

• When Microsoft CRM creates the SQL Server databases, it uses the organization name that you entered in the installation wizard. However, you can enter any organization name you want, because it's not tied to the license key. This allows you to use the same server for multiple environments.

• Create organizational units (OUs) in your development Active Directory domain for each installation (one for staging, and one for development in our example). We recommend using the same OU name that you used for your database name so that it is easier to keep track of your installations.

• Although it's possible to share a SQL Server Reporting Services server across staging and development, we recommend that you create a dedicated Reporting Services server for each environment. This will allow you to manage the reports for each environment independently.

• Use the redeployment tools (provided for free by Microsoft) to synchronize your data between Microsoft CRM deployments on different domains. You will not be able to simply restore the databases, because the system GUIDs will not match between domains.

Note 

If you set up your production, staging, and development environments in the same domain, you could expedite migrations by simply restoring the SQL Server databases from one environment to another. Despite this potential benefit, we generally recommend against the single-domain setup. By using two different domains, you minimize the chances of accidentally damaging the production environment during your testing and development. However, if you're a risk-taker, maybe the single-domain installation fits you better!

WSDL Reference

After you set up your project file, you must add Web references to the two Web services. For simplicity, we recommend that you keep the naming convention of the Web references Microsoft uses for its sample code.

We showed you how to add the CrmService and MetadataService Web references to Visual Studio .NET one at a time. However, instead of adding the CrmService and Metadata Web references individually, you can also create a common assembly that contains both the CrmService and Metadata Web references. Then you can reference the common assembly in your other projects, which allows you to update the CrmService and Metadata Web services in a single place if you ever need to update this information.

Another tip related to the WSDL reference includes using a configuration file to set the Url property. You might have noticed in our code samples that we explicitly set the Url property of the CrmService and MetadataService classes. Here's an example.

 service.Url = "http://<crmserver>/mscrmservices/2006/crmservice.asmx"; 

But what would happen to our code when we have multiple CRM environments such as production, staging, and testing? Because each environment would have its own unique URL to the Web service APIs, we would have to update the URL, recompile, and then deploy. Obviously, that approach is not a good strategy.

So, instead of hard-coding the URL address in our web reference, we prefer to specify the Url property of the service by using a configuration setting so that each environment setting depends on simply updating a configuration file. Using a configuration setting technique will help you develop against one environment and compile your assemblies just once. You can then quickly deploy your solution to separate staging or production environments.

You could access this value from the registry or the Web.config file. The following code snippet shows one example of how to call a routine and use a configuration setting the Url property. We create a ConfigSettings class, which simply accesses two application-setting keys in your Web.config file. Then when you deploy your solution, you need only update the Web.config settings to point to the correct server. The code lists a simple class that contains two static strings that retrieve the Url values from the Web.config file. You would add the following class to the appropriate place in your project.

 public class ConfigSettings {  public static string CrmServiceUrl = System.Configuration.ConfigurationSettings.AppSettings ["CrmServiceUrl"];  public static string CrmMetadataUrl = System.Configuration.ConfigurationSettings.AppSetting s["CrmMetadataUrl"]; } 

Add the following two keys in your Web.config file. If your Web.config file already contains an <appSettings> node, just include <add> nodes.

 <appSettings>  <!-- Crm web service url -->  <add key="CrmServiceUrl" value="http:// <crmserver>/mscrmservices/2006/crmservice.asmx"/>>  <!-- Crm metadata web service url -->  <add key="CrmMetadataUrl" value="http:// <crmserver>/mscrmservices/2006/metadataservice.asmx"/> </appSettings> 

Make sure you reference the ConfigSettings class assembly, and then set the Url property as follows.

 CrmService service = new CrmService(); service.Credentials = System.Net.CredentialCache.DefaultCredentials; service.Url = ConfigSettings.CrmServiceUrl; 

Tip 

Are your custom entities or new attributes not appearing in IntelliSense in Visual Studio? Make sure that you have published your changes and updated your Web reference in Visual Studio. You can update the Web reference by right-clicking it and then clicking Update Web Reference.

Coding and Testing Tips

This section contains development and testing tips that we use when working on Microsoft CRM projects. We hope you find them as useful as we do. We'll review the following topics:

• Microsoft .NET Framework version 2.0 versus version 1.1

• Application Mode and Loader.aspx

• Enabling the default Internet Explorer context menu

• Accessing query string parameters

• Referencing the Microsoft CRM assemblies or files

• Authentication and coding with filtered views

• Web.config file considerations

• Server assembly impersonations

• Authentication to test different users and roles

• Enabling platform-level tracing

• Enabling development errors

Microsoft .NET Framework Version 2.0

As documented in the SDK, Microsoft CRM 3.0 does support writing client-side code using Visual Studio .NET 2005 and the .NET Framework version 2.0 that accesses the CRMService and MetadataService Web services. However, Microsoft CRM 3.0 does not support callout or workflow assemblies written in Visual Studio .NET 2005 and the .NET Framework version 2.0. You should still continue to use Visual Studio .NET 2003 and the .NET Framework Version 1.1 when creating custom assemblies for callouts and workflow.

Please review the latest SDK for the most up-to-date information on the support for .NET Framework Version 2.0.

Application Mode and Loader.Aspx

Of course you've noticed that Microsoft CRM launches into a special Internet Explorer window that does not have the menu bar, address bar, toolbar, and so on. Microsoft CRM refers to this as the Application Mode, and it runs in this mode by default. Often, developers need these additional Internet Explorer features that application mode hides. You can launch Microsoft CRM in a standard Internet Explorer window by browsing to http://<crmserver>/loader.aspx.

Using the Loader.aspx page disables application mode for that single Web session. You can also permanently disable application mode for all users and all sessions by updating the Web.config file.

Disabling Application Mode

1. On the Microsoft CRM Web server, navigate to <web installation path>\ (typically C:\Inetpub\wwwroot\).

2. Open the Web.config file in Notepad (or any text editor).

3. Look for the AppMode key, and change its value to Off.

4. Save the Web.config file.

Enabling the Default Internet Explorer Context Menu

In addition to running in Application Mode, Microsoft CRM modifies the standard Internet Explorer behavior by displaying its own context menu when you right-click in the application. Right-clicking a grid gives you options unique to Microsoft CRM, such as Open, Print, and Refresh List. However, right-clicking a form won't display a context menu like you would see on a normal Web page. When you're troubleshooting and debugging, you might find that you want to access the standard Internet Explorer context menu so that you can use features such as View Source, Properties, or Open In New Window. You can re-enable the Internet Explorer context menu by editing the Global.js file.

Re-Enabling the Internet Explorer Standard Context Menu

1. On the Microsoft CRM Web server, navigate to <web installation path>\_common\scripts (typically C:\Inetpub\wwwroot\_common\scripts).

2. Open the Global.js file in Notepad (or any text editor). Note: Do not double-click this file because it will attempt to execute the JavaScript file.

3. Right-click the file, and then click Edit.

4. Use your text editor's Find feature to locate the document.oncontextmenu() function.

5. Comment out the existing code in this function by adding /* and */ as shown in the following code. You can undo this change later by simply removing event.returnValue = true; line and the comment characters.

    function document.oncontextmenu() {  event.returnValue = true;  /*  var s = event.srcElement.tagName;  (!event.srcElement.disabled &&  (document.selection.createRange().text.length > 0 ||     s == "TEXTAREA" ||  s == "INPUT" && event.srcElement.type == "text"));  */ } 

6. Save the file.

7. Open a page in Microsoft CRM and right-click it. You will see the familiar Internet Explorer context menu.

   

Caution 

Use this technique on development servers only. Do not modify the Global.js file in a production or staging environment; this unsupported change might cause unpredictable behavior. Microsoft CRM prevents use of the right-click context menu for the user's benefit and also to maintain a predictable navigation structure in the application interface.

Accessing Query String Parameters

When testing or debugging your code, you will frequently need the GUID of an entity record or want to see the query string parameters that Microsoft CRM passed to the window. You can access the URL of any page and view its GUID by pressing Ctrl+N on your keyboard. Internet Explorer opens a new window, and the address bar displays its query string parameters. You can also press the F11 key when viewing a record to toggle the display so that the URL address bar appears.

If you have re-enabled the Internet Explorer context menu, you can also get this information by right-clicking the page and selecting Properties. You can then copy the URL from the Properties dialog box.

Referencing the Microsoft CRM Assemblies or Files

You should never reference any Microsoft CRM assemblies other than Microsoft.Crm.Platform .Callout.Base.dll. You also should not import any of the JavaScript, style sheets, or behavior files into your project. Microsoft will not support this type of code reuse, and you will probably experience significant code problems when Microsoft CRM releases hotfixes, updates, or patches.

Caution 

Because you're not supposed to even reference any of the Microsoft CRM assemblies other than Microsoft.Crm.Platform.Callout.Base.dll, it should also be pretty obvious that you shouldn't attempt to modify any of the Microsoft CRM .dll files, either.

If you want to mimic any look or functionality of Microsoft CRM, you must re-create it yourself. The SDK provides a sample style sheet and a UI Style Guide, but if you want to review and understand the native script files, you can find most of them in < web installation path>\_common. If you want to review styles or code, copy these files to your own directory.

Authentication and Coding with Filtered Views

The SQL filtered views provide an excellent method for you to quickly and easily retrieve Microsoft CRM data by using standard SQL Server connections. However, because the filtered views rely on Integrated Windows authentication for data security, you must pay attention to how your code connects to the filtered views.

If you were to go under the hood of a filtered view in SQL and look at its script, you would see that it uses a custom function to enforce the security settings.

 create function dbo.fn_FindUserGuid () returns uniqueidentifier as begin  declare @userguid uniqueidentifier  select @userguid = s.SystemUserId  from SystemUserBase s  where s.DomainName = SUSER_SNAME()  return @userguid end 

SUSER_SNAME() is a special function in SQL that returns the currently authenticated user, and the preceding function uses it to find the systemuserid identifier. If your code doesn't authenticate to SQL Server by using Windows authentication, your queries will never return any data, because all of the filtered views perform an inner join using systemuserid.

To connect to the database by using Windows authentication instead of SQL Server authentication, your connection string should include the following parameter: Integrated Security=SSPI. The full string would look something like this.

 server=databaseserver;database=yourcustomdatabase;Integrated Security=SSPI 

More Info 

Remember that you should never alter the Microsoft CRM databases by adding your own routines or stored procedures. Microsoft doesn't support this type of alteration, and it will probably result in the loss of your routines upon upgrades or hotfixes. Instead, you should create your own database to store your custom routines.

If you're calling your custom SQL routines from a Web page, you must configure additional settings to make sure that your Web page passes the integrated Windows credentials to SQL Server. First, the user should belong to the SQLAccessGroup, which will happen automatically when you add users to Microsoft CRM. Second, you must ensure that your Web application does not permit anonymous access by disabling anonymous access in IIS for your virtual directory or Web site. Finally, you must add or update the Web.config file in your custom web with the following nodes located in the <system.web> node set.

 <authentication mode="Windows" /> <authorization><deny users="?" /></authorization> <identity impersonate="true" /> 

These keys ensure that IIS uses the Windows credential set when accessing a page in your virtual web.

As we explained earlier, another consequence of the integrated security features in filtered views is that you can't use filtered views in callouts or in workflow assemblies. The callout and workflow engine runs under the security context of the user, and, because you cannot impersonate to SQL Server from your connection string, you cannot retrieve data by using the filtered views. In these cases, we recommend that you use the QueryExpression class because the Web service does allow impersonation.

Web.Config File Considerations

If you create custom pages that work with Microsoft CRM, you should deploy them to a directory outside of the Microsoft CRM root and create a new Web site or a new virtual directory. The easiest way to leverage cross-site scripting (see Chapter 10 for more details) is to set up a virtual directory underneath the Microsoft CRM web. When you create a virtual directory, you will inherit the Web.config settings of the parent web, which in this case would be settings from the Microsoft CRM Web.config file.

If you add your custom web files to a virtual directory underneath the Microsoft CRM web, you might receive an error similar to this one when accessing your custom pages:

• "File or assembly name Microsoft.Crm.Tools.ImportExportPublish, or one of its dependencies, was not found."

You have a couple of options for getting around this error. One is to register each of the assemblies that fail in the global assembly cache (GAC). The other is to remove these entries in your custom Web.config file. To remove the assemblies from your Web.config file, add the <remove> node for each Microsoft CRM assembly that fails to load in your custom application. Here's an example of how this looks.

 <compilation defaultLanguage="C#" debug="true">  <assemblies>   <remove assembly="Microsoft.Crm.Tools.ImportExportPublish, Version=3.0.5300.0, Culture= neutral, PublicKeyToken=31bf3856ad364e35"/>  </assemblies> </compilation> 

Warning 

Make sure that you add this to your Web.config file. Do not alter these values in the Microsoft CRM Web.config file.

Server Assembly Impersonation

You might find that you need to use the credentials of the user making the request in your callouts or workflow assemblies. The SDK documents this numerous times, but, because it is such a useful technique, we want to mention here, too. This code snippet shows how to accomplish impersonation.

 CrmService service = new CrmService(); service.Credentials = System.Net.CredentialCache.DefaultCredentials; service.Url = "http://<crmserver>/mscrmservices/2006/crmservice.asmx"; // Get the current user ID. WhoAmIRequest userRequest = new WhoAmIRequest(); WhoAmIResponse userResp = (WhoAmIResponse) service.Execute(userRequest); service.CallerIdValue = new CallerId(); service.CallerIdValue.CallerGuid = userResp.UserId; 

When you are using impersonation from a callout, the user context already contains the user ID for you. So, instead of making an additional request, you could simply use the following.

 CrmService service = new CrmService(); service.Credentials = System.Net.CredentialCache.DefaultCredentials; service.Url = "http://<crmserver>/mscrmservices/2006/crmservice.asmx"; service.CallerIdValue = new CallerId(); service.CallerIdValue.CallerGuid = userContext.UserId; 

Authentication to Test Different Users and Roles

When testing, you will often need to review users with different roles to validate security and custom functionality. Because Microsoft CRM uses your logon information for its authentication credentials, by default you will access the application under the Windows account that you used to access your computer. If you wanted to check the functionality of a different role, you would have to change the role of your account or log on with a different account.

Chapter 3, "Managing Security and Information Access," showed you in detail how to force the browser to prompt for credentials. This technique allows you to authenticate as different users without having to log off of your computer. Remember that this will affect all intranet web applications that you currently access. Another approach is to use the run as command to launch Internet Explorer. In a DOS prompt, you could execute the following: runas/user:domain\user "C:\Program Files\Internet Explorer\iexplore http://<crmserver>". You will then be prompted for a valid password and then Internet Explorer will launch under the specified user context.

Enabling Platform-Level Tracing

You might need to track down issues at the platform level to debug callouts, workflow, or even the Outlook client. Enabling this type of tracing requires a registry change. The locations of the registry settings are listed in Table 9-5.

Table 9-5: Registry Settings Locations

Web server	HKEY_LOCAL_MACHINE\Software\Microsoft\MSCRM
Outlook client	HKEY_CURRENT_USER\Software\Microsoft\MSCRMClient

To enable tracing, you must create the registry values listed in Table 9-5 in the appropriate key, as specified by Table 9-6.

Table 9-6: Registry Values

Name	Type	Data
TraceEnabled	dword	1
TraceDirectory	string	Enter a directory (such as C:\MSCRM\Tracing). Note that this directory must exist; Microsoft CRM will not create it for you.
TraceCategories	string	*:Verbose
TraceCallStack	dword	Off
TraceRefresh	dword	1
TraceSchedule	string	Hourly

Remember that tracing will negatively affect performance, so be sure to turn it off when it is no longer Prequired. To do this, change TraceEnabled to 0.

Caution 

We would be remiss if we didn't provide the obligatory warning from Microsoft when editing the registry: "Using Registry Editor incorrectly can cause serious, system-wide problems that may require you to re-install Windows to correct them. Microsoft cannot guarantee that any problems resulting from the use of Registry Editor can be solved. Use this tool at your own risk."

Enabling Development Errors

By default, Microsoft CRM displays a nice, user-friendly error message if it encounters a problem trying to execute a request. However, as you develop and troubleshoot your code, you'll want to see more descriptive information about any errors. You can enable detailed development errors (Figure 9-14) with a setting in the Web.config file.

Figure 9-14: Development errors enabled

Enabling Development Errors in the Web.Config File

1. On the Microsoft CRM Web server, navigate to <web installation path>\ (typically C:\Inetpub\wwwroot\).

2. Open the Web.config file in Notepad (or any text editor).

3. Look for the DevErrors key, and change its value to On.

4. Save the Web.config file.