一、Microsoft Dynamics CRM 4.0 SDK概述

Chapter 1. Microsoft Dynamics CRM 4.0 SDK Overview(SDK概述)

You are probably reading this book because your organization recently purchased Microsoft Dynamics CRM or because your organization is evaluating it. As a developer, you want to know what this new software application will mean to your day-to-day life. Will it cause you nightmares and sleepless nights? Or will it be a dream to work with and solve all your current development headaches? As you might guess, the true answer lies somewhere in between. However, we strongly believe that if you take the time to learn the Microsoft Dynamics CRM application, you will find yourself much closer to the latter. If you're new to Microsoft Dynamics CRM, your initial questions might include the following:

你或许正在学习这本书，因为你的部门最近需要采购Microsoft Dynamics CRM或者在研究它。 作为一个开发者，你需要去了解CRM软件程序对你以后生活的意义。它会导致你的噩梦和失眠？或者导致你对于CRM开发头疼？因此你可以猜猜，真实的答案就在这两者之间。然后， 我们必须相信如果你花费时间去学习CRM应用，你会发现你自身与它更进一步了。如果你是CRM的初学者，你最初的问题可能包含以下几方面：

• Will the software limit what I can do?在使用 CRM应用过程中，我们会有什么限制？

• How do I customize and extend the software?改如何实现自定义扩展CRM软件？

• What types of resources are available to help me with the software?有些什么资源能帮助我学习CRM软件？

We wrote this book to explain how professional software developers can extend the Microsoft Dynamics CRM software application to meet their business needs. To create customizations and integrations outlined in this book, you must be comfortable developing Web-based applications using tools such as Microsoft Visual Studio. We assume you have working knowledge of Visual Studio and Web application configuration with Microsoft Internet Information Services (IIS). Even if you're not a developer, you might benefit from reading these chapters to understand the different types of customizations that the Microsoft Dynamics CRM programming model makes possible.

我们写这本书是为了阐述作为一个职业化的软件开发者如何能扩展CRM应用来满足我们的业务需要。当你要很方便快速使用Microsoft Visual Studio开发web应用，你需要去学习本书的定制化和集成化的讲解。我们建设你在web开发和iis方面有一定的经验。 即使你不是一个开发者， 你去阅读本书也对你在CRM方面了解不同的定制化开发有一定的帮助。

From a very high level, Microsoft Dynamics CRM is just a large and sophisticated Web application. The application serves Web pages through IIS while accessing data from a Microsoft SQL Server database. Consequently, users access data through a Web browser, in addition to having the option to install Microsoft Office Outlook integration software. For most developers, we recommend that they simply think of Microsoft Dynamics CRM as a typical Web application.

从一定角度讲，CRM仅仅是一个大型的、复杂的web应用。这个应用支持通过IIS访问web网页来获取书MS SQL Server数据库的数据。因此，用户获取数据要通过web浏览器，除此之外还可以通过office outlook集成来访问。对于大多数开发者，我们建议最好把CRM当做一个典型的web应用来看会更简单。

This chapter introduces three topics regarding programming Microsoft Dynamics CRM:

本章节包含3个主题：

• The Software Development Kit   软件开发包

• A hitchhiker's guide to common questions  常见问题

• Microsoft Dynamics CRM as a business-application platform  CRM业务应用平台

The subsequent chapters dive into the Microsoft Dynamics CRM software architecture and provide programming examples.

以下子章节主要研究CRM软件架构和提供编程示例。

Software Development Kit Introduction

软件开发包介绍

Like many commercial software applications, Microsoft Dynamics CRM offers a Software Development Kit (SDK) that documents how you can customize and extend the system. The SDK consists of many different components related to extending the software:

与很多商业软件应用一样，CRM提供一个软件开发包来实现定制化和扩展系统。 SDK包含很多辅助扩展软件不同的组件：

