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.

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 ofthe 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 bookWorking 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.
  為了獲取更多的web-based定製化工具資訊，請參考Mike Snyder和Jim Steger編寫的Working with Microsoft Dynamics CRM(微軟出版社，2008)。這本書包含一些講解web-based定製化工具來修改資料結構的使用。
  

• The metadata API allows you to programmatically modify the database, including adding new attributes, entities, and so on. In this book, please refer toChapter 8, "Developing with the Metadata Service," for more information about programmatically modifying the database.
  使用元資料API來程式設計修改資料庫，主要包括增加屬性、實體等等。在這本書中，你可以參考第八章“元資料服務開發”， 從中獲取更多關於修改資料庫的程式設計方法。

• 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. 即使你能使用SQL Server來熟練的修改資料庫結構， 你也不要嘗試著這樣做，因為這樣可能會導致你的應用程式出現不可預料的後果，比如資料丟失或者系統崩潰。 CRM定製化工具盒元資料API提供很多資源方法來修改資料庫結構。

  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 releasedlogical 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. These database diagrams show the logical data relationships and the linked attributes between entities in Microsoft Office Visio format.
  另外一個相關聯出現頻繁的問題是“資料庫結構是什麼樣的？”雖然CRM使用的是SQL Server資料庫， 但是理論上你也不需要瀏覽它的資料結構或者檢視它。你可以用利用元資料API的介面來訪問資料實體。為了進一步的詳細說明CRM的資料結構，我們提供了資料庫結構圖。這些資料庫邏輯圖不包含實際的表結構，而是列舉了使用過程中的一些抽象的邏輯結構。下載地址

• In addition to the logical database diagrams, you can also view information about the entities and entity relationships through the Metadata browser athttp://< yourcrmserver>/< yourorganizationname >/sdk/list.aspx (seeFigure 1-1).
  除此之外，你還可以通過訪問http://< yourcrmserver >/< yourorganizationname>/sdk/list.aspx的方式來瀏覽實體和實體關係的資訊。如下圖：

  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.
  最後，你也可以用元資料服務API去檢視資料庫佳偶、屬性值、關係等等

  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 asaccount_base andaccount_extensionbase.
  如果你希望我能看到基礎資料庫結構，當然你也能開啟SQL Server來查詢。你可以看到CRM使用的清晰的命名來定是標準的基礎資料庫結構，例如account_base andaccount_extensionbase。

  How do we write custom code that gets data into and out of Microsoft Dynamics CRM?
  怎樣自定義程式碼獲取或者插入資料到CRM中？

  When you create custom code that needs to interact with Microsoft Dynamics CRM data, you should use one of two techniques:
  當你使用自定義程式碼的時候你需要和CRM資料關聯起來，你需要使用到下面2種技術：

  • 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.
    CrmService Web服務  它是一種操作驗證和支援普通的資料請求，例如增刪改查的API介面。

  • Filtered views Filtered views are SQL Server database views that your custom application can query to obtain read-only information about records.
    Filterd檢視  它是一種SQL Server資料檢視，你可以使用它來獲取一些只讀的資訊記錄。

  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 theCrmService Web service or a filtered view, Microsoft updates these interfaces with the corresponding database changes so that your code continues to run as-is.
  避免直接建立自定一定程式碼來訪問SQL Server資料庫----請堅持使用上述2種技術中的一種。

  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 bookWorking 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 toChapter 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 offersonSave,onLoad, andonChange 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 toChapter 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 toWorking 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 thosechanges 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 500users 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 toChapter 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.