Summary
- ASP.NET applications on the Microsoft Dynamics CRM 4.0 server
- ASP.NET applications for Microsoft Dynamics CRM 4.0 for Microsoft Office Outlook with Offline Access
- Plug-ins
- Custom workflow activities
- Scripting
- Setup and deployment
- Application configuration
Applies To
Microsoft Dynamics CRM 4.0
Microsoft Visual Studio 2005
Introduction
Both Microsoft Visual Studio 2005 and Microsoft Visual Studio 2008 serve as excellent platforms for application development for Microsoft Dynamics CRM. It is easiest to use a single Visual Studio solution to contain the projects that you create during your development cycle. It's important to understand the four fundamental kinds of projects that you can create:
- .NET applications that connect to Microsoft Dynamics CRM: These applications may be of any type as long as they can use SOAP Web services. Example types include Windows Forms, WPF Forms, console applications, Windows Services, and so on. You can use this kind of application for alternative UIs, tools, and application integration.
- ASP.NET applications that run 'inside' Microsoft Dynamics CRM: These Web applications run in the context of Microsoft Dynamics CRM itself. They must be coded, built, and deployed within specific boundaries. You can typically frame these applications within Microsoft Dynamics CRM as a pop-up window, IFRAME, or menu navigation.
- Plug-In/Workflow Assemblies: The classes in these DLLs are derived from Microsoft Dynamics CRM SDK classes or Microsoft Windows Workflow Foundation classes. The DLLs are then registered inside Microsoft Dynamics CRM to be executed at specific times. You can use these to run your complex business logic and to orchestrate complex integrations.
- Setup: You may want to create a setup project to deploy your projects to the Microsoft Dynamics CRM server and client computers.
Creating your Development Environment
When you set up your Microsoft Dynamics CRM development environment you have two choices to make: networked or stand-alone. If you use the networked approach you can set up a Microsoft Dynamics CRM server on your actual network by using physical or virtual computers. The stand-alone option is typically vertical using a "one-box" deployment.
For the networked approach you should follow the steps in the Microsoft Dynamics CRM 4.0 Implementation Guide. It's highly suggested that you configure the box for both regular Windows and Internet-facing deployment (IFD) authentication modes. Creating your own virtual one-box deployment might seem a bit difficult at first, but I assure you it is easy and doesn't take very long. This checklist will help you get started. Note that the order of doing this is important. You should read the Implementation Guide before you begin this process.
Creating a one-box deployment
- Hardware. At the moment, I use a Windows Vista Enterprise 64-bit on a Lenovo T60P with 4 GB of RAM. Some of my colleagues have also had success using USB sticks for ReadyBoost to increase the RAM. I put the VHD on the laptop's SATA drive. If you do use external drives, make sure that they are faster than the internal drive.
- I use Virtual PC for virtualization. Virtual Server is also a good option.
- The next step is to build out Windows Server Virtual Machine. Try to avoid pre-built VPCs as they tend to be loaded up with extraneous components.
- Do not join this computer to your domain. For now, keep it connected to a Workgroup.
- Hook your computer up to the Internet and run Windows Update.
- Now configure the VPC to use the Loopback Adapter. You might first have to install the Loopback Adapter on the host operating system (for example, Vista). Here is a screencast on how to do this: Configuring the Loopback Adapter.
- Change the IP address of the server to 192.168.1.1.
- Change the IP address of the host operating system to 192.168.1.2. Use 192.168.1.1 as the DNS Server.
- Next, make sure that the server is connected to this private loopback network. Now nothing from the outside except the host operating system can reach the server. This is a safety precaution
- Install Active Directory® on the server. For those who haven't done this in a while: type dcpromo at the command prompt. Make sure to remember the restore password.
- Now install Internet Information Services (IIS).
- Microsoft SQL Server® is next. Use Remote Desktop to connect to the server (at 192.168.1.1). You might want to use the IP instead of the server name because you may get netbios conflicts if your host server is also connected to another network. Install SQL Server and make sure that you install SQL Server Reporting Services. For your development computer, I also suggest you use mixed-mode SQL authentication. However, you should always avoid this in a production environment (for the usual reasons).
- Now install Visual Studio on the server. You may want it later for debugging.
- You may want to create a config file to make your server run in IFD mode. For more information, see the Microsoft Dynamics CRM 4.0 Implementation Guide.
· <CRMSetup>
· <Server>
· <ifdsettings enabled="true">
· <internalnetworkaddress>192.168.1.1-255.255.255.255</internalnetworkaddress>
· <rootdomainscheme>http</rootdomainscheme>
· <sdkrootdomain>crm.philiprichardson.org</sdkrootdomain>
· <webapplicationrootdomain>crm.philiprichardson.org</webapplicationrootdomain>
· </ifdsettings>
· </Server>
· </CRMSetup>
- Copy all the Microsoft Dynamics CRM files to the server. The DVD is a good option here as it contains all the prerequisites (such as Microsoft Visual C++®).
- To start the installer, open the command prompt and navigate to the server folder. Assuming that your config file is called ifd.xml, you can type the following:
· setupserver.exe /config ifd.xml
- Here is a screencast showing the installation experience: Installing CRM.
- Now Microsoft Dynamics CRM is ready to use. Restart the computer and make sure everything is working.
- Create some user accounts in the Active Directory of the server.
- Shut down the VPC and make the VHD file read-only. This is now your "base image."
- Now create a new Virtual Hard Drive with the type set to "Differencing". Parent this to the base image. This might sound a bit confusing at first. Try it out and read the VPC help files if you are unsure.
- Note that to access Microsoft Dynamics CRM by using IFD from the host operating system, you also have to add the IFD URL to your hosts file (C:\windows\system32\drivers\…). Map 192.168.1.1 to orgname.crm.philiprichardson.org, substituting the name of your deployment. Also note that you need the orgname in this mapping. Each time you create a new organization you need to add this to the host operating system's hosts file.
- Undo disks are also a good option on the Differencing VPC. Then, you can revert changes without creating a new VHD.
- Back up everything.
Now you have your environment ready to go and you can easily rebuild it if necessary.
Switching Between IFD and Windows
If you configured your development environment as described previously, you will notice that if you log on to the server using the IP address (192.168.1.1) or the Host file configured URL (such as http://contoso.crm.philiprichardson.org), you will be prompted for Windows Credentials.
I use a registry key on the Microsoft Dynamics CRM Server to change the internal subnet of the IFD setting. Microsoft Dynamics CRM looks at the IP address of the incoming request and, if this is in the internal range of the registry key, it gives you a "Windows experience." If the IP address is external, it gives you an "IFD experience."
For example, if the client is configured with an IP address of 192.168.1.2 (Subnet: 255.255.255.0):
- When the internal range is 192.168.1.1-255.255.255.0 you will get a Windows experience. This is the value that you provided in the config.xml file when you installed Microsoft Dynamics CRM.
- When the internal range is 192.168.1.1-255.255.255.255 you will get an IFD experience. This is because the client on the host operating system has an IP of 192.168.1.2 (Subnet: 255.255.255.0), which is outside the internal range.
Here are the two registry key modifications. Note that this is supported. For more information, see the Implementation Guide.
IFD Experience:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM]
"IfdInternalNetworkAddress"="192.168.1.1-255.255.255.255"
Windows Experience:
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSCRM]
"IfdInternalNetworkAddress"="192.168.1.1-255.255.255.0"
If you have your own network configuration, you will have to determine the network addresses and subnet masks on your own. I strongly suggest you read the Implementation Guide and the IFD Setup documentation. If your environment is located on your network, you may want to contact your network administrator to figure out the correct IP ranges.
Applications that Connect to Microsoft Dynamics CRM
Connecting to Microsoft Dynamics CRM 4.0 uses one of two methods: SQL and Web services. Both are valid techniques but they do not provide the same functionality.
SQL
This approach involves making a regular SQL connection (with a technology like ADO.NET, for example) and executing SQL statements. Microsoft Dynamics CRM 4.0 has a set of special SQL views that we call the Filtered Views. Each entity in Microsoft Dynamics CRM has a corresponding filtered view. For example, the Contact entity has a view called FilteredContact. These views join together all the information for this entity and they also link to the security tables that contain the row level security information. This means that if a user has access to, for example, only 15432 contacts out of 3 million in the database, when that user does a SELECT * FROM dbo.FilteredContact they will only see 15432 rows. The filtered views can only be used for retrieving data. You should never change the database data or schema by using SQL with Microsoft Dynamics CRM. The Microsoft Dynamics CRM middle tier must handle all data and schema transactions. Never make changes directly to the database. Reporting is the main scenario for using filtered views. You can use these views to generate most of your analysis and reporting for Microsoft Dynamics CRM 4.0. You might also use them with ADO.NET (or similar technologies) when you write applications. Please be aware that the views can be locked down by system administrators. My advice: only use the filtered views for analytical applications.
Web Services
Using Web services is the standard way to connect to Microsoft Dynamics CRM and manipulate the data and schema of the system. Many assumptions you might have made with Microsoft Dynamics CRM 3.0, which is single tenant, must be reconsidered. Our Web service is a SOAP service, which we feel is a great fit for a complex business system such as Microsoft Dynamics CRM. There are three Web services that you should consider in your application architecture:
CrmDiscoveryService: You can use this service to "discover" information about tenants (organizations) on a server (deployment). In some modes it will also issue security tickets.
CrmService: This is the "main" Web service. It handles the manipulation of an organization's transactional data.
MetadataService: This service handles the manipulation of an organization's metadata (schema).
Authentication
Understanding authentication plays a role in how you connect to Microsoft Dynamics CRM. There are four ways to perform authentication and not all are available to every deployment.
Integrated Authentication
Use integrated authentication within your firewall, where Integrated Windows Authentication works best.
Connect to the Discovery Service and get the organization details by using System.Net.CredentialCache.DefaultCredentials.
Create a CrmService by using the information from the organization details.
Conduct transactions through the CrmService using System.Net.CredentialCache.DefaultCredentials.
Internet-Facing Deployment
Internet-facing deployment (IFD) uses Active Directory at the back end but the credentials are collected using a Forms Authentication approach. Microsoft Dynamics CRM 4.0 (the on-premise version) uses Active Directory as the Identity store. Microsoft Dynamics CRM Online uses Windows Live ID.
Make an anonymous request to the Discovery Service to obtain the Microsoft Dynamics CRM Online Windows Live ID Policy.
Connect to Windows Live ID and supply the Policy, Windows Live ID UserName/Password. It will give you back a Windows Live ID Ticket.
Connect to the Discovery Service and get the organization details by using the Windows Live ID Ticket.
Create a CRM Ticket by using the Discovery Service and the Windows Live ID Ticket. A CRM Ticket is organization-specific.
Create a CrmService by using the CRM Ticket and organization details.
Conduct transactions by using the CrmService. The CRM Ticket will be passed in the SOAP header. It will authenticate you for a period of time (tickets do time out) against a specific organization.
The Microsoft Dynamics CRM SDK contains samples for each authentication pattern. To create applications that connect to Microsoft Dynamics CRM you need to understand the following concepts:
Where do I find the deployment? This really means: What is the URL for the Discovery service? There is only one Discovery service URL for Microsoft Dynamics CRM Online.
What organization do I want to connect to? Some applications always know this. Other applications may want to query the Discovery service for a list of all organizations that a user has access to, and then have the user select which organization to connect to. You have to create the UI for this.
What type of Authentication is being used? Integrated, Windows, IFD, or Windows Live ID. Maybe your applications will support some of these authentication types. If so, remember that you are responsible for the UI, so help out your users when connecting. Our Microsoft Dynamics CRM for Microsoft Office Outlook application is a good example of one these kinds of applications. It's worth looking at how we solved these UI problems and see what works or doesn't work in your application.
You have a choice of using our compiled type proxy or the Web Services Description Language (WSDL) when connecting to Microsoft Dynamics CRM. Note that there is not a type proxy for the Discovery service. However, the WSDL is the same for Windows, IFD, and Windows Live ID.
ASP.NET Applications on the Microsoft Dynamics CRM Server
In Microsoft Dynamics CRM 3.0, if you wanted to run an ASP.NET application on the same server as Microsoft Dynamics CRM you needed to use your own application pool. This application would then connect to Microsoft Dynamics CRM like an external application if it needed to read and write data in Microsoft Dynamics CRM. For credentials, these applications would simply use Integrated Windows Authentication because a majority of customers used this configuration.
With the introduction of Internet-facing deployment (IFD), which uses Forms Authentication for Active Directory credentials, you cannot rely on Integrated Windows Authentication for your application. It's important to recognize that all partner-hosted customers will use IFD and most on-premise customers will configure their systems to use IFD plus Windows Authentication. Developers should always consider IFD as a primary usage pattern for their applications.
Because IFD uses a Forms Authentication technology to collect Active Directory credentials, your own applications are faced with a problem. You can't use Integrated Windows Authentication because your application might be running outside the firewall where this authentication type becomes very "fragile," and you don't want to have to prompt the user for credentials. For this situation we have provided a special class in the Microsoft.Crm.Sdk.dll called CrmImpersonator. This class enables an application, which runs inside our context, to use the credentials of the logged on user.
The following ASP.NET code example shows how to create a new lead and display the GUID of the record it created. The aspx and aspx.cs files should be placed on the Microsoft Dynamics CRM server in a folder that is named ISV. The Microsoft.Crm.Sdk and Microsoft.Crm.SdkTypeProxy namespaces derive from two DLLs of the same name. These DLLs are always present with Microsoft Dynamics CRM so that you don't have to package them with your solution. However, you may want to reference them in your project. You can find the DLLs in the \Server\GAC folder of your installation files or in the SDK download.
using System;
using System.Configuration;
using System.Data;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Net;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;
public partial class _Default : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
//Retrieve the organization name from the query string.
string orgname = Request.QueryString["orgname"].ToString();
//Wrap the CRM Web Service Code in a using block.
using (new CrmImpersonator())
{
//Create a token with the static method. ExtractCrmAuthenticationToken
//The 'Context' used here is the Page.Context.
CrmAuthenticationToken token = CrmAuthenticationToken.ExtractCrmAuthenticationToken(Context, orgname);
CrmService service = new CrmService();
service.CrmAuthenticationTokenValue = token;
service.Credentials = CredentialCache.DefaultCredentials;
//Create the lead object as usual.
lead lead = new lead();
lead.subject = "Lorem";
lead.firstname = "John";
lead.lastname = "Smith";
lead.companyname = "Ipsum";
//Assign the owner as the caller ID from the token.
//If you don't do this, the owner will be SYSTEM.
lead.ownerid = new Owner();
lead.ownerid.type = EntityName.systemuser;
lead.ownerid.Value = token.CallerId;
//Create the lead on Skype.
Guid leadid = service.Create(lead);
}
//Display the GUID.
Response.Write(leadid.ToString());
}
}
Let's examine the anatomy of this code pattern:
- You need to possess some prerequisites such as Page.Context, organization name, and if you are using the Metadata Service, the MetadataService URL.
- The CrmAuthenticationToken was created using the static ExtractCrmAuthenticationToken method of the CrmAuthenticationToken class.
- You do not have to use the Discovery Service. This code can only access the Microsoft Dynamics CRM Server that the code is running on.
- You must manually set the owner of new records using the CallerId property of CrmAuthenticationToken. (See the previous code sample.)
ASP.NET Applications on the Microsoft Dynamics CRM Offline Client
Microsoft Dynamics CRM 4.0 enables you to write an ASP.NET application and put it on the offline client's Web server. This application can call the offline Web service platform to perform operations against Microsoft Dynamics CRM. These files are deployed in the [Program Files]\Microsoft Dynamics CRM\Client\res\Web\ISV\[Company Name]\[Application Name]. Typically you can use Windows Installer to distribute these files to clients.
When you execute your code offline there are several things that you need to know:
The organization name. You get this from the Registry.
The port number used by the local Web server. Typically, this is 2525.However, you should always check the registry in case there is an abnormal installation.
The service URLs. You can construct these by concatenating http://localhost + Port Number + the service path.
You always use Integrated Windows Authentication to access the offline Web services, regardless of the authentication type on the server (including Microsoft Dynamics CRM Online). You also don't have to wrap your code with a CrmImpersonator block. However if you do so, there is no harm. If you write symmetrical code for online/offline, make sure that you don't create the token using the ExtractCrmAuthenticationToken method because this is not available offline. You may want to check to see if the code is executing offline. One way to do this is to see if the Request.Url.Host is 127.0.0.1.
The following sample shows how this can easily be achieved.
using System;
using System.Collections;
using System.Configuration;
using System.Data;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;
using Microsoft.Win32;
using System.Text;
using System.Net;
public partial class Hello : System.Web.UI.Page
{
protected void Page_Load(object sender, EventArgs e)
{
//Retrieve the port and orgname from the Registry.
RegistryKey regkey = Registry.CurrentUser.OpenSubKey("Software\\Microsoft\\MSCRMClient");
string orgname = regkey.GetValue("ClientAuthOrganizationName").ToString();
string portnumber = regkey.GetValue("CassiniPort").ToString();
//Construct the URLs.
StringBuilder urlbuilder = new StringBuilder();
urlbuilder.Append("http://localhost:");
urlbuilder.Append(portnumber);
urlbuilder.Append("/mscrmservices/2007/");
string crmserviceurl = urlbuilder.ToString() + "crmservice.asmx";
//Create your token as usual.
//Offline always uses Integrated Windows Authentication regardless of the Authentication on the server.
CrmAuthenticationToken token = new CrmAuthenticationToken();
token.OrganizationName = orgname;
token.AuthenticationType = 0;
CrmService service = new CrmService();
service.CrmAuthenticationTokenValue = token;
service.Credentials = CredentialCache.DefaultCredentials;
service.Url = crmserviceurl;
WhoAmIRequest request = new WhoAmIRequest();
WhoAmIResponse response = (WhoAmIResponse)service.Execute(request);
Response.Write(response.UserId.ToString());
}
}