• A compiled Help file that documents the application's architecture and programming interfaces, provides a report writer's guide, and offers additional development information  编译的帮助文档来讲述应用系统的架构和编程接口、指导和开发信息。

• Microsoft Dynamics CRM 4.0 user interface style guide CRM 4.0用户操作手册

• Code samples (walkthroughs) 示例代码(测试过)

• Helper classes and utilities  帮助类和工具

• Graphic images 图像

• The SDKreadme.htm file, which documents any known issues  这个SDKreadme.htm文件包含了一些常见的问题

Sometimes people refer to just the compiled help file as the SDK, but you can see all of these documents when you download the SDK and extract the files.

有时候仅仅参考帮助文件作为SDK，但是当你下载和解压SDK的时候，你能看到所有文档。

Important 注意

Microsoft updates the SDK on a periodic basis (approximately once every two or three months), so be sure to obtain the latest version. You can download the Microsoft Dynamics CRM 4.0 Software Development Kit at http://www.microsoft.com/downloads/details.aspx?FamilyID=82E632A7-FAF9-41E0-8EC1-A2662AAE9DFB.

Microsoft更新SDK有一定的周期（大约每两或者三个月更新一次）， 所以你必须确定你获取的是最新版本。你可以在http://www.microsoft.com/downloads/details.aspx?FamilyID=82E632A7-FAF9-41E0-8EC1-A2662AAE9DFB网站去下载CRM4.0最新软件开发包。

As part of the SDK, Microsoft documents all of the supported interaction points—also known as application programming interfaces (APIs)—that you can use when writing code that integrates with Microsoft Dynamics CRM. Using the APIs for your customizations provides several significant benefits:

作为SDK的一部分，Microsoft记录了相关开发知识点-----也叫做应用开发接口APIs。在编写代码做CRM集成的时候，你可以使用这些API。 使用API做定制化可以提供一下几点有意义的好处：

• Ease of use The APIs include hundreds of pages of documentation complete with real-world examples, code samples, and helper classes to help you write code that works with Microsoft Dynamics CRM.  易用性   API包含了上百页的文档来提供真实的示例，代码示例和帮助类来来帮助你在CRM上编写代码。

• Supportability If you encounter technical problems or issues using the APIs, you can contact Microsoft technical support or use the Microsoft Dynamics CRM public newsgroup for assistance. 支持性   如果遇到技术方面的问题或者使用API上的问题，你可以联系微软技术支持或者使用CRM公布的新闻组来协助。

• Upgrade support Microsoft makes every effort to ensure that the code you create for Microsoft Dynamics CRM using the APIs upgrades smoothly to future versions of the product, even if the underlying Microsoft SQL Server database changes radically. This is also true for any updates and hotfixes that Microsoft might release for Microsoft Dynamics CRM.  升级支持  微软尽一切努力来确定你使用的是API是最新的CRM产品版本， 即使是MS SQL Server数据库根本上的变动。有任何更新和升级微软都会重新发布CRM。

• Certification By following the documented APIs, you can submit your customizations to a third-party testing vendor to certify that your application works within the confines of the SDK. This certification provides comfort and reassurance for people evaluating your customizations. 认证  遵循API， 你可以提交你的定制化给第三方测试你的应用程序是工作在SDK范围内的。可以为其他人去研究你的定制化提供舒适安心的证明。

  Hitchhiker's Guide to Common Questions(常见问题)

  Throughout the years we've worked with Microsoft Dynamics CRM, we find that a common set of developer questions pop up again and again. This section lists some of these questions and points you to the chapters in this book where you can find additional details about what you're trying to accomplish.

  通过这些年在CRM方面的经验，我发现开发者在开发过程中经常遇到的一些问题。本节将要列举这些问题和本书中在尝试过程中遇到的一些问题。

  Can we alter the CRM database structure to add our custom tables and columns?我们能再CRM数据结构中增加表和字段吗？

• Yes, you can extend the Microsoft Dynamics CRM database with new entities (tables), attributes (columns), and relationships (keys). You can also add new attributes to the out-of-box entities. However, you do not make these modifications to SQL Server directly. Instead you use one of two different tools to modify the database:
  是，你可以扩展CRM数据库的实体(表)，属性(字段)和关系(键)。你可以增加新的属性到存在的实体中。然后，你是不能直接修改SQL Server数据库的， 取而代之的是使用2个不同的同居来修改数据库：

  • A Web-based customization tool  web-based定制化工具

  • The metadata API   元数据API

  For more information about using the Web-based customization tool, please refer to the book Working with Microsoft Dynamics CRM by Mike Snyder and Jim Steger (Microsoft Press, 2008). That book includes several chapters on using the Web-based customization tools to modify the data structure.

  The metadata API allows you to programmatically modify the database, including adding new attributes, entities, and so on. In this book, please refer to Chapter 8, "Developing with the Metadata Service," for more information about programmatically modifying the database.

  Important

  Even though you can technically modify the database structure directly within SQL Server, you should not attempt to do so because the modifications might cause unintended consequences in your application, including possible data loss or system corruption. The Microsoft Dynamics CRM customization tools and the metadata API provide all of the resources you need to modify the database structure.

  Another related question we frequently hear is "What does the database structure look like?" Although Microsoft Dynamics CRM does use a SQL Server database, theoretically you should not need to poke around the database structure or examine it. You can access data about the entities through the user interface or the metadata API. To further emphasize this idea, we want to point out that Microsoft released logical database diagrams for Microsoft Dynamics CRM 4.0. These logical database diagrams do not include the actual table structure; instead, they list the abstracted logical structure just as you utilize it through the user interface and API. You can download and view the Microsoft Dynamics CRM 4.0 logical database diagrams from http://www.microsoft.com/downloads/details.aspx?FamilyID=b73912e8-861e-43ae-97b4-72b3e809f287&DisplayLang=en. These database diagrams show the logical data relationships and the linked attributes between entities in Microsoft Office Visio format.

  In addition to the logical database diagrams, you can also view information about the entities and entity relationships through the Metadata browser at http://< yourcrmserver >/< yourorganizationname >/sdk/list.aspx (see Figure 1-1).

  Figure 1-1. The Microsoft Dynamics CRM Metadata browser

  

  Lastly, you can also use the metadata service API to programmatically view data about the database schema, attribute values, relationships, and so on.

  If you're just dying to see the underlying database structure, of course you can simply open SQL Server and examine it for yourself. You will find that Microsoft Dynamics CRM uses a normalized underlying database structure with clearly named tables such as account_base and account_extensionbase.

  How do we write custom code that gets data into and out of Microsoft Dynamics CRM?

  When you create custom code that needs to interact with Microsoft Dynamics CRM data, you should use one of two techniques:

  • CrmService Web Service An API that performs authentication and supports common data requests such as create, read, update, and delete. This API uses a Web service interface.

  • Filtered views Filtered views are SQL Server database views that your custom application can query to obtain read-only information about records.

  You should avoid creating custom code that accesses the SQL Server database tables directly—please stick to one of these two techniques. Both of these interfaces abstract the underlying database from your code so that if necessary Microsoft can modify the SQL Server database for hotfixes, new versions, and so on. If your custom code accesses a database table directly and then Microsoft needs to modify it, your custom code will probably break. However, if your code accesses the CrmService Web service or a filtered view, Microsoft updates these interfaces with the corresponding database changes so that your code continues to run as-is.

  While the CrmService Web service provides access to data about records, Microsoft Dynamics CRM includes two additional Web services that you can utilize:

  • MetadataService Web Service This Web service provides an API that allows you to query and manipulate the data structure.

  • CrmDiscoveryService Web Service This Web service provides an API that allows you to query for information about the Microsoft Dynamics CRM installation.

  Refer to Chapter 3, "Communicating with Microsoft Dynamics CRM APIs," for information about connecting to the APIs. Chapter 8 includes a deeper look at retrieving and modifying the database schema programmatically.

  Can we change the current CRM form layouts and controls?

  Yes, Microsoft Dynamics CRM offers multiple tools to modify the existing forms. The Web-based customization tools allow you to:

  • Add, remove, and modify form fields.

  • Add, remove, and move tabs.

  • Change field and tab labels.

  Figure 1-2 shows the form editor for the contact entity.

  Figure 1-2. The contact form editor

  

  Many of the attributes on the form include built-in controls such as a calendar for date fields, drop-down menus for picklist fields, check boxes for bit fields, and so on. Obviously this form editor provides great convenience for you to add and remove fields, in addition to changing the form layout. The book Working with Microsoft Dynamics CRM includes several chapters explaining how to modify form layouts.

  However, if you want to use different controls than the ones included by default, Microsoft Dynamics CRM does not include a tool to swap out the default controls with your controls. However, you can implement your own custom controls by using a combination of IFrames and your own custom Web pages. An IFrame allows you to embed a custom Web page into a Microsoft Dynamics CRM form so that it appears in the context of other Microsoft Dynamics CRM fields. For more information on creating custom user controls, please refer to Chapter 14, "Developing Custom Microsoft Dynamics CRM Controls."

  How do we implement our own custom business logic?

  Microsoft Dynamics CRM includes several different options for implementing your custom business logic:

  • Form scripting events Microsoft Dynamics CRM offers onSave, onLoad, and onChange form events that you can use to trigger form scripting code.

  • Server-side events You can register Microsoft .NET assemblies that contain your custom code, and Microsoft Dynamics CRM will trigger these assemblies based on the user operations you configure, such as creating a record, deleting a record, assigning a record, and so on. These .NET assemblies are known as plug-ins in Microsoft Dynamics CRM, and you can run them either synchronously or asynchronously.

  • Microsoft Dynamics CRM Workflow This option uses the Windows Workflow Foundation framework to create business automation processes triggered by the actions you configure. Sample workflow rules include e-mail alerts, task creation, record assignment, and so on.

  • Custom Web pages You can embed your own custom Web pages directly within the Microsoft Dynamics CRM application and user interface. These pages can contain any type of business logic that you deem necessary.

  As you would expect, you configure form scripting events on a record's form that Microsoft Dynamics CRM can trigger when a user saves a record, loads a form, or changes a field's data value. Form scripting events allow you to perform conditional form manipulation such as updating one field's value based on the value of a different field, or changing the form layout that a user sees based on the security role of the user viewing the record. You use JavaScript as your form scripting language. Figure 1-3 shows where you can load script onto a form. Please refer to Chapter 7, "Form Scripting," for a detailed look at the client script programming model. Microsoft Dynamics CRM executes form scripting both online and offline (within Microsoft Dynamics CRM for Outlook with Offline Access).

  Figure 1-3. A dialog box for adding client-side scripts to a form

  

  For server-side logic, Microsoft Dynamics CRM offers a plug-in model where you can create custom .NET assemblies that Microsoft Dynamics CRM executes based upon the defined trigger operations. For example, you can create an assembly that runs every time a user deactivates a lead or closes an opportunity. Because the plug-in model accepts .NET assemblies, developers can take advantage of the .NET Framework to accommodate almost any type of customization your organization might require. You can configure plug-ins to run either synchronously or asynchronously. In addition, you can even create plug-ins that run offline (disconnected from the server) in the Microsoft Dynamics CRM for Outlook software. Chapter 5, "Plug-ins," explains how to write plug-ins in exhaustive detail.

  Microsoft Dynamics CRM Workflow offers another option for implementing your own business logic. Unlike form scripting events and plug-ins, Microsoft Dynamics CRM Workflow includes a user interface that nondevelopers can use to set up and create their own automation processes. As a developer, this frees you from simple and common requests such as creating e-mail alerts and notifications. Figure 1-4 shows an example of a workflow rule created in the Web interface. Please refer to Working with Microsoft Dynamics CRM for an explanation of the Workflow Web interface.

  Figure 1-4. The Web-based workflow rule designer

  

  Even though the Workflow Web interface is quite powerful, undoubtedly your users will encounter scenarios where they can't design their business logic within the existing Web-based tools. Fortunately, Microsoft Dynamics CRM allows you to create custom workflow assemblies that your users can reference in the Web workflow designer to utilize in their rules. Just like plug-ins, workflow assemblies are fully .NET-compliant so that you have almost unlimited programming options to create complex and sophisticated business logic within workflow. Chapter 6, "Programming Workflow," explains the process for creating workflow assemblies within Microsoft Dynamics CRM. Chapter 12, "Advanced Workflow Programming," contains additional information about more complex programming customizations within workflow.

  Caution

  Many people assume that because Microsoft Dynamics CRM uses SQL Server, they can use database triggers for their business logic. This is not the case. If you want to create custom business logic related to database activity, you should plan to use one of the supported mechanisms such as form scripting events, plug-ins, or workflow instead of database triggers.

  Another powerful option to implement your custom business logic in Microsoft Dynamics CRM is to create custom Web pages that you embed in the user interface. You can create these pages using any technology that you prefer—Microsoft Dynamics CRM simply references your pages.

  How much control do we have over the user interface and branding?

  As we already mentioned, Microsoft Dynamics CRM offers Web-based customization tools that allow you to modify the various forms with your custom attributes and relationships. This form-customization tool is nice because nondevelopers can use it to make modifications to your system.

  However, you can perform more complex modifications to the user interface through the use of IFrames to implement your own custom user interface. While IFrames allow you to embed your custom Web pages within a Microsoft Dynamics CRM form, you can also modify the user interface by creating entirely new Web pages within the application. Users can access these custom Web pages through the primary navigation, or from buttons or links that you can add to existing records. Figure 1-5 shows the dialog to add an IFrame to a Microsoft Dynamics CRM form.

  Figure 1-5. Adding an IFrame to a form

  

  Please refer to Chapter 13, "Emulating the User Interface with ASP.NET Development," for information about creating new Web pages that work within Microsoft Dynamics CRM. Please refer to the book Working with Microsoft Dynamics CRM for an explanation of using the SiteMap and ISV.Config to modify the navigation model.

  Warning

  Even though you can technically modify the .aspx Web pages and the .js files in the Microsoft Dynamics CRM Web application, Microsoft considers these types of modifications unsupported. Instead you should use the other techniques outlined above to implement your custom business logic and user interface. Modifying the .aspx or .js files will probably cause unexpected (bad) behavior within your system.

  How do we deploy changes from one system to another?

  Microsoft Dynamics CRM includes a customization import and export utility in the Web interface so that you can easily move customizations from one system to another (such as moving from development to staging to production). Figure 1-6 shows some of the customization import and export utilities.

  Figure 1-6. Import and export customizations in Microsoft Dynamics CRM

  

  When you export customizations, Microsoft Dynamics CRM creates an XML file that contains all of the details of your entities. You can then take that customization file and import it into your target system. If you plan on frequent updates from one system to another, you can write code using the Microsoft Dynamics CRM Metadata API that will automatically export customizations from one system, import them into another system, and then publish those changes on the target system. If your system includes custom Web pages, you are responsible for deploying those files. Microsoft Dynamics CRM will not include your custom Web pages in the customizations import/export process. Chapter 9, "Deployment," takes a closer look at deploying your Microsoft Dynamics CRM customizations.

  Will our customizations upgrade when Microsoft releases a new version of the software?

  This question appears more frequently than probably all of the other questions combined, and understandably so! If you invest hundreds or thousands of hours customizing Microsoft Dynamics CRM, you want to know that you won't lose that investment when Microsoft releases the next version of the software. The key to answering this question is understanding what Microsoft means when they talk about "supported customizations." If Microsoft considers a customization supported, you can pretty safely assume that the customization will upgrade smoothly. We like to think of the SDK as the authoritative list of supported customizations, so if you follow the guidance outlined in that document you should not experience a problem.

  Caution

  While most supported customizations upgrade to future versions, Microsoft cannot guarantee this. For example, upgrading from Microsoft Dynamics CRM 1.2 to Microsoft Dynamics CRM 3.0 included a few breaking changes related to activities. However, Microsoft only makes these types of changes when the benefit of the new functionality clearly outweighs the cost of re-creating a customization.

  Having experienced multiple upgrades of Microsoft Dynamics CRM, we feel that Microsoft demonstrates a good track record of supporting customizations. For example, Microsoft completely revamped the asynchronous service for Microsoft Dynamics CRM 4.0, replacing 3.0 callouts with plug-ins in 4.0. The new 4.0 plug-in model included a large number of new benefits for developers and administrators, so plug-ins were a great architecture improvement over callouts. However, Microsoft included backward-compatibility support for Microsoft Dynamics CRM 3.0 callouts so that they can run in Microsoft Dynamics CRM 4.0 without any code changes.

  More Info

  Microsoft stated that they plan to release a new major release of Microsoft Dynamics CRM once every two years. In the interim, Microsoft will release smaller updates, hotfixes, and security updates along the way. However, many customers find it comforting that the major updates follow a periodic update schedule at a reasonable interval.

  Are role-based security permissions supported and configurable?

  Microsoft Dynamics CRM uses a role-based security model to determine the various privileges with the system. Each user can possess one or more security roles, and each security role defines the various privileges within the system. Administrators can configure and assign security roles through a Web interface. Figure 1-7 shows how an administrator can configure a security role in the application.

  Figure 1-7. The security role editor in Microsoft Dynamics CRM

  

  Please refer to Working with Microsoft Dynamics CRM for more information on setting up user security. For information about security within your programming customizations, please refer to Chapter 4, "Security," in this book.

  Does Microsoft Dynamics CRM support multiple languages and currencies?

  Yes, Microsoft Dynamics CRM is a truly global product that supports multiple languages and multiple currencies within a single deployment. Suppose that a sample organization has 500 users using Microsoft Dynamics CRM. That organization could theoretically set up their users as follows:

  • 100 users with US English and US Dollars

  • 100 users with Spanish and US Dollars

  • 100 users with French and Euros

  • 200 users with Spanish and Euros

  As a developer, you must understand how your custom code needs to accommodate these types of multiple language and multiple currency scenarios. Chapter 11, "Multilingual and Multi-Currency Applications," takes a look at programming for these situations within Microsoft Dynamics CRM.

  Will our programming customizations run offline?

  As we previously mentioned, Microsoft Dynamics CRM includes optional add-in software for Microsoft Office Outlook. This add-in software comes in two different versions:

  • Microsoft Dynamics CRM for Outlook

  • Microsoft Dynamics CRM for Outlook with Offline Access

  The offline-enabled version of this software allows your users to work while disconnected from the Microsoft Dynamics CRM server. As a developer, you have the option to create customizations that also run offline within Microsoft Dynamics CRM for Outlook. The SDK includes support for offline programming interfaces. Even if your customizations don't need to run offline, you should take some time to understand how users with the offline version of Microsoft Dynamics CRM for Outlook might interact with your server-based customizations. Please refer to Chapter 10, "Developing Offline Solutions," for more information on this topic.

  How do you recommend we set up a Microsoft Dynamics CRM development environment?

  When you're creating your Microsoft Dynamics CRM customizations, of course you don't want to develop and test your code in a production environment. You want to work in a sandbox system and then push your completed customizations to a different environment upon completion. Chapter 2, "Development Overview and Environment," examines different options for setting up a development system for your team of developers.